convez.ai
MCP Server
ManasaEdavalli-TharunSure

opengriffin

ManasaEdavalli-TharunSure/opengriffin

Ver no GitHub
BomPluginScore · de 0 a 100

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/opengriffin

1 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

Estrelas
1
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 3 dias
Versão
v0.1.0
Issues abertas
26
Contribuidores
3

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.

License: Apache 2.0 Python 3.11+ CI 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:

  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.
OpenGriffinHermes (Nous)OpenClawQwenPaw
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 manyone of manyone 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✅
LicenseApache-2.0MITMITOSS

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

#FeatureWhat it does
1Skill HubInstall community skills directly from GitHub URLs with license auto-check, signing, and reputation tracking by outcome, not stars.
2Echo Memory + ReceiptsAutobiographical 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.
3Ambient Trigger MeshCompose triggers from cron, webhook, or polled URLs → optional LLM yes/no predicate → skill or prompt action. The agent acts before you notice the problem.
4Agent PodsMultiple agent personas with distinct SOUL files but shared memory. Add them to a group chat, watch them debate, converge.
5Agentic Wallet (x402)The agent can pay for things — sandbox wallet + per-skill spending caps + Telegram inline-button approval. Pays only after you tap.
6Soul SyncMines your past chats for writing voice (sentence length, contractions, recurring phrases). Builds a VOICE.md the agent uses to draft as you.
7Provider Routing AuctionsLightweight 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.
8Drift DetectionNightly scan of USER.md against recent journal entries. Flags contradictions: "3 months ago you told me you hated meetings; today you scheduled five."
9Self-Healing SkillsWhen a skill fails 3+ times in a week, the agent debugs it, proposes an updated SKILL.md, and asks for approval before applying.
10Skill Graph StrategyReads your usage to recommend missing skills based on co-occurrence, flags never-used skills, and surfaces your top-used ones.
11Memory ReceiptsEvery claim the agent makes can be traced. Tap a receipt token to see the exact session and turn that established the fact.
12Reputation LedgerSigned 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:

TimeJobWhat
04:00Daily session resetArchives sessions; preserves the next morning a fresh slate while keeping recall
04:30Self-improvementReads yesterday's transcripts, consolidates MEMORY / USER, writes JOURNAL.md, suggests skills
04:45Echo memory consolidationRolls older sessions up the time hierarchy (vivid → recent → fading → ancient)
05:00Drift detectionSurfaces contradictions in user model / behavior
05:15World model retrainRebuilds the personal forecast from the event log
05:30Mesa-cognition reportScores the agent's own behavior for drift signatures
05:45Causal discoveryWalks the event log for new cause→effect proposals
Sun 05:00Voice card refreshRe-extracts writing-voice profile from past week's chats
per-triggerAmbient triggersAll 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:

  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[<gateway>]' 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 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.

PlatformDifficultyExtras neededDetailed doc
Telegram⭐ easynonedocs/gateways/telegram.md
Discord⭐ easy[discord]docs/gateways/discord.md
Slack⭐⭐ medium[slack]docs/gateways/slack.md
Email⭐⭐ mediumnone (stdlib)docs/gateways/email.md
iMessage⭐⭐ mediummacOS onlydocs/gateways/imessage.md
Matrix⭐⭐ medium[matrix]docs/gateways/matrix.md
Signal⭐⭐⭐ hardsignal-cli + Java 21+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:
    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
    
  4. 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 https://discord.com/developers/applications → 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:
    DISCORD_BOT_TOKEN=                     # from step 1
    DISCORD_ALLOWED_USERS=                 # comma-separated numeric user ids
    
  6. 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 — https://api.slack.com/apps → 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:
    SLACK_BOT_TOKEN=xoxb-...
    SLACK_APP_TOKEN=xapp-...
    SLACK_ALLOWED_USERS=                   # comma-separated Slack user ids; empty = open to workspace
    
  7. 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:
  2. 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
    
  3. 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.

  1. 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.
  2. Grant Automation access to Messages.app: System Settings → Privacy & Security → Automation → your terminal → check Messages.
  3. Identify the handles you'll allow — open a Messages.app conversation; the handle in the address bar (e.g. +15551234567 or you@example.com) is what you'll list.
  4. 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
    
  5. Run — opengriffin run. The gateway polls chat.db every 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.

  1. Create a bot account — easiest is to register a fresh username at https://element.io (e.g. mybot:matrix.org). For self-hosted Synapse, use register_new_matrix_user.
  2. (Optional) Get an access token instead of storing the password — Element → Settings → Help & About → Advanced → Access Token. Saves you re-login.
  3. 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
    
  4. Install + run — pip install 'opengriffin[matrix]' (the [e2e] extra is included; drop it for plaintext-only) then opengriffin 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+.

  1. Install — brew install signal-cli (macOS) or grab the release JAR from GitHub. Confirm Java 21+ with java -version.
  2. Register a phone number that isn't already on Signal (Signal only allows one device per number for primary registration):
    signal-cli -a +15551234567 register
    signal-cli -a +15551234567 verify <code-from-sms>
    
    If you hit Captcha required, solve at https://signalcaptchas.org/registration/generate.html and pass --captcha <url>.
  3. Test sending manually to confirm signal-cli works end-to-end:
    echo "test" | signal-cli -a +15551234567 send +15555555555
    
  4. Configure:
    SIGNAL_NUMBER=+15551234567                     # the bot's number
    SIGNAL_ALLOWED_NUMBERS=+15555555555,+15556666666
    
  5. 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 card renders it into a shareable image.)
  • /usage and /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.

ProviderOPENGRIFFIN_PROVIDERRequired envDefault model
Claude (Max OAuth)claudenone — uses ~/.claude/.credentials.jsonclaude-opus-4-7
Anthropic APIanthropicANTHROPIC_API_KEYclaude-sonnet-4-6
OpenAIopenaiOPENAI_API_KEYgpt-4o
OpenRouteropenrouterOPENROUTER_API_KEYanthropic/claude-opus-4
Azure OpenAIazureAZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINTgpt-4o
Google GeminigeminiGEMINI_API_KEYgemini-2.5-pro
MistralmistralMISTRAL_API_KEYmistral-large-latest
CoherecohereCOHERE_API_KEYcommand-r-plus
GroqgroqGROQ_API_KEYllama-3.3-70b-versatile
Together AItogetherTOGETHER_API_KEYmeta-llama/Llama-3.3-70B-Instruct-Turbo
Fireworks AIfireworksFIREWORKS_API_KEYaccounts/fireworks/models/llama-v3p3-70b-instruct
DeepSeekdeepseekDEEPSEEK_API_KEYdeepseek-chat
HuggingFacehuggingfaceHF_TOKENmeta-llama/Llama-3.3-70B-Instruct
PerplexityperplexityPERPLEXITY_API_KEYsonar-pro
xAI (Grok)xaiXAI_API_KEYgrok-2-latest
AWS BedrockbedrockAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGIONanthropic.claude-sonnet-4-6
CerebrascerebrasCEREBRAS_API_KEYllama3.3-70b
NVIDIA NIMnvidiaNVIDIA_API_KEYmeta/llama-3.1-405b-instruct
Lambda LabslambdaLAMBDA_API_KEYhermes-3-llama-3.1-405b-fp8
NovitanovitaNOVITA_API_KEYmeta-llama/llama-3.1-70b-instruct
Ollama (local)ollamaOLLAMA_HOST, OLLAMA_MODELllama3.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.

VariablePurpose
OPENGRIFFIN_HOMEOverride the runtime state root. Default ~/.opengriffin.
OPENGRIFFIN_PROVIDERBackend selection (see matrix above). Default claude.
TELEGRAM_BOT_TOKENBotFather token. Required to talk on Telegram.
TELEGRAM_ALLOWED_USERSComma-separated Telegram user IDs. Empty = open to anyone.
TELEGRAM_HOME_CHANNELDefault destination for cron output and proactive messages.
FAL_KEYEnables fal.ai image generation tool.
WEBHOOK_PORTHTTP port for the webhook gateway. Default 8645.
SELF_IMPROVE_CRONCron expression for the nightly loop. Default 30 4 * * *.
CLAUDE_BOT_DISABLE_PLAYWRIGHTSet 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

PathContents
~/.opengriffin/memories/MEMORY.mdEnvironment + project facts. Loaded into every system prompt. Capped at 2,200 chars.
~/.opengriffin/memories/USER.mdStable user profile + preferences. Capped at 1,375 chars.
~/.opengriffin/memories/SOUL.mdThe bot's voice and tone — edited to set personality.
~/.opengriffin/memories/JOURNAL.mdAppend-only daily log of conversations and tool calls.
~/.opengriffin/sessions.jsonPer-chat session resume state.
~/.opengriffin/kanban.jsonShared task board state.
~/.opengriffin/jobs.jsonScheduled jobs the agent has authored.
~/.opengriffin/checkpoints/Crash-recovery snapshots of in-flight conversations.
~/.opengriffin/usage.jsonlPer-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.json records 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.

Ver o original no GitHub

Bom para

Relacionados