Opengriffin

OpenGriffin

> The Claude-native personal agent that learns while you sleep — and lives in your Telegram.

[](LICENSE) [](https://www.python.org/) [](https://github.com/ManasaEdavalli-TharunSure/opengriffin/actions/workflows/ci.yml) [](https://core.telegram.org/bots)

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.

Run griffin card to turn any night's journal entry into a card like this — your shareable “here's what my agent did overnight.”

---

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:

1. 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.
2. 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 card makes 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 | ✅ 7 | ✅ 20+ | ✅ 5 | | BYO-key / multi-provider | ✅ 21 | ✅ (incl. 200+ via OpenRouter) | ✅ | ✅ | | 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 card renders 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.md is the environment, USER.md is the profile, SOUL.md is 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-whisper transcribes inbound voice notes; edge-tts speaks 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/) 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](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 + TELEGRAM_ALLOWED_USERS
uv run opengriffin doctor              # verify env + provider
uv run opengriffin run                 # start the bot

On first launch, OpenGriffin will:

1. Load .env from ~/.opengriffin/.env (or OPENGRIFFIN_HOME/.env if you've overridden the path).
2. Detect available providers (Claude Max → Anthropic → OpenAI → Ollama).
3. Create MEMORY.md, USER.md, SOUL.md, and a JOURNAL.md under ~/.opengriffin/memories/.
4. 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:

1. Create a bot / account / app on the platform → get a credential.
2. Find your own user id / handle / phone number on the platform.
3. Add credential + allowed-users env vars to ~/.opengriffin/.env.
4. (For some gateways) pip install 'opengriffin[]' to pull the platform SDK.
5. opengriffin doctor then opengriffin 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](docs/gateways/index.md#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](#telegram) | ⭐ easy | none | [docs/gateways/telegram.md](docs/gateways/telegram.md) | | [Discord](#discord) | ⭐ easy | [discord] | [docs/gateways/discord.md](docs/gateways/discord.md) | | [Slack](#slack) | ⭐⭐ medium | [slack] | [docs/gateways/slack.md](docs/gateways/slack.md) | | [Email](#email-imapsmtp) | ⭐⭐ medium | none (stdlib) | [docs/gateways/email.md](docs/gateways/email.md) | | [iMessage](#imessage-macos-only) | ⭐⭐ medium | macOS only | [docs/gateways/imessage.md](docs/gateways/imessage.md) | | [Matrix](#matrix) | ⭐⭐ medium | [matrix] | [docs/gateways/matrix.md](docs/gateways/matrix.md) | | [Signal](#signal) | ⭐⭐⭐ hard | signal-cli + Java 21+ | [docs/gateways/signal.md](docs/gateways/signal.md) |

Telegram

1. Create the bot — DM @BotFather → /newbot → pick display name → pick a username ending in bot → copy the 1234567890:AAH... token.
2. Get your user id — DM @userinfobot anything; it replies with your numeric id (e.g. 987654321).
3. Configure ~/.opengriffin/.env:

``bash 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 ``

1. Run — opengriffin doctor && opengriffin run. Open your bot in Telegram, send /start, you'll see the command menu. /whoami confirms 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

1. Create the bot — go to → New Application → Bot tab → Reset Token → copy.
2. Enable Message Content Intent under Privileged Gateway Intents (without this, the bot connects but never sees messages).
3. 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.
4. Get your user id — enable Developer Mode (User Settings → Advanced), right-click your name → Copy User ID.
5. Configure:

``bash DISCORD_BOT_TOKEN= # from step 1 DISCORD_ALLOWED_USERS= # comma-separated numeric user ids ``

1. Install + run — pip install 'opengriffin[discord]' then opengriffin 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.

1. Create the app — → Create New App → from scratch.
2. App-Level Token — Socket Mode → Enable → Generate App-Level Token with connections:write scope. Save the xapp-... token.
3. Bot Token Scopes under OAuth & Permissions: chat:write, im:history, im:read, im:write, channels:history, channels:read, app_mentions:read.
4. Event Subscriptions → Enable → subscribe to bot events: message.im, app_mention.
5. Install App to Workspace — copy the bot token (xoxb-...).
6. Configure:

``bash SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_ALLOWED_USERS= # comma-separated Slack user ids; empty = open to workspace ``

1. Install + run — pip install 'opengriffin[slack]' then opengriffin 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).

1. 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: → create one for Mail; use the 16-character output.
• iCloud: → Sign-In and Security → App-Specific Passwords.
• Other providers: usually IMAP 993 (SSL) + SMTP 587 (STARTTLS).

1. Configure:

```bash EMAILIMAPHOST=imap.gmail.com EMAILIMAPPORT=993 EMAILIMAPUSER=you@example.com EMAILIMAPPASS=app-password-here

EMAILSMTPHOST=smtp.gmail.com EMAILSMTPPORT=587 EMAILSMTPUSER=you@example.com # defaults to IMAPUSER if blank EMAILSMTPPASS=app-password-here # defaults to IMAPPASS if blank

EMAILFROMADDR=you@example.com EMAILALLOWEDSENDERS=trusted@example.com,boss@example.com ```

1. 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.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mr-tharun-sure
• Source: mr-tharun-sure/opengriffin
• License: Apache-2.0
• Homepage: https://opengriffin.com

Install and usage instructions live in the source repository linked above.