@inetafrica/open-claudia 1.2.8 → 1.3.0

package/README.md

@@ -7,92 +7,232 @@ Send text, voice notes, screenshots, and files from your phone. Claude Code work
 ## Features
 
 - **Multi-project sessions** — switch between workspace projects
+- **Per-project conversation history** — auto-resumes last conversation, switch with `/sessions`
 - **Voice notes** — speak instructions, transcribed locally via Whisper
-- **Screenshots** — send UI mockups, errors, or code screenshots
-- **File sharing** — send and receive files directly in Telegram
+- **Screenshots & images** — send UI mockups, errors, or code screenshots
+- **File sharing** — send PDFs, code files, documents — saved and read by Claude
+- **Reply context** — reply to any message (including files) for follow-up
 - **Streaming output** — see Claude working in real-time
 - **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
+- **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))
-- (Optional) whisper-cpp + ffmpeg for voice notes
+- (Optional) [whisper.cpp](https://github.com/ggerganov/whisper.cpp) + ffmpeg for voice notes
 
 ## Install
 
 ```bash
-# From npm package
-npm install -g open-claudia
-
-# Or from source
-git clone https://git.coders.africa/agents/open-claudia.git
-cd open-claudia
-npm install
+npm install -g @inetafrica/open-claudia
 ```
 
 ## Setup
 
 ```bash
 open-claudia setup
-# or: node setup.js
 ```
 
 The setup wizard will:
-1. Detect Claude CLI and dependencies
-2. Ask for your Telegram bot token and verify it
-3. Auto-detect your chat ID
-4. Set a vault password for credential encryption
-5. Optionally install as a background service (macOS launchd / Linux systemd)
+
+1. Detect Claude 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
+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
 
+### Session Management
+
 | Command | Description |
 |---------|-------------|
 | `/session` | Pick a project to work on |
+| `/sessions` | List past conversations for current project |
 | `/projects` | Browse all workspace projects |
-| `/model` | Switch model (opus/sonnet/haiku) |
-| `/effort` | Set effort level |
-| `/budget` | Set max spend per task |
+| `/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) |
+| `/effort` | Set effort level (low / medium / high / max) |
+| `/budget` | Set max spend for next task (e.g. `/budget 0.50`) |
 | `/plan` | Toggle plan mode |
-| `/continue` | Resume last conversation |
+| `/compact` | Summarize conversation context |
+| `/worktree` | Toggle isolated git branch |
+| `/status` | Show current session and settings |
+
+### Automation
+
+| Command | Description |
+|---------|-------------|
 | `/cron` | Manage scheduled tasks |
-| `/vault` | Manage credentials (password-protected) |
-| `/soul` | View/edit assistant identity |
-| `/stop` | Cancel running task |
-| `/end` | End current session |
+| `/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 |
+
+## 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.
+
+Add a caption to your file to give Claude 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
-                 ←               ←                  ←
+Phone (Telegram) --> Bot (Node.js) --> Claude Code CLI --> Your codebase
+                 <--               <--                  <--
 ```
 
-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 own configuration files, and the ability to send files/images directly.
+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.
 
 ## Configuration Files
 
+All stored in `~/.open-claudia/`:
+
 | File | Purpose |
 |------|---------|
-| `.env` | Telegram token, paths, settings (created by setup) |
-| `soul.md` | Assistant identity and personality (editable) |
-| `crons.json` | Scheduled tasks |
+| `.env` | Telegram token, workspace path, binary paths |
+| `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) |
+| `bot.log` | Bot logs |
+| `files/` | Files received from Telegram |
+| `media/` | Temporary media (voice notes, photos) |
+
+## 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
+```
+
+### 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.3.0). You're on v1.2.9."
+
+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
+```
+
+Claude can read vault credentials when unlocked — useful for deployment scripts and API calls.
 
 ## License
 

package/bin/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { execSync } = require("child_process");
+const fs = require("fs");
 const path = require("path");
 
 const args = process.argv.slice(2);
@@ -8,6 +9,30 @@ const command = args[0] || "help";
 
 const botDir = path.join(__dirname, "..");
 
+function findBotProcesses() {
+  try {
+    if (process.platform === "win32") {
+      const out = execSync('tasklist /FI "IMAGENAME eq node.exe" /FO CSV /NH', { encoding: "utf-8" });
+      // Check if any node process has bot.js in its command line
+      const wmic = execSync('wmic process where "name=\'node.exe\'" get ProcessId,CommandLine /FORMAT:CSV 2>nul', { encoding: "utf-8" });
+      const pids = [];
+      for (const line of wmic.split("\n")) {
+        if (line.includes("bot.js") && line.includes("open-claudia")) {
+          const parts = line.trim().split(",");
+          const pid = parts[parts.length - 1];
+          if (pid) pids.push(pid.trim());
+        }
+      }
+      return pids;
+    } else {
+      const out = execSync('ps -eo pid,command | grep "bot.js" | grep "open-claudia" | grep -v grep', { encoding: "utf-8" });
+      return out.trim().split("\n").map((l) => l.trim().split(/\s+/)[0]).filter(Boolean);
+    }
+  } catch (e) {
+    return [];
+  }
+}
+
 switch (command) {
   case "setup":
     require(path.join(botDir, "setup.js"));
@@ -24,33 +49,37 @@ switch (command) {
     require(path.join(botDir, "setup.js"));
     break;
 
-  case "stop":
-    try {
-      execSync('pkill -f "node.*bot.js"', { stdio: "inherit" });
-      console.log("Stopped.");
-    } catch (e) {
+  case "stop": {
+    const pids = findBotProcesses();
+    if (pids.length === 0) {
       console.log("Not running.");
+    } else {
+      for (const pid of pids) {
+        try { process.kill(parseInt(pid, 10), "SIGTERM"); } catch (e) {}
+      }
+      console.log("Stopped.");
     }
     break;
+  }
 
-  case "logs":
+  case "logs": {
     const configDir = require(path.join(botDir, "config-dir"));
     const logFile = path.join(configDir, "bot.log");
     try {
-      execSync(`tail -50 "${logFile}"`, { stdio: "inherit" });
+      const content = fs.readFileSync(logFile, "utf-8");
+      const lines = content.split("\n");
+      console.log(lines.slice(-50).join("\n"));
     } catch (e) {
       console.log("No logs found.");
     }
     break;
+  }
 
-  case "status":
-    try {
-      execSync('pgrep -f "node.*bot.js"', { stdio: "pipe" });
-      console.log("Running.");
-    } catch (e) {
-      console.log("Not running.");
-    }
+  case "status": {
+    const pids = findBotProcesses();
+    console.log(pids.length > 0 ? `Running (PID: ${pids.join(", ")}).` : "Not running.");
     break;
+  }
 
   default:
     console.log(`

package/bot.js

@@ -61,8 +61,11 @@ const FULL_PATH = [
   path.dirname(process.execPath),
   FFMPEG ? path.dirname(FFMPEG) : null,
   WHISPER_CLI ? path.dirname(WHISPER_CLI) : null,
-  "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin",
-].filter(Boolean).join(":");
+  ...(process.platform === "win32"
+    ? [process.env.APPDATA, process.env.LOCALAPPDATA].filter(Boolean).map((p) => path.join(p, "npm"))
+    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]
+  ),
+].filter(Boolean).join(path.delimiter);
 
 const bot = new TelegramBot(TOKEN, {
   polling: {

package/package.json

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

package/setup.js

@@ -138,20 +138,17 @@ function detectPlatform() {
   return "other";
 }
 
-function findClaude() {
+function findBinary(name) {
+  const cmd = process.platform === "win32" ? `where ${name} 2>nul` : `which ${name} 2>/dev/null`;
   try {
-    const p = execSync("which claude 2>/dev/null || where claude 2>nul", { encoding: "utf-8" }).trim();
+    const p = execSync(cmd, { encoding: "utf-8" }).trim().split("\n")[0];
     return p || null;
   } catch (e) { return null; }
 }
 
-function findWhisper() {
-  try { return execSync("which whisper-cli 2>/dev/null", { encoding: "utf-8" }).trim() || null; } catch (e) { return null; }
-}
-
-function findFfmpeg() {
-  try { return execSync("which ffmpeg 2>/dev/null", { encoding: "utf-8" }).trim() || null; } catch (e) { return null; }
-}
+function findClaude() { return findBinary("claude"); }
+function findWhisper() { return findBinary("whisper-cli"); }
+function findFfmpeg() { return findBinary("ffmpeg"); }
 
 function findWhisperModel() {
   const candidates = [