Open Claudia

Your always-on AI coding assistant — Claude Code and Cursor Agent via Telegram.

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

Features

• Multi-backend — switch between Claude Code and Cursor Agent on the fly (/cursor, /claude)
• Multi-project sessions — switch between workspace projects
• Per-project conversation history — auto-resumes last conversation, switch with /sessions
• Separate session persistence — Claude and Cursor each maintain their own conversation state
• Voice notes — speak instructions, transcribed locally via Whisper
• Screenshots & images — send UI mockups, errors, or code screenshots
• File sharing — send PDFs, code files, documents — saved and read by the agent
• Reply context — reply to any message (including files) for follow-up
• Streaming output — see the agent working in real-time
• Agent mode — non-blocking side conversations while heavy tasks run in the background
• Cron jobs — scheduled tasks (standups, git digests, health checks)
• Encrypted vault — store API keys and credentials securely
• Customizable soul — define your assistant's personality and knowledge
• Model switching — toggle between models on either backend
• Plan mode, effort levels, budgets — full control from Telegram
• Auto-updates — checks for new versions every 5 minutes, upgrade with /upgrade
• Multi-user auth — authorize additional users with code verification
• Cross-platform — works on macOS, Linux, and Windows

Prerequisites

• Node.js 18+
• A Telegram bot token (from @BotFather)
• 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

Important: Both CLIs store authentication locally on the machine. Open Claudia doesn't handle auth itself — it shells out to whichever CLI you've authenticated. If you see auth errors in Telegram, SSH into the machine and re-authenticate the relevant CLI.

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.

Run

open-claudia start    # Start the bot
open-claudia stop     # Stop the bot
open-claudia status   # Check if running (shows PID)
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.

Telegram Commands

Backend Switching

| Command | Description | |---------|-------------| | /cursor | Switch to Cursor Agent backend | | /claude | Switch to Claude Code 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 | Pick a project to work on | | /sessions | List past conversations for current project | | /projects | Browse all workspace projects | | /continue | Resume last conversation explicitly | | /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 | Switch model (opus / sonnet / haiku for Claude; any model flag for Cursor) | | /effort | Set effort level (low / medium / high / max) | | /budget | Set max spend for next task (e.g. /budget 0.50) — 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) | | /compact | Summarize conversation context | | /worktree | Toggle isolated git branch — Claude only | | /mode | Switch between direct and agent bot modes | | /status | Show current session, backend, and settings |

Automation

| Command | Description | |---------|-------------| | /cron | Manage scheduled tasks | | /vault | Manage encrypted credentials (password required) | | /soul | View/edit assistant identity and personality |

System

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

Backend Comparison

| | Claude Code | Cursor Agent | |---|---|---| | Binary | claude | agent | | Session flag | --resume <id> | --resume <id> | | Auth | claude auth | agent login | | Plan mode | Yes (--permission-mode plan) | Yes (--mode plan) | | Ask mode | No | Yes (--mode ask) | | Budget control | Yes (--max-budget-usd) | No | | Effort levels | Yes | No | | Worktree | Yes (--worktree) | Yes (--worktree) | | Model switching | Yes | Yes | | Dangerously skip permissions | Yes | Yes (--trust) |

Both backends output stream-json which Open Claudia parses for real-time progress updates.

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 your file 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"

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.

Multi-User Authorization

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

From Telegram (unauthorized users):

• Send /auth to the bot — the owner gets notified

From the terminal (owner):

open-claudia auth

This shows authorized chats, pending requests, and lets you approve/deny or add new users with code verification.

How It Works

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

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

Use /cursor or /claude to switch which CLI handles your messages. Each maintains its own session ID, so switching doesn't lose context on either side.

Configuration Files

All stored in ~/.open-claudia/:

| File | Purpose | |------|---------| | .env | Telegram token, workspace path, binary paths (CLAUDE_PATH, CURSOR_PATH) | | auth.json | Authorized users and pending requests | | vault.enc | Encrypted credential store | | soul.md | Assistant identity and personality (editable via /soul) | | crons.json | Scheduled tasks | | sessions.json | Per-project conversation history | | state.json | Current session state including active backend (survives restarts) | | bot.log | Bot logs | | files/ | Files received from Telegram | | media/ | Temporary media (voice notes, photos) |

Environment Variables (.env)

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | Yes | Bot token from BotFather | | TELEGRAM_CHAT_ID | Yes | Comma-separated authorized chat IDs | | WORKSPACE | Yes | Path to your projects directory | | CLAUDE_PATH | Yes | Path to Claude Code CLI binary | | CURSOR_PATH | No | Path to Cursor Agent CLI binary (auto-detected if in PATH) | | WHISPER_CLI | No | Path to whisper.cpp binary | | WHISPER_MODEL | No | Whisper model to use | | FFMPEG | No | Path to ffmpeg binary |

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 Telegram notification:

"Hey! A new version is available (v1.10.0). You're on v1.9.2."

Send /upgrade to update. The bot will:

1. Download and install the new version
2. Go offline briefly
3. Restart and notify you it's back

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.

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