opengriffin
ManasaEdavalli-TharunSure/opengriffin
Self-evolving personal AI agent. Telegram-first. Multi-provider BYO key. Persistent memory, daily journal, skill graph, dream cycle. Free forever. Apache 2.0.
Instalação
npx convez-ai ManasaEdavalli-TharunSure/opengriffin1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
OpenGriffin
The Claude-native personal agent that learns while you sleep — and lives in your Telegram.
You wake up. Overnight, your agent has read yesterday back to itself, written down what it learned about you, caught its own failures, and proposed new skills — in a journal you can read over coffee. That nightly self-improvement loop, built natively on the Claude Agent SDK — real skills, MCP, hooks, resumable sessions, not a reimplementation — is what OpenGriffin is. It lives in your Telegram, runs entirely on your own machine, and works with any of 21 model providers on your own key.
How it's different
The personal-agent space is crowded — Nous Research's Hermes Agent, OpenClaw, and QwenPaw all do self-evolving, multi-messenger, BYO-key, and local-first. OpenGriffin doesn't claim to out-feature them. Two things are genuinely ours:
- It's the Claude-native one. OpenGriffin runs on the Claude Agent SDK itself — your skills are real Claude Code skills under
~/.claude/skills/(shared with Claude Code), MCP servers, hooks, and resumable sessions all work as-is. The others reimplement an agent loop; OpenGriffin is the Claude loop, wearing a Telegram face. - The journal is a readable, shareable artifact. The nightly loop doesn't just mutate hidden state — it writes you a page you can read, and
griffin cardmakes it shareable. "Learns while you sleep" you can actually see.
| OpenGriffin | Hermes (Nous) | OpenClaw | QwenPaw | |
|---|---|---|---|---|
| Built on the Claude Agent SDK (native skills / MCP / hooks / sessions) | ✅ | ❌ own runtime | ❌ own runtime | ❌ Qwen / AgentScope |
| Readable nightly journal you can screenshot & share | ✅ griffin card | ❌ | ❌ | ❌ |
| Telegram-native onboarding (one messenger, ~2 min) | ✅ | one of many | one of many | one of many |
| Self-evolving skills | ✅ | ✅ | ◑ | ✅ |
| Multi-messenger gateways | ✅ 7 | ✅ 10+ | ✅ 50+ | ✅ |
| BYO-key / multi-provider | ✅ 21 | ✅ 200+ | ✅ | ✅ |
| Local-first / no backend | ✅ | ✅ | ✅ | ✅ |
| Acts proactively (cron / triggers) | ✅ | ✅ | ✅ heartbeat | ✅ |
| License | Apache-2.0 | MIT | MIT | OSS |
Comparison reflects publicly documented features as of mid-2026. Hermes, OpenClaw, and QwenPaw are excellent projects with far larger communities — this table is about fit, not size.
Why OpenGriffin
- Self-evolving skill graph. The agent authors, edits, and retires its own skills at runtime. No redeploy. New capabilities ship inside a conversation.
- Daily journal at 4:30 AM. Every conversation, decision, and tool call is appended to a structured journal. A nightly self-improvement loop reads yesterday's entries, summarizes them, and proposes new skills — then
griffin cardrenders the entry into a shareable image. - 21 AI providers, BYO key. Claude Max OAuth, Anthropic, OpenAI, OpenRouter, Azure, Gemini, Mistral, Cohere, Groq, Together, Fireworks, DeepSeek, HuggingFace, Perplexity, xAI, Bedrock, Cerebras, NVIDIA NIM, Lambda Labs, Novita, Ollama. Switch with one env var.
- Persistent memory: MEMORY / USER / SOUL. Three flat markdown files load fresh into every session.
MEMORY.mdis the environment,USER.mdis the profile,SOUL.mdis the voice. - Multi-surface. Telegram is the front door, but the same brain answers via CLI, webhooks, and voice notes.
- Skill auto-discovery. Drop a markdown file into
~/.claude/skills/, and the agent picks it up on next turn — no registry, no config. - Voice round-trip.
faster-whispertranscribes inbound voice notes;edge-ttsspeaks replies in the user's preferred neural voice. - Browser automation via Playwright MCP. Screenshots, scraping, end-to-end clicks. The agent can drive a real Chromium.
- Kanban built in. Multiple agent workers claim, block, and complete tasks against a shared board. Long plans get parallelized.
- Checkpoints + rollback. Conversation snapshots survive crashes. The agent can replay or branch off any prior point.
- Approval inline buttons. Risky actions ask first via Telegram inline keyboards. Confirm or deny with a tap; nothing destructive runs unsupervised.
The 12 killer features
| # | Feature | What it does |
|---|---|---|
| 1 | Skill Hub | Install community skills directly from GitHub URLs with license auto-check, signing, and reputation tracking by outcome, not stars. |
| 2 | Echo Memory + Receipts | Autobiographical hierarchical memory (vivid → recent → fading → ancient). Every recalled fact comes with a citation receipt like [echo:vivid/2026-05-06:abc123] linking back to the source session. |
| 3 | Ambient Trigger Mesh | Compose triggers from cron, webhook, or polled URLs → optional LLM yes/no predicate → skill or prompt action. The agent acts before you notice the problem. |
| 4 | Agent Pods | Multiple agent personas with distinct SOUL files but shared memory. Add them to a group chat, watch them debate, converge. |
| 5 | Agentic Wallet (x402) | The agent can pay for things — sandbox wallet + per-skill spending caps + Telegram inline-button approval. Pays only after you tap. |
| 6 | Soul Sync | Mines your past chats for writing voice (sentence length, contractions, recurring phrases). Builds a VOICE.md the agent uses to draft as you. |
| 7 | Provider Routing Auctions | Lightweight classifier scores each prompt 0–3, routes to cheapest tier that can answer. Heavy thinking goes to Claude Opus / o1; "summarize this" goes to Groq for $0.0001. |
| 8 | Drift Detection | Nightly scan of USER.md against recent journal entries. Flags contradictions: "3 months ago you told me you hated meetings; today you scheduled five." |
| 9 | Self-Healing Skills | When a skill fails 3+ times in a week, the agent debugs it, proposes an updated SKILL.md, and asks for approval before applying. |
| 10 | Skill Graph Strategy | Reads your usage to recommend missing skills based on co-occurrence, flags never-used skills, and surfaces your top-used ones. |
| 11 | Memory Receipts | Every claim the agent makes can be traced. Tap a receipt token to see the exact session and turn that established the fact. |
| 12 | Reputation Ledger | Signed JSON-LD profile (/u/<handle>) showing task count, approval rate, specialties, authored skills. A2A-discoverable for agent-to-agent trust. |
The frontier modules — Personal World Model, Living Twin, Verifiable Refusal Proofs + Provable Forgetting, Generative Live UI, Mesa-Cognition Supervisor, Capability-Scoped Skill Leasing, Personal Causal Layer, and the Adversarial Improvement Market — ship in addition. See docs/frontier.md for the design notes.
Nightly auto-loops
Every night, OpenGriffin runs without prompting:
| Time | Job | What |
|---|---|---|
| 04:00 | Daily session reset | Archives sessions; preserves the next morning a fresh slate while keeping recall |
| 04:30 | Self-improvement | Reads yesterday's transcripts, consolidates MEMORY / USER, writes JOURNAL.md, suggests skills |
| 04:45 | Echo memory consolidation | Rolls older sessions up the time hierarchy (vivid → recent → fading → ancient) |
| 05:00 | Drift detection | Surfaces contradictions in user model / behavior |
| 05:15 | World model retrain | Rebuilds the personal forecast from the event log |
| 05:30 | Mesa-cognition report | Scores the agent's own behavior for drift signatures |
| 05:45 | Causal discovery | Walks the event log for new cause→effect proposals |
| Sun 05:00 | Voice card refresh | Re-extracts writing-voice profile from past week's chats |
| per-trigger | Ambient triggers | All cron-based triggers from triggers.json |
Quick start
# One-line install (clones, runs uv sync, writes a launchctl/systemd unit)
curl -fsSL https://raw.githubusercontent.com/ManasaEdavalli-TharunSure/opengriffin/main/scripts/install.sh | bash
# Or from source
git clone https://github.com/ManasaEdavalli-TharunSure/opengriffin.git
cd opengriffin
uv sync --all-extras
cp .env.example ~/.opengriffin/.env # fill in TELEGRAM_BOT_TOKEN
uv run opengriffin doctor # verify env + provider
uv run opengriffin run # start the bot
On first launch, OpenGriffin will:
- Load
.envfrom~/.opengriffin/.env(orOPENGRIFFIN_HOME/.envif you've overridden the path). - Detect available providers (Claude Max → Anthropic → OpenAI → Ollama).
- Create
MEMORY.md,USER.md,SOUL.md, and aJOURNAL.mdunder~/.opengriffin/memories/. - Drop you into a chat where the agent can already use tools.
# Use a specific provider
OPENGRIFFIN_PROVIDER=openrouter opengriffin run
# Diagnose the install
opengriffin doctor
# Run the nightly self-improvement loop manually
opengriffin improve
# Turn last night's journal entry into a shareable card (SVG, + PNG with --png)
opengriffin card --png
# Migrate state from a prior agent runtime (see docs/migration.md)
opengriffin migrate from-hermes
First-time setup — pick your messenger
OpenGriffin runs the same brain across 7 free-pricing platforms. You create the bot in whichever messenger you use, paste its credential into your local .env, and run the agent on your own machine. There is no hosted onboarding, no waitlist, no account — you own the keys, the data, and the process.
The shared steps for every gateway are:
- Create a bot / account / app on the platform → get a credential.
- Find your own user id / handle / phone number on the platform.
- Add credential + allowed-users env vars to
~/.opengriffin/.env. - (For some gateways)
pip install 'opengriffin[<gateway>]'to pull the platform SDK. opengriffin doctorthenopengriffin run.
You also need at least one model key in .env. Any of these is enough:
ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY, GEMINI_API_KEY,
# GROQ_API_KEY, DEEPSEEK_API_KEY, …
OPENGRIFFIN_PROVIDER=anthropic # must match the key you set
You can enable multiple gateways at once — the bot starts every gateway whose required env vars are present. They share one memory, one kanban, one set of MCP servers. See Cross-platform identity to link your accounts.
⚠️ Across every gateway: leaving the
*_ALLOWED_USERS(or equivalent) env var empty makes the bot open to anyone who finds it. Set it to your own id while testing.
| Platform | Difficulty | Extras needed | Detailed doc |
|---|---|---|---|
| Telegram | ⭐ easy | none | docs/gateways/telegram.md |
| Discord | ⭐ easy | [discord] | docs/gateways/discord.md |
| Slack | ⭐⭐ medium | [slack] | docs/gateways/slack.md |
| ⭐⭐ medium | none (stdlib) | docs/gateways/email.md | |
| iMessage | ⭐⭐ medium | macOS only | docs/gateways/imessage.md |
| Matrix | ⭐⭐ medium | [matrix] | docs/gateways/matrix.md |
| Signal | ⭐⭐⭐ hard | signal-cli + Java 21+ | docs/gateways/signal.md |
Telegram
- Create the bot — DM @BotFather →
/newbot→ pick display name → pick a username ending inbot→ copy the1234567890:AAH...token. - Get your user id — DM @userinfobot anything; it replies with your numeric id (e.g.
987654321). - Configure
~/.opengriffin/.env:TELEGRAM_BOT_TOKEN=1234567890:AAH...your-token-here TELEGRAM_ALLOWED_USERS=987654321 # your numeric user id TELEGRAM_HOME_CHANNEL=987654321 # default destination for cron + proactive messages - Run —
opengriffin doctor && opengriffin run. Open your bot in Telegram, send/start, you'll see the command menu./whoamiconfirms auth.
Optional BotFather steps while you're there: /setprivacy (Enable = DM/mention-only; Disable = sees all group messages), /setdescription, /setuserpic, /setcommands (or use the setMyCommands curl snippet in the detailed doc).
Discord
- Create the bot — go to https://discord.com/developers/applications → New Application → Bot tab → Reset Token → copy.
- Enable Message Content Intent under Privileged Gateway Intents (without this, the bot connects but never sees messages).
- Invite it to your server — OAuth2 → URL Generator → scopes:
bot,applications.commands; permissions:Send Messages,Read Message History,Use Slash Commands. Open the generated URL and pick your server. - Get your user id — enable Developer Mode (User Settings → Advanced), right-click your name → Copy User ID.
- Configure:
DISCORD_BOT_TOKEN= # from step 1 DISCORD_ALLOWED_USERS= # comma-separated numeric user ids - Install + run —
pip install 'opengriffin[discord]'thenopengriffin run. DM the bot or @-mention it in a channel.
Discord caps messages at 2000 chars; OpenGriffin auto-splits longer replies. Voice channels and slash commands are not yet wired.
Slack
Uses Slack Bolt Socket Mode — no public webhook URL needed.
- Create the app — https://api.slack.com/apps → Create New App → from scratch.
- App-Level Token — Socket Mode → Enable → Generate App-Level Token with
connections:writescope. Save thexapp-...token. - Bot Token Scopes under OAuth & Permissions:
chat:write,im:history,im:read,im:write,channels:history,channels:read,app_mentions:read. - Event Subscriptions → Enable → subscribe to bot events:
message.im,app_mention. - Install App to Workspace — copy the bot token (
xoxb-...). - Configure:
SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_ALLOWED_USERS= # comma-separated Slack user ids; empty = open to workspace - Install + run —
pip install 'opengriffin[slack]'thenopengriffin run. DM the bot or @-mention it in any channel where it's been added.
Threading works automatically — replies stay in the thread they came from. Effective message limit is ~40k chars.
Email (IMAP/SMTP)
Stdlib only — no extra deps. IMAP polling for inbound, SMTP for outbound. Great for long-form async work and webhook-driven inbound (Zapier/Make → email → bot).
- Get IMAP + SMTP credentials. For Gmail/Workspace or iCloud (with 2FA on, which is the default), you need an App Password, not your account password:
- Gmail: https://myaccount.google.com/apppasswords → create one for Mail; use the 16-character output.
- iCloud: https://account.apple.com/account/manage → Sign-In and Security → App-Specific Passwords.
- Other providers: usually IMAP 993 (SSL) + SMTP 587 (STARTTLS).
- Configure:
EMAIL_IMAP_HOST=imap.gmail.com EMAIL_IMAP_PORT=993 EMAIL_IMAP_USER=you@example.com EMAIL_IMAP_PASS=app-password-here EMAIL_SMTP_HOST=smtp.gmail.com EMAIL_SMTP_PORT=587 EMAIL_SMTP_USER=you@example.com # defaults to IMAP_USER if blank EMAIL_SMTP_PASS=app-password-here # defaults to IMAP_PASS if blank EMAIL_FROM_ADDR=you@example.com EMAIL_ALLOWED_SENDERS=trusted@example.com,boss@example.com - Run —
opengriffin run. Email the bot from an allowed sender. Polling cadence is 60s (no IMAP IDLE in stdlib); threading is preserved via message-id chains.
iMessage (macOS only)
Reads ~/Library/Messages/chat.db directly; sends via AppleScript through Messages.app.
- Grant Full Disk Access to your terminal: System Settings → Privacy & Security → Full Disk Access → add Terminal.app / iTerm / whatever you launch the bot from. Restart the terminal session after granting.
- Grant Automation access to Messages.app: System Settings → Privacy & Security → Automation → your terminal → check Messages.
- Identify the handles you'll allow — open a Messages.app conversation; the handle in the address bar (e.g.
+15551234567oryou@example.com) is what you'll list. - Configure (allowed handles are required — there is no open mode for iMessage):
IMESSAGE_ALLOWED_HANDLES=+15551234567,boss@example.com IMESSAGE_DB_PATH= # default ~/Library/Messages/chat.db - Run —
opengriffin run. The gateway pollschat.dbevery 3 seconds; replies appear as if they came from your iMessage account.
macOS only. Group chats are not yet supported.
Matrix
Works with any Matrix homeserver — matrix.org (free public), self-hosted Synapse, Beeper, Element, etc. End-to-end encryption via Olm/Megolm is supported.
- Create a bot account — easiest is to register a fresh username at https://element.io (e.g.
mybot:matrix.org). For self-hosted Synapse, useregister_new_matrix_user. - (Optional) Get an access token instead of storing the password — Element → Settings → Help & About → Advanced → Access Token. Saves you re-login.
- Configure:
MATRIX_HOMESERVER=https://matrix.org MATRIX_USER_ID=@mybot:matrix.org MATRIX_PASSWORD= # OR set MATRIX_ACCESS_TOKEN MATRIX_ACCESS_TOKEN= MATRIX_ALLOWED_USERS=@you:matrix.org,@boss:matrix.org - Install + run —
pip install 'opengriffin[matrix]'(the[e2e]extra is included; drop it for plaintext-only) thenopengriffin run. Open a DM with your bot's Matrix handle.
For E2E: the bot's device must be verified on first contact (click verify in Element), otherwise accept unverified sessions in your client settings. mautrix bridges to Telegram/Discord/Signal/WhatsApp work — the bot can sit in a bridged room.
Signal
Hardest of the gateways — there's no public Signal API, so OpenGriffin wraps signal-cli which reverse-engineers the protocol. JVM-based; needs Java 21+.
- Install —
brew install signal-cli(macOS) or grab the release JAR from GitHub. Confirm Java 21+ withjava -version. - Register a phone number that isn't already on Signal (Signal only allows one device per number for primary registration):
If you hitsignal-cli -a +15551234567 register signal-cli -a +15551234567 verify <code-from-sms>Captcha required, solve at https://signalcaptchas.org/registration/generate.html and pass--captcha <url>. - Test sending manually to confirm signal-cli works end-to-end:
echo "test" | signal-cli -a +15551234567 send +15555555555 - Configure:
SIGNAL_NUMBER=+15551234567 # the bot's number SIGNAL_ALLOWED_NUMBERS=+15555555555,+15556666666 - Run —
opengriffin run. First message after a quiet period can lag a few seconds (JVM cold start).
If signal-cli pain outweighs the value, use Matrix with the Signal bridge instead.
After your bot is running
Once any gateway is up:
- Send
/start(Telegram/Discord/Slack/Matrix) or any plain message (Email/iMessage/Signal) — you should get a typing indicator and a reply. /whoami— confirms the gateway recognised your user id./model openai gpt-4o-mini— per-chat provider switch./journal— shows today's auto-journal entry. (griffin cardrenders it into a shareable image.)/usageand/insights— token and cost breakdown across providers.
Full command reference, voice support, group-chat behavior, and per-gateway troubleshooting live in docs/gateways/ — one file per platform.
Provider matrix
One env var (OPENGRIFFIN_PROVIDER) picks the backend. Full features (skills, MCP, hooks, sessions) on Claude; chat + function-calling fallbacks on every other provider.
| Provider | OPENGRIFFIN_PROVIDER | Required env | Default model |
|---|---|---|---|
| Claude (Max OAuth) | claude | none — uses ~/.claude/.credentials.json | claude-opus-4-7 |
| Anthropic API | anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 |
| OpenAI | openai | OPENAI_API_KEY | gpt-4o |
| OpenRouter | openrouter | OPENROUTER_API_KEY | anthropic/claude-opus-4 |
| Azure OpenAI | azure | AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT | gpt-4o |
| Google Gemini | gemini | GEMINI_API_KEY | gemini-2.5-pro |
| Mistral | mistral | MISTRAL_API_KEY | mistral-large-latest |
| Cohere | cohere | COHERE_API_KEY | command-r-plus |
| Groq | groq | GROQ_API_KEY | llama-3.3-70b-versatile |
| Together AI | together | TOGETHER_API_KEY | meta-llama/Llama-3.3-70B-Instruct-Turbo |
| Fireworks AI | fireworks | FIREWORKS_API_KEY | accounts/fireworks/models/llama-v3p3-70b-instruct |
| DeepSeek | deepseek | DEEPSEEK_API_KEY | deepseek-chat |
| HuggingFace | huggingface | HF_TOKEN | meta-llama/Llama-3.3-70B-Instruct |
| Perplexity | perplexity | PERPLEXITY_API_KEY | sonar-pro |
| xAI (Grok) | xai | XAI_API_KEY | grok-2-latest |
| AWS Bedrock | bedrock | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION | anthropic.claude-sonnet-4-6 |
| Cerebras | cerebras | CEREBRAS_API_KEY | llama3.3-70b |
| NVIDIA NIM | nvidia | NVIDIA_API_KEY | meta/llama-3.1-405b-instruct |
| Lambda Labs | lambda | LAMBDA_API_KEY | hermes-3-llama-3.1-405b-fp8 |
| Novita | novita | NOVITA_API_KEY | meta-llama/llama-3.1-70b-instruct |
| Ollama (local) | ollama | OLLAMA_HOST, OLLAMA_MODEL | llama3.1 |
The OpenAI-compatible providers all share a single connector under the hood — adding a new one is a short dict entry in providers/openai_compatible.py:FLAVORS.
Configuration
Copy .env.example to ~/.opengriffin/.env and fill in only the keys you intend to use.
| Variable | Purpose |
|---|---|
OPENGRIFFIN_HOME | Override the runtime state root. Default ~/.opengriffin. |
OPENGRIFFIN_PROVIDER | Backend selection (see matrix above). Default claude. |
TELEGRAM_BOT_TOKEN | BotFather token. Required to talk on Telegram. |
TELEGRAM_ALLOWED_USERS | Comma-separated Telegram user IDs. Empty = open to anyone. |
TELEGRAM_HOME_CHANNEL | Default destination for cron output and proactive messages. |
FAL_KEY | Enables fal.ai image generation tool. |
WEBHOOK_PORT | HTTP port for the webhook gateway. Default 8645. |
SELF_IMPROVE_CRON | Cron expression for the nightly loop. Default 30 4 * * *. |
CLAUDE_BOT_DISABLE_PLAYWRIGHT | Set to 1 to skip browser automation. |
Architecture
OpenGriffin is one Python package, one long-lived process, and a handful of orthogonal modules. Each does one thing and is replaceable.
src/opengriffin/
├── bot.py # Telegram entrypoint; routes messages to the agent loop
├── cli.py # `opengriffin` / `griffin` Typer CLI
├── paths.py # Canonical filesystem layout (OPENGRIFFIN_HOME-rooted)
├── providers/ # 21 pluggable AI backends
│ ├── claude.py # Claude Agent SDK (default; full features)
│ ├── anthropic_api.py # Direct Anthropic API
│ ├── gemini.py # Google Gemini
│ ├── cohere.py # Cohere
│ ├── bedrock.py # AWS Bedrock
│ ├── ollama.py # Local models via Ollama
│ └── openai_compatible.py # 15 OpenAI-compatible flavors share one connector
├── memory.py # MEMORY.md / USER.md / SOUL.md read/edit/cap logic
├── recall.py # Long-term recall across journal entries
├── echo_memory.py # Hierarchical autobiographical memory + citation receipts
├── topics.py # Topic extraction and clustering for ambient memory
├── cron.py # APScheduler bridge — agent-authored cron jobs
├── voice.py # Whisper STT + edge-tts TTS pipeline
├── webhooks.py # aiohttp gateway for inbound HTTP triggers
├── kanban.py # Shared task board (claim / block / complete)
├── tools.py # Tool registry: image gen, journal, kanban, send_message…
├── self_improve.py # Skill authorship + nightly 4:30 AM loop
├── checkpoints.py # Conversation snapshots; crash recovery + rollback
├── approvals.py # Inline-keyboard confirm gate for destructive actions
├── redact.py # Secret scrubbing on inbound + outbound payloads
├── world_model.py # Personal predictive forecaster
├── twin.py # Counterfactual sub-agent (Living Twin)
├── proofs.py # Verifiable refusal + provable forgetting
├── gen_ui.py # Generative UI with preference learning
├── mesa.py # Mesa-cognition drift supervisor
├── skill_lease.py # Capability-scoped skill leases (A2A)
├── causal.py # Personal causal data layer
└── adversarial.py # Adversarial improvement market
Where state lives
| Path | Contents |
|---|---|
~/.opengriffin/memories/MEMORY.md | Environment + project facts. Loaded into every system prompt. Capped at 2,200 chars. |
~/.opengriffin/memories/USER.md | Stable user profile + preferences. Capped at 1,375 chars. |
~/.opengriffin/memories/SOUL.md | The bot's voice and tone — edited to set personality. |
~/.opengriffin/memories/JOURNAL.md | Append-only daily log of conversations and tool calls. |
~/.opengriffin/sessions.json | Per-chat session resume state. |
~/.opengriffin/kanban.json | Shared task board state. |
~/.opengriffin/jobs.json | Scheduled jobs the agent has authored. |
~/.opengriffin/checkpoints/ | Crash-recovery snapshots of in-flight conversations. |
~/.opengriffin/usage.jsonl | Per-call token + dollar accounting. |
~/.claude/skills/ | Self-evolving skill files. Auto-discovered each turn. Shared with other Claude Code installs. |
Override the root by setting OPENGRIFFIN_HOME before launch.
Skills
Skills are markdown files with frontmatter. The agent reads them on demand and can also write new ones during a conversation.
---
name: morning-briefing
description: Compile calendar + journal + weather into a 5-line digest.
trigger: /briefing OR mornings at 7:30 AM
---
1. Pull today's calendar from Google.
2. Read the last journal entry.
3. Grab weather for the user's location.
4. Format as 5 lines, no preamble.
The agent decides when a skill is relevant. Users can invoke them with /skill-name. The self_improve module governs creation, editing, and deletion — every change is journaled.
Built by itself
This README, the JOURNEY.md, the landing site at apps/web, and the dashboard module were drafted by a running OpenGriffin instance.
The audit trail is in dogfood/:
- Kanban tasks.
dogfood/kanban.jsonrecords each artifact — created, claimed, blocked, completed — with timestamps and the worker's session ID. - Journal entries.
dogfood/journal/holds the daily log entries the agent wrote while working. They include tool calls, file diffs, and the agent's own reasoning.
A self-authored repo where you cannot trace the work back to a real run is not dogfooding, it's marketing. The chain of evidence is intentional.
Contributing
We welcome PRs of every size — typo fixes, new providers, new tools, new skills. See CONTRIBUTING.md for:
- Local dev setup (
uv,ruff,pytest). - The skill authoring guide.
- How to add a new provider (a short dict entry for OpenAI-compatible ones).
- The PR review bar (tests + a journal entry from a real session showing it works).
If you are unsure whether something is in-scope, open a discussion first — the project is opinionated about staying small at the core.
License
OpenGriffin is released under the Apache License 2.0. You are free to fork, embed, modify, and run it commercially. A copy of the license must travel with redistributions.
OpenGriffin is not affiliated with Anthropic, OpenAI, Google, Microsoft, AWS, Mistral, Cohere, Groq, or any other provider listed above. "Claude" is a trademark of Anthropic, PBC.