@inetafrica/open-claudia 1.10.0 → 1.10.1

package/README.md

@@ -1,41 +1,69 @@
 # Open Claudia
 
-Your always-on AI coding assistant — Claude Code via Telegram.
+Your always-on AI coding assistant — Claude Code and Cursor Agent via Telegram.
 
-Send text, voice notes, screenshots, and files from your phone. Claude Code works on your projects and reports back.
+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 Claude
+- **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 Claude working in real-time
+- **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 Opus, Sonnet, Haiku
-- **Plan mode, effort levels, budgets** — full Claude Code control from Telegram
+- **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
 
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
 - [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
 
-## Install
+## 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
 ```
 
-## Setup
+### 3. Run setup
 
 ```bash
 open-claudia setup
@@ -43,7 +71,7 @@ open-claudia setup
 
 The setup wizard will:
 
-1. Detect Claude CLI, ffmpeg, and whisper on your system
+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
@@ -69,6 +97,16 @@ If installed as a background service, the bot starts automatically on login and
 
 ## 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 |
@@ -85,13 +123,14 @@ When you select a project, the last conversation is automatically resumed. Tap "
 
 | Command | Description |
 |---------|-------------|
-| `/model` | Switch model (opus / sonnet / haiku) |
+| `/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`) |
-| `/plan` | Toggle plan mode |
+| `/budget` | Set max spend for next task (e.g. `/budget 0.50`) — Claude only |
+| `/plan` | Toggle plan mode — Claude only |
 | `/compact` | Summarize conversation context |
-| `/worktree` | Toggle isolated git branch |
-| `/status` | Show current session and settings |
+| `/worktree` | Toggle isolated git branch — Claude only |
+| `/mode` | Switch between direct and agent bot modes |
+| `/status` | Show current session, backend, and settings |
 
 ### Automation
 
@@ -111,11 +150,27 @@ When you select a project, the last conversation is automatically resumed. Tap "
 | `/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`) |
+| Budget control | Yes (`--max-budget-usd`) | No |
+| Effort levels | Yes | No |
+| Worktree | Yes | No |
+| 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. Claude reads the file and responds based on content.
+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 Claude specific instructions:
+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"
@@ -152,11 +207,14 @@ This shows authorized chats, pending requests, and lets you approve/deny or add
 ## How It Works
 
 ```
-Phone (Telegram) --> Bot (Node.js) --> Claude Code CLI --> Your codebase
+Phone (Telegram) --> Bot (Node.js) --> Claude Code CLI  --> Your codebase
+                                   --> Cursor Agent CLI -->
                  <--               <--                  <--
 ```
 
-The bot spawns `claude -p` for each message, streaming output back to Telegram. It maintains conversation context via `--resume` and passes a system prompt that gives Claude awareness of the Telegram environment, its configuration files, and the ability to send files/images directly.
+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
 
@@ -164,17 +222,30 @@ All stored in `~/.open-claudia/`:
 
 | File | Purpose |
 |------|---------|
-| `.env` | Telegram token, workspace path, binary paths |
+| `.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 (survives restarts) |
+| `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)
@@ -188,6 +259,8 @@ 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
@@ -202,7 +275,7 @@ sudo systemctl status claude-telegram-bot
 
 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.3.0). You're on v1.2.9."
+> "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
@@ -232,7 +305,7 @@ Store sensitive credentials encrypted:
 /vault lock               # Lock vault
 ```
 
-Claude can read vault credentials when unlocked — useful for deployment scripts and API calls.
+The agent can read vault credentials when unlocked — useful for deployment scripts and API calls.
 
 ## License
 

package/bot-agent.js

@@ -1110,10 +1110,17 @@ bot.onText(/\/sessions$/, (msg) => {
 
 bot.onText(/\/model$/, (msg) => {
   if (!isAuthorized(msg)) return;
-  send(`Model: ${settings.model || "default"}`, { keyboard: { inline_keyboard: [
+  const keyboard = settings.backend === "cursor" ? [
+    [{ text: "Composer 2", callback_data: "m:composer-2" }, { text: "Composer 2 Fast", callback_data: "m:composer-2-fast" }],
+    [{ text: "Opus 4.6 Thinking", callback_data: "m:claude-4.6-opus-high-thinking" }, { text: "Sonnet 4.6", callback_data: "m:claude-4.6-sonnet-medium" }],
+    [{ text: "GPT-5.4", callback_data: "m:gpt-5.4-medium" }, { text: "GPT-5.4 High", callback_data: "m:gpt-5.4-high" }],
+    [{ text: "Auto", callback_data: "m:auto" }, { text: "Default", callback_data: "m:default" }],
+  ] : [
     [{ text: "Opus", callback_data: "m:opus" }, { text: "Sonnet", callback_data: "m:sonnet" }, { text: "Haiku", callback_data: "m:haiku" }],
     [{ text: "Default", callback_data: "m:default" }],
-  ] } });
+  ];
+  const label = settings.backend === "cursor" ? "Cursor Agent" : "Claude Code";
+  send(`${label} model: ${settings.model || "default"}\n\nOr type /model <name> for any model.`, { keyboard: { inline_keyboard: keyboard } });
 });
 bot.onText(/\/model (.+)/, (msg, match) => { if (!isAuthorized(msg)) return; settings.model = match[1].trim().toLowerCase(); if (settings.model === "default") settings.model = null; send(`Model: ${settings.model || "default"}`); });
 

package/bot.js

@@ -1153,10 +1153,17 @@ bot.onText(/\/sessions$/, (msg) => {
 
 bot.onText(/\/model$/, (msg) => {
   if (!isAuthorized(msg)) return;
-  send(`Model: ${settings.model || "default"}`, { keyboard: { inline_keyboard: [
+  const keyboard = settings.backend === "cursor" ? [
+    [{ text: "Composer 2", callback_data: "m:composer-2" }, { text: "Composer 2 Fast", callback_data: "m:composer-2-fast" }],
+    [{ text: "Opus 4.6 Thinking", callback_data: "m:claude-4.6-opus-high-thinking" }, { text: "Sonnet 4.6", callback_data: "m:claude-4.6-sonnet-medium" }],
+    [{ text: "GPT-5.4", callback_data: "m:gpt-5.4-medium" }, { text: "GPT-5.4 High", callback_data: "m:gpt-5.4-high" }],
+    [{ text: "Auto", callback_data: "m:auto" }, { text: "Default", callback_data: "m:default" }],
+  ] : [
     [{ text: "Opus", callback_data: "m:opus" }, { text: "Sonnet", callback_data: "m:sonnet" }, { text: "Haiku", callback_data: "m:haiku" }],
     [{ text: "Default", callback_data: "m:default" }],
-  ] } });
+  ];
+  const label = settings.backend === "cursor" ? "Cursor Agent" : "Claude Code";
+  send(`${label} model: ${settings.model || "default"}\n\nOr type /model <name> for any model.`, { keyboard: { inline_keyboard: keyboard } });
 });
 bot.onText(/\/model (.+)/, (msg, match) => { if (!isAuthorized(msg)) return; settings.model = match[1].trim().toLowerCase(); if (settings.model === "default") settings.model = null; send(`Model: ${settings.model || "default"}`); });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "Your always-on AI coding assistant — Claude Code via Telegram",
   "main": "bot.js",
   "bin": {