npm package: @inetafrica/open-claudia
Description: Your always-on AI coding assistant — Claude Code via Telegram
Author: Sumeet Rajpal
Latest version: 1.12.1

# 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](https://nodejs.org/) 18+
- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
- At least one authenticated CLI backend on the host machine (see below)
- (Optional) [whisper.cpp](https://github.com/ggerganov/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):

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

**Cursor Agent** (optional — enables `/cursor` backend):

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

```bash
npm install -g @inetafrica/open-claudia
```

### 3. Run setup

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

```bash
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](https://github.com/ggerganov/whisper.cpp) and ffmpeg:

```bash
# 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):
```bash
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:

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

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