Open Claudia

Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat.

Send text, voice notes, screenshots, and files from your phone. Your chosen AI agent works on your projects, remembers what it learned, and reports back.

Features

Channels & backends

• Multi-channel — run the same bot on Telegram, Kazee Chat, or both at once (CHANNELS=telegram,kazee). Each channel renders keyboards, files, voice notes, and edits natively
• Multi-backend — switch between Claude Code, Cursor Agent, and OpenAI Codex on the fly (/claude, /cursor, /codex); each keeps its own session state
• Multi-user / team mode — one bot serves multiple authorized users in parallel, each with their own conversations, settings, model, backend, and usage counters
• Multi-project sessions — switch between workspace projects; per-project conversation history auto-resumes

Memory & long-term context

• Context packs — living per-topic documents (one per project, system, or recurring task) holding Stance, Procedure, State, and Journal. Packs matching your message are auto-injected into the agent's context, and a background reviewer updates them after every substantial turn — the assistant keeps its train of thought across sessions and projects
• Entity memory — short notes on the people, places, projects, orgs, and systems you mention, extracted automatically and injected when they come up again
• Dream consolidation — a nightly pass on a stronger model that merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions, dedupes entities, and reports what it tidied — with everything backed up first
• Personality — a persona file gives the assistant a consistent voice on top of your soul file, and the dream pass evolves it gently as you work together
• Transcript search — redacted project transcripts indexed in SQLite FTS5; open-claudia transcript-search gives the agent ~50ms ranked recall over months of history
• Smart compaction — long conversations are summarized proactively before they get slow; full briefs are archived to disk so nothing is truly lost (/compact, /compactwindow)
• No silent learning — every pack, entity, or skill the bot creates or changes is announced in chat with one line

Background work

• Wakeups & crons — the agent can schedule one-shot wake-ups ("check the deploy in 20 minutes") and recurring jobs that survive restarts
• Persistent tasks — a per-channel todo tree with plans and subtasks that survives compaction and restarts
• Sub-agents — throwaway research agents for side questions that shouldn't pollute the main conversation
• Agent mode — non-blocking side conversations while heavy tasks run in the background

Working from your phone

• Voice notes — speak instructions, transcribed locally via Whisper; voice questions get voice replies (macOS)
• Screenshots & images — send UI mockups, errors, or code screenshots
• File sharing — send PDFs, code files, documents; the agent can send files, photos, and voice clips back
• Reply context — reply to any message (including files) for follow-up
• Streaming output — see the agent working in real time

Team

• People roster — the bot knows your team members, their channels, and notes about them
• Intros — unknown chats go through an owner-approved introduction flow
• Cross-channel relay — the agent can message teammates on their own channels (with provenance and an audit trail)
• Identity links — link chats across channels to one canonical user so history follows you

Operations

• Encrypted vault — store API keys and credentials securely
• Customizable soul — define your assistant's personality and knowledge
• Model switching, plan mode, effort levels, budgets — full control from chat
• Token economy — byte-stable system prompt for maximum Anthropic prompt-cache hits; dynamic state rides each message instead
• Web UI — optional browser UI for setup and config (open-claudia start --web)
• Auto-updates — checks npm every 5 minutes, upgrade with /upgrade
• Requirements doctor — /doctor checks CLI installs, auth, voice tools, and writable paths
• Cross-platform — macOS, Linux, and Windows

Prerequisites

• Node.js 18+ (22.5+ recommended — its built-in SQLite powers transcript/pack/entity search; on older Node those features quietly disable themselves)
• A Telegram bot token (from @BotFather) and/or a Kazee Chat bot
• At least one authenticated CLI backend on the host machine (see below)
• (Optional) whisper.cpp + ffmpeg for voice notes

Quick Start

1. Install and authenticate the CLI backends

You need at least one of these authenticated on the machine where Open Claudia will run.

Claude Code (required):

npm install -g @anthropic-ai/claude-code
claude                    # Opens browser to log in
claude --version          # Verify it works

Cursor Agent (optional — enables /cursor backend):

# Install from Cursor IDE: Settings > General > Agent CLI
# Or download from https://docs.cursor.com/agent
agent login               # Opens browser to authenticate
agent status              # Verify: should show your email and plan

OpenAI Codex (optional — enables /codex backend):

npm install -g @openai/codex
codex login               # Opens browser to authenticate
# Or from chat after Open Claudia is running: /codex_login
# If browser/device login cannot complete remotely: /codex_setup_token
codex --version           # Verify it works

Docker images include the Codex CLI. Direct npm installs still need optional backend CLIs installed on the host.

Important: Claude Code can use macOS Keychain when you log in interactively, but a launchd/background bot may not be able to read that Keychain session. Open Claudia supports CLAUDE_CODE_OAUTH_TOKEN for non-interactive Claude runs. Prefer /setup_token then /use_oauth_token if chat shows Claude auth/keychain errors.

2. Install Open Claudia

npm install -g @inetafrica/open-claudia

3. Run setup

open-claudia setup

The setup wizard will:

1. Detect Claude CLI, Cursor Agent CLI, ffmpeg, and whisper on your system
2. Verify Claude is authenticated
3. Ask for your Telegram bot token and verify it
4. Generate a verification code — send it to your bot to prove your identity
5. Set your workspace path (default: ~/.open-claudia/Workspace)
6. Create an encrypted vault for credentials
7. Optionally install as a background service (macOS launchd / Linux systemd)

If setup is interrupted, running it again resumes from the last completed step.

All configuration is stored in ~/.open-claudia/ — survives npm upgrades.

4. (Optional) Add Kazee Chat

Set CHANNELS=telegram,kazee plus KAZEE_URL, KAZEE_BOT_TOKEN, KAZEE_BOT_USER_ID, and KAZEE_OWNER_USER_ID in ~/.open-claudia/.env, or run /channel add kazee from an existing chat and follow the wizard.

Run

open-claudia start            # Start the bot (--web adds the web UI, --quick skips slow health checks)
open-claudia web              # Start with web UI for setup/config
open-claudia stop             # Stop the bot
open-claudia status           # Check if running (shows PID)
open-claudia health           # Run environment health checks (-v for detail)
open-claudia logs             # View recent logs
open-claudia auth             # Manage chat authorizations

If installed as a background service, the bot starts automatically on login and restarts on crash.

Chat Commands

Backend switching

| Command | Description | |---------|-------------| | /claude | Switch to Claude Code backend | | /cursor | Switch to Cursor Agent backend | | /codex | Switch to OpenAI Codex backend | | /backend | Show current backend with picker |

Each backend keeps its own persistent session. Switching doesn't lose your place — you can go back and forth freely.

Session management

| Command | Description | |---------|-------------| | /session [<project>] | Pick a project to work on | | /sessions | List past conversations for current project | | /projects | Browse all workspace projects | | /continue | Resume last conversation explicitly | | /compact | Summarize conversation context now | | /compactwindow [<tokens> \| off \| default] | Set the auto-compact token threshold | | /end | End current session |

When you select a project, the last conversation is automatically resumed. Tap "New conversation" to start fresh.

Settings

| Command | Description | |---------|-------------| | /model [<model>] | Switch model (opus / sonnet / haiku for Claude; any model flag for Cursor/Codex) | | /effort [low\|medium\|high\|max] | Set effort level | | /budget [$N] | Set max spend for next task — Claude only | | /plan | Toggle plan mode — --permission-mode plan (Claude) / --mode plan (Cursor) | | /ask | Toggle ask mode — read-only Q&A, no edits (Cursor Agent only) | | /worktree | Toggle isolated git branch | | /mode | Switch between direct and agent bot modes | | /status | Show current session, backend, and settings | | /usage | Token usage and cost for this session | | /doctor / /requirements | Check Node, CLI binaries/versions/auth, voice stack, and writable paths |

Memory & skills

| Command | Description | |---------|-------------| | /learn [<hint>] | Capture the last piece of work into the matching context pack | | /skills [show\|remove <name>] | List, show, or remove legacy learned skills | | /soul | View/edit assistant identity and personality |

Automation

| Command | Description | |---------|-------------| | /cron [add\|remove ...] | Manage scheduled tasks | | /vault [create\|get\|set\|remove\|lock] | Manage encrypted credentials (password required) |

Team & access

| Command | Description | |---------|-------------| | /auth [list \| revoke <chatId>] | Request access; owner lists/revokes | | /people [show\|note\|link\|unlink\|add\|remove ...] | Manage the team roster | | /intros [approve\|reject <id>] | Approve/reject introductions from unknown chats | | /link [<chat-id>] <email-or-id> | Link a chat to a canonical user id | | /links | List identity links (owner) | | /whoami | Show your canonical user id | | /channel [add kazee \| remove <id>] | Add or remove channels |

Claude Code auth

| Command | Description | |---------|-------------| | /auth_status | Reports redacted Claude auth status and whether an OAuth token is configured | | /login | Starts a Claude login flow, sends the URL/code, accepts paste-back codes (/auth_code <code>, /cancel_auth) | | /setup_token | Runs claude setup-token; the resulting OAuth token is stored without echoing it | | /use_oauth_token [<token>] | Stores CLAUDE_CODE_OAUTH_TOKEN for non-interactive runs; the message is deleted when possible. Without an argument, send the token as the next message | | /clear_oauth_token | Removes the stored OAuth token |

Tokens are redacted from chat output and logs.

Codex auth

| Command | Description | |---------|-------------| | /codex_auth_status | Reports redacted Codex auth status/version | | /codex_login | Starts codex login --device-auth and relays the URL/device code | | /codex_setup_token [<key>] | Secure paste mode for an OpenAI API key (message deleted, never echoed) | | /cancel_codex_auth | Cancels a pending Codex auth flow |

System

| Command | Description | |---------|-------------| | /version | Show current running version | | /upgrade | Upgrade to latest version and restart (includes a post-upgrade doctor summary) | | /restart | Restart the bot | | /stop | Cancel a running task | | /help | Show all commands |

Memory & Long-Term Context

Open Claudia layers three memory systems on top of the backend's native sessions:

Context packs (~/.open-claudia/packs/<dir>/PACK.md) are living per-topic documents with four sections: Stance (how to think about the topic — your preferences and hard rules), Procedure (verified how-to steps), State (where work stands now), and Journal (a dated one-line log of past sessions). Incoming messages are matched against packs (FTS5, field-weighted so a stray word can't drag a pack in) and hits are injected into the agent's context — mention a project anywhere and the assistant picks up its train of thought, decisions, and history without you re-explaining. After every substantial turn, a background reviewer on a cheap model updates the relevant pack (or creates one for a genuinely new topic). Every change is announced in chat.

Entity memory (~/.open-claudia/entities/<slug>.md) works the same way for the people, places, projects, orgs, and systems you mention — who they are, current truth, and a dated observation log. Mentioning a name injects its note.

Dream consolidation — while the per-turn reviewer takes quick notes, dream is the slow overnight pass (default 4am, on a stronger model): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, and cross-links notes. Anything merged away is backed up under ~/.open-claudia/backup/dream-<stamp>/ first, and every dream that changes something reports in chat. Configure with DREAM_CRON / DREAM_MODEL, disable with DREAM=off.

Personality — your soul.md holds identity and hard rules; ~/.open-claudia/persona.md holds the voice on top — tone, quirks, emoji habits. It feeds into the system prompt and the dream pass may evolve it gently (bounded, backed up, announced). Edit it directly any time.

Transcript index — every project conversation is logged (redacted) to JSONL outside the repo and indexed in SQLite FTS5, giving the agent ranked search over your full history.

open-claudia pack list|show <dir>|match "<text>"|migrate|remove <dir>|reindex
open-claudia entity list|show <slug>|match "<text>"|note <name> "<text>"|remove <slug>|reindex
open-claudia dream [--dry-run]               # run the consolidation pass now
open-claudia transcript-search "<query>"     # alias: ts; --all for every project
open-claudia transcript-window "<pattern>"   # alias: tw; hits with surrounding turns

pack migrate folds legacy ~/.claude/skills into packs (originals backed up, never deleted) — run it once after upgrading from a pre-2.5 version.

When a conversation grows past the auto-compact threshold, the bot summarizes it proactively: the full brief is archived to ~/.open-claudia/briefs/ and a condensed version seeds the fresh session, so long-running work never hits a context wall.

Background Work

The agent can schedule its own future work — these survive bot restarts:

open-claudia schedule-wakeup <30s|5m|2h|1d|ISO-date> "<prompt>"   # one-shot; resumes the session
open-claudia cron-add "<5-field cron>" "<prompt>"                 # recurring
open-claudia cron-list / cron-remove <id>

A persistent per-channel task tree tracks multi-turn work (plans with subtasks; completed items are removed automatically):

open-claudia task plan "<title>" "<step 1>" "<step 2>" [--description "..."]
open-claudia task add|list|start <id>|done <id>|remove <id>

And for side research that shouldn't pollute the main conversation:

open-claudia agent "<prompt>" [--role "<role>"]   # throwaway sub-agent, output on stdout

Team & Cross-Channel

The setup owner is automatically authorized. To add more users:

• From chat: unknown users who message the bot go through an intro flow — the owner gets an approve/reject prompt (/intros). Or they send /auth for a direct request.
• From the terminal: open-claudia auth shows authorized chats and pending requests.

Each chat defaults to telegram:<chatId> as its user id. Link chats to a canonical id to share sessions and history across channels:

/link [email protected]
/whoami

The bot keeps a people roster (/people, or open-claudia people list|show|note|link) and can relay messages between team members with provenance and an audit trail:

open-claudia send-to --person "<name>" "<message>"
open-claudia recent --person "<name>" [--limit 20]   # read recent activity from another chat

Backend Comparison

| | Claude Code | Cursor Agent | OpenAI Codex | |---|---|---|---| | Binary | claude | agent | codex | | Session flag | --resume <id> | --resume <id> | exec resume <id> | | Auth | claude auth | agent login | codex login | | Plan mode | Yes (--permission-mode plan) | Yes (--mode plan) | Yes (--sandbox read-only) | | Ask mode | No | Yes (--mode ask) | No | | Budget control | Yes (--max-budget-usd) | No | No | | Effort levels | Yes | No | Via config.toml | | Worktree | Yes (--worktree) | Yes (--worktree) | No | | Model switching | Yes | Yes | Yes (--model) | | Dangerously skip permissions | Yes | Yes (--trust) | Yes (--dangerously-bypass-approvals-and-sandbox) |

All three backends output structured JSON which Open Claudia parses for real-time progress updates (Claude/Cursor: stream-json; Codex: JSONL events).

Sending Files

Send any file to the bot — PDFs, code files, documents, images. Files are saved to ~/.open-claudia/files/ with their original names. The agent reads the file and responds based on content.

Add a caption to give the agent specific instructions:

• Send a PDF with caption "summarize the key findings"
• Send a code file with caption "find bugs in this"
• Send a screenshot with caption "implement this design"

The agent can also send files back — documents, photos with inline previews, and voice clips — directly from within a task.

Voice Notes

Requires whisper.cpp and ffmpeg:

# macOS
brew install whisper-cpp ffmpeg

# Linux (Ubuntu/Debian)
sudo apt install ffmpeg
# Build whisper.cpp from source: https://github.com/ggerganov/whisper.cpp

Voice notes are transcribed locally — nothing sent to external services. On macOS, replies to voice messages come back as voice notes too.

How It Works

Phone (Telegram / Kazee) --> Bot (Node.js) --> Claude Code CLI    --> Your codebase
                                           --> Cursor Agent CLI  -->
                                           --> OpenAI Codex CLI  -->
                         <--               <--                   <--

The bot spawns the active backend CLI in headless mode (--print / -p) for each message, streaming stream-json/JSONL output back to the chat. It maintains native backend context via --resume and passes a system prompt that gives the agent awareness of the chat environment, configuration files, memory systems, and the ability to send files/images directly.

The appended system prompt is byte-stable within a session to maximize Anthropic prompt-cache hits; per-turn state (vault status, pending tasks, matched packs/entities) rides the user message instead, where it is always uncached anyway.

Open Claudia does not summarize one backend into another during switches; instead it records a redacted project transcript outside the repo and injects a small pointer telling fresh/switched sessions to search it only if needed.

Configuration Files

All stored in ~/.open-claudia/:

| File | Purpose | |------|---------| | .env | Tokens, workspace path, binary paths, channel config | | auth.json | Authorized users and pending requests | | identities.json | Channel-to-canonical-user mappings | | people.json / intros.json | Team roster and pending introductions | | vault.enc | Encrypted credential store | | soul.md | Assistant identity and hard rules (editable via /soul) | | persona.md | Assistant voice and quirks (feeds the system prompt; evolved gently by dream) | | crons.json / jobs.json | Recurring crons and one-shot wakeups | | tasks/ | Persistent per-channel task trees | | packs/ | Context packs (living topic documents) + FTS index | | entities/ | Entity notes (people/places/projects) + FTS index | | sessions.json | Per-project conversation history | | state.json | Current session state including active backend (survives restarts) | | transcripts/ | Redacted project-scoped JSONL transcripts + FTS index | | briefs/ | Archived full compaction briefs | | audit.log | Relay/intro/auth audit trail | | bot.log | Bot logs | | files/ | Files received from chat | | media/ | Temporary media (voice notes, photos) | | backup/ | Backups (skills folded by pack migrate; packs/entities merged away by dream) |

Environment Variables (.env)

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | Yes* | Bot token from BotFather | | TELEGRAM_CHAT_ID | Yes* | Comma-separated authorized chat IDs | | CHANNELS | No | Channels to start: telegram, kazee, or telegram,kazee (default telegram) | | KAZEE_URL / KAZEE_BOT_TOKEN / KAZEE_BOT_USER_ID / KAZEE_OWNER_USER_ID | Kazee only | Kazee Chat connection | | WORKSPACE | Yes | Path to your projects directory | | CLAUDE_PATH | Yes | Path to Claude Code CLI binary | | CURSOR_PATH / CODEX_PATH | No | Paths to optional backend CLIs (auto-detected if in PATH) | | CLAUDE_CODE_OAUTH_TOKEN | No | OAuth token for non-interactive Claude runs (set via /use_oauth_token) | | CLAUDE_MODEL | No | Default Claude model | | AUTO_COMPACT_TOKENS | No | Auto-compact threshold in tokens (also settable via /compactwindow) | | PROJECT_TRANSCRIPTS | No | Enable redacted project transcripts (default true) | | TRANSCRIPT_MAX_ENTRY_CHARS | No | Max chars per transcript entry (default 12000) | | TRANSCRIPTS_DIR / PACKS_DIR / ENTITIES_DIR | No | Override storage directories | | PACK_REVIEW | No | off disables the post-turn pack/entity reviewer (default on) | | PACK_REVIEW_MODEL | No | Model for the reviewer (default haiku) | | PACK_MATCH_THRESHOLD / ENTITY_MATCH_THRESHOLD | No | Router match score thresholds (default 2) | | DREAM | No | off disables the nightly memory consolidation pass (default on) | | DREAM_CRON | No | Schedule for the dream pass (default 0 4 * * *) | | DREAM_MODEL | No | Model for the dream pass (default sonnet) | | PERSONA_FILE | No | Override the persona file location | | WEB_UI / WEB_PORT / WEB_PASSWORD | No | Web UI toggle, port, and password | | WHISPER_CLI / WHISPER_MODEL | No | whisper.cpp binary and model for voice notes | | FFMPEG | No | Path to ffmpeg binary |

* Required for the Telegram channel.

Background Service

macOS (launchd)

Set up during open-claudia setup, or manually:

# The setup wizard creates ~/Library/LaunchAgents/com.open-claudia.plist
# To manage:
launchctl load ~/Library/LaunchAgents/com.open-claudia.plist
launchctl unload ~/Library/LaunchAgents/com.open-claudia.plist

Important: If agent is installed in a non-standard location (e.g. ~/.local/bin), make sure that path is included in the launchd plist's PATH environment variable. Otherwise the bot won't detect it at startup.

Linux (systemd)

# The setup wizard creates /etc/systemd/system/claude-telegram-bot.service
# To manage:
sudo systemctl enable claude-telegram-bot
sudo systemctl start claude-telegram-bot
sudo systemctl status claude-telegram-bot

Auto-Updates

The bot checks npm for new versions every 5 minutes. When an update is available, you get a chat notification. Send /upgrade to update — the bot installs the new version, restarts, runs a doctor check, and notifies you it's back.

For direct npm installs, /upgrade updates Open Claudia itself and does not install optional backend CLIs such as Codex or Cursor Agent. Container deployments should roll out a new Docker image when bundled CLI tools change.

Cron Jobs

Schedule recurring tasks:

/cron add "0 9 * * 1-5" myproject "Morning standup: summarize git changes since yesterday"
/cron add "0 18 * * *" myproject "Git digest: what changed today?"
/cron add "*/30 * * * *" myproject "Health check: verify the API is responding"

Presets available via /cron menu. The agent can also schedule its own jobs with open-claudia cron-add / schedule-wakeup (see Background Work).

Vault

Store sensitive credentials encrypted:

/vault                    # Unlock vault (prompts for password)
/vault set AWS_KEY xxx    # Store a credential
/vault remove AWS_KEY     # Remove a credential
/vault lock               # Lock vault

The agent can read vault credentials when unlocked — useful for deployment scripts and API calls.

License

MIT