cc-claw 0.1.0 → 0.2.1

package/README.md

@@ -1,12 +1,24 @@
-# CC-Claw — Coding CLI Claw
+# CC-Claw
 
 <p align="center">
   <img src="assets/cc_claw.png" alt="CC-Claw Logo" width="300" />
 </p>
 
-Your personal AI assistant on Telegram, powered by the best coding CLIs. CC-Claw uses **Claude Code**, **Gemini CLI**, and **Codex** as its backend intelligence — giving you a full personal and productivity assistant accessible from any device.
+A personal AI assistant on Telegram, powered by coding CLIs. CC-Claw uses **Claude Code**, **Gemini CLI**, and **Codex** as interchangeable backends — giving you a multi-model AI assistant accessible from any device.
 
-Send text, voice messages, photos, documents, or videos. The agent handles coding, research, email, scheduling, content creation, document analysis, and any task you need. Switch backends on the fly with `/claude`, `/gemini`, or `/codex`. Spawn sub-agents across different CLIs to work in parallel.
+Send text, voice, photos, documents, or videos. Switch backends with `/claude`, `/gemini`, or `/codex`. Spawn sub-agents across different CLIs to work in parallel. Schedule recurring tasks. All state persists in SQLite.
+
+## What Can It Do
+
+- **Multi-backend AI** — Switch between Claude, Gemini, and Codex mid-conversation. Each backend supports per-model thinking levels.
+- **Agent orchestration** — Spawn named sub-agents across different CLIs. Agents communicate via inbox, share data on a whiteboard, and track tasks with dependencies.
+- **Agent templates** — Define reusable agent personas as markdown files (`~/.cc-claw/agents/*.md`). Security reviewers, content writers, researchers — spawn them by name.
+- **Scheduling** — Cron jobs, one-shot tasks, and intervals. Per-job backend, model, and delivery (Telegram, webhook, or silent).
+- **Memory** — Hybrid vector + keyword search. The agent remembers what you tell it across sessions, with salience decay.
+- **Voice** — Send voice messages, get voice replies. Groq Whisper for transcription, ElevenLabs for synthesis.
+- **50+ CLI commands** — Full system management from terminal. Every command supports `--json` for scripting.
+- **MCP support** — Model Context Protocol servers extend the agent with external tools and data.
+- **Cross-channel awareness** — Actions from CLI are visible to Telegram and vice versa via the activity log.
 
 ## Supported Backends
 
@@ -16,19 +28,15 @@ Send text, voice messages, photos, documents, or videos. The agent handles codin
 | **Gemini** | `gemini` | 3.1 Pro Preview, 3 Flash |
 | **Codex** | `codex` | GPT-5.4, GPT-5.3 Codex, GPT-5.2 Codex |
 
-Each backend supports per-model thinking/reasoning level control, session resumption, and configurable permission modes.
-
 ## Prerequisites
 
 - **Node.js 20+**
-- **At least one coding CLI** installed:
-  - Claude Code CLI — `npm install -g @anthropic-ai/claude-code`
-  - Gemini CLI — `npm install -g @google/gemini-cli` (or via Homebrew)
-  - Codex CLI — `npm install -g @openai/codex` (or via Homebrew)
+- **At least one backend CLI** installed:
+  - Claude Code — `npm install -g @anthropic-ai/claude-code`
+  - Gemini CLI — `npm install -g @google/gemini-cli`
+  - Codex — `npm install -g @openai/codex`
 - **Telegram bot token** from [@BotFather](https://t.me/BotFather)
 
-Backend-specific setup (e.g., Vertex AI for Claude, Google Cloud for Gemini, ChatGPT subscription for Codex) is handled during `cc-claw setup`.
-
 ## Install
 
 ```bash
@@ -41,181 +49,185 @@ npm install -g cc-claw
 cc-claw setup
 ```
 
-The interactive wizard walks you through:
+The wizard walks you through:
 
 1. Creating a Telegram bot and pasting the token
-2. Getting your Telegram chat ID (for security — only you can use the bot)
-3. Selecting your default backend and configuring its credentials
-4. Optional features: voice (Groq STT + ElevenLabs TTS), web dashboard, video analysis (Gemini)
+2. Setting your chat ID (security — only you can use the bot)
+3. Configuring backend credentials (all optional — configure what you use)
+4. Optional features: voice, web dashboard, video analysis
 5. Installing as a background service
 
-Configuration is saved to `~/.cc-claw/.env`. Data is organized under `~/.cc-claw/`:
-
-```
-~/.cc-claw/
-  .env                        config (Telegram token, backend credentials)
-  data/cc-claw.db             SQLite database
-  logs/cc-claw.log            stdout log
-  logs/cc-claw.error.log      stderr log
-  runners/                    config-driven CLI runner definitions (JSON)
-  workspace/
-    SOUL.md                   agent identity and personality (customizable)
-    USER.md                   your profile and preferences
-    CLAUDE.md / GEMINI.md     native CLI awareness notes (auto-generated)
-    context/                  on-demand context files
-    skills/                   skill repository (available to all backends)
-```
+Config saved to `~/.cc-claw/.env`.
 
 ## Run
 
 ```bash
-# Foreground (see output in terminal)
+# Background service (recommended)
+cc-claw service install
+
+# Or foreground
 cc-claw start
+```
 
-# Or install as a background service (launchd on macOS, systemd on Linux)
-cc-claw install
+```bash
+cc-claw service start       # Start
+cc-claw service stop        # Stop
+cc-claw service restart     # Restart (pick up config changes)
+cc-claw service status      # Check if running
 ```
 
 ## CLI
 
-CC-Claw has a comprehensive CLI with 50+ commands. Every command supports `--json` for AI agents and scripts.
-
 ```bash
-cc-claw status                    # System status (backend, model, usage)
-cc-claw doctor                    # Health checks + auto-fix
-cc-claw logs -f                   # Follow daemon logs
-cc-claw chat send "hello"         # Talk to the AI from terminal
-cc-claw tui                       # Interactive terminal chat
-cc-claw backend set gemini        # Switch backend
-cc-claw model list                # List models
-cc-claw cron list                 # List scheduled jobs
-cc-claw agents list               # List active sub-agents
+cc-claw status              # System status
+cc-claw doctor --fix        # Health checks + auto-repair
+cc-claw logs -f             # Follow logs
+cc-claw chat send "hello"   # Talk to the AI from terminal
+cc-claw tui                 # Interactive terminal chat
+cc-claw backend set gemini  # Switch backend
 cc-claw agents spawn --runner claude --task "review code"
-cc-claw db stats                  # Database health
-cc-claw completion --shell zsh    # Shell completions
-cc-claw --ai                      # Generate AI skill file
+cc-claw cron list           # Scheduled jobs
+cc-claw --ai                # Generate AI skill file
 ```
 
-| Command Group | Description |
-|---------------|-------------|
+| Group | Description |
+|-------|-------------|
 | `service` | start, stop, restart, status, install, uninstall |
 | `status` / `doctor` / `logs` | Diagnostics and monitoring |
-| `chat` / `tui` | Talk to the AI from terminal |
+| `chat` / `tui` | Terminal AI chat |
 | `backend` / `model` / `thinking` | Backend and model management |
 | `memory` | list, search, add, forget, history |
-| `cron` / `schedule` | Scheduler management (create, cancel, pause, resume, run) |
+| `cron` / `schedule` | Scheduler (create, cancel, pause, resume, run) |
 | `agents` / `tasks` / `runners` | Agent orchestration |
-| `config` | Runtime and static configuration |
-| `usage` / `cost` | Cost tracking and usage limits |
+| `config` | Runtime configuration |
+| `usage` / `cost` | Cost tracking and limits |
 | `permissions` / `tools` / `verbose` | Permission and tool management |
 | `skills` / `mcps` | Skills and MCP servers |
 | `db` | Database stats, backup, prune |
-| `completion` | Shell completions (bash/zsh/fish) |
-| `setup` | Interactive configuration wizard |
 
-Read commands work offline (direct DB). Write commands require the daemon running.
+Read commands work offline (direct DB access). Write commands require the daemon.
+
+## Telegram Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `/help` | All commands |
+| `/status` | Backend, model, session, usage |
+| `/newchat` | Start fresh (summarizes current session) |
+| `/stop` | Cancel running task |
+
+### Backend & Model
+
+| Command | Description |
+|---------|-------------|
+| `/backend` | Switch backend via keyboard |
+| `/claude` `/gemini` `/codex` | Quick switch |
+| `/model` | Switch model + thinking level |
+| `/summarizer` | Session summarization model |
+
+### Scheduling
+
+| Command | Description |
+|---------|-------------|
+| `/schedule <desc>` | Create a scheduled task |
+| `/jobs` | List jobs |
+| `/run <id>` | Trigger now |
+| `/runs` | Run history |
+| `/editjob <id>` | Edit a job |
+| `/pause` / `/resume` / `/cancel` | Job lifecycle |
+| `/health` | Scheduler health |
+
+### Agents
 
-### Telegram Commands
+| Command | Description |
+|---------|-------------|
+| `/agents` | List sub-agents |
+| `/tasks` | Task board |
+| `/stopagent <id>` | Cancel one agent |
+| `/stopall` | Cancel all agents |
+| `/runners` | Available CLI runners |
 
-Once running, send these to your bot:
+### Settings
 
 | Command | Description |
 |---------|-------------|
-| `/help` | Show available commands |
-| `/backend` | Switch AI backend (Claude / Gemini / Codex) |
-| `/model` | Switch model for active backend (with thinking level picker) |
-| `/summarizer` | Configure session summarization model |
-| `/status` | Backend, model, thinking level, session, context usage |
-| `/cost` | Estimated API cost for this chat (per-model breakdown) |
-| `/cost all` | All-time cost breakdown by model across all chats |
-| `/usage` | Usage per backend with limit warnings |
-| `/limits` | Configure usage limits per backend |
-| `/newchat` | Start a fresh conversation |
-| `/cwd <path>` | Set the working directory |
-| `/memory` | List stored memories |
-| `/forget <keyword>` | Remove a memory |
-| `/voice` | Toggle voice responses |
-| `/cron <desc>` | Schedule a task (or `/schedule`) |
-| `/cron` | List scheduled jobs (or `/jobs`) |
-| `/cron cancel <id>` | Cancel a scheduled job |
-| `/cron pause <id>` | Pause a job |
-| `/cron resume <id>` | Resume a job |
-| `/cron run <id>` | Trigger a job now |
-| `/cron runs [id]` | View run history |
-| `/cron edit <id>` | Edit a job |
-| `/cron health` | Scheduler health |
-| `/skills` | List skills from all backends |
-| `/skill-install <url>` | Install a skill from GitHub |
-| `/setup-profile` | Set up your user profile |
-| `/chats` | List authorized chats and aliases |
-| `/heartbeat` | Proactive awareness (on/off/interval/hours) |
-| `/history` | List recent session summaries |
-| `/stop` | Cancel the current task |
-| `/tools` | Configure which tools the agent can use |
-| `/permissions` | Switch permission mode |
-| `/verbose` | Tool visibility (off / normal / verbose) |
-| `/claude` `/gemini` `/codex` | Quick backend switch |
-| `/agents` | List active sub-agents |
-| `/tasks` | Show task board for current orchestration |
-| `/stopagent <id>` | Cancel a specific sub-agent |
-| `/stopall` | Cancel all sub-agents |
-| `/runners` | List registered CLI runners |
-| `/mcp` | List all MCP servers (central + backends) |
-
-### Permission Modes
-
-- **yolo** — Full autopilot, all tools auto-approved
-- **safe** — Only user-configured tools allowed
-- **readonly** — Read, Glob, Grep only
-- **plan** — Plan only, no execution
+| `/cwd <path>` | Set working directory |
+| `/permissions` | Permission mode (yolo/safe/readonly/plan) |
+| `/tools` | Configure allowed tools |
+| `/voice` | Toggle voice replies |
+| `/verbose` | Tool visibility level |
+| `/limits` | Usage limits per backend |
+
+### Memory & Context
+
+| Command | Description |
+|---------|-------------|
+| `/memory` | List memories |
+| `/forget <keyword>` | Remove memories |
+| `/history` | Past session summaries |
+| `/cost` | API cost breakdown |
+| `/skills` | Browse skills |
+| `/mcp` | MCP servers |
 
 ## Architecture
 
 ```
-Telegram --> TelegramChannel --> router (handleMessage)
-  |-- command --> handleCommand
-  |-- voice --> Groq Whisper STT --> askAgent
-  |-- photo/document/video --> handleMedia --> askAgent
-  '-- text --> askAgent --> sendResponse
-                            '--> [SEND_FILE:/path] --> channel.sendFile
+Telegram → TelegramChannel → router (handleMessage)
+  ├── command → handleCommand
+  ├── voice → Groq Whisper STT → askAgent
+  ├── photo/document/video → handleMedia → askAgent
+  └── text → askAgent → sendResponse
+                         └── [SEND_FILE:/path] → channel.sendFile
 ```
 
-The core `askAgent()` function delegates to the active backend's adapter, which handles CLI arg construction, NDJSON parsing, and env setup. All state is persisted in SQLite with FTS5 full-text search.
+`askAgent()` delegates to the active backend adapter, which constructs CLI args, spawns the subprocess, and parses NDJSON output. All state lives in SQLite with FTS5 full-text search.
 
 ### Agent Orchestration
 
-CC-Claw can spawn and manage multiple sub-agents across different coding CLIs simultaneously:
-
 ```
-User: "Have Claude review the code while Gemini researches the API docs"
-  → Main agent calls spawn_agent(runner: "claude", task: "Review...", role: "reviewer")
-  → Main agent calls spawn_agent(runner: "gemini", task: "Research...", role: "worker")
-  → Sub-agents communicate via inbox, share data via whiteboard
-  → Results flow back to the main agent for synthesis
+"Have Claude review the code while Gemini researches the API docs"
+  → spawn_agent(runner: "claude", name: "code-reviewer", role: "reviewer")
+  → spawn_agent(runner: "gemini", name: "api-researcher", role: "researcher")
+  → Agents communicate via inbox, share data on whiteboard
+  → Results flow back to the main agent
 ```
 
-Sub-agents support task dependencies, role-based prompts (worker/reviewer/planner), idle detection, timeout enforcement, and per-orchestration cost tracking. See `docs/plans/2026-03-09-agent-orchestration-design.md` for the full design.
+Sub-agents support named agents with personas, 9 role presets, file-based templates, per-agent model/tool overrides, task dependencies, idle detection, and cost tracking.
 
-### MCP Management
+### Agent Templates
 
-MCP (Model Context Protocol) servers are managed centrally. `/mcp` shows all MCPs across all backends. Each backend's native MCPs are available when running through CC-Claw. The orchestrator MCP server gives agents tools for spawning sub-agents, messaging, and task management.
+Define reusable agents in `~/.cc-claw/agents/*.md`:
+
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities
+runner: claude
+role: reviewer
+model: claude-sonnet-4-6
+---
+You are a senior security engineer...
+```
+
+The main agent discovers templates via `list_templates` and spawns them by name.
 
 ### Adding a CLI Runner
 
-Users can add any coding CLI as a sub-agent runner without code changes:
+No code changes needed:
 
 1. Tell CC-Claw: *"Onboard cursor CLI as a sub-agent"*
-2. The agent discovers capabilities, tests the CLI, and creates a JSON config at `~/.cc-claw/runners/`
-3. The new runner is immediately available via `/runners`
-
-For developers: create a JSON runner config (see `src/agents/runners/config-types.ts`) or a TypeScript adapter.
+2. The agent discovers capabilities, writes a JSON config to `~/.cc-claw/runners/`
+3. Available immediately via `/runners`
 
 ### Adding a Channel
 
-1. Create `src/channels/<name>.ts` implementing the `Channel` interface
-2. Register it in `src/index.ts`
+1. Implement the `Channel` interface in `src/channels/<name>.ts`
+2. Implement `getCapabilities()` for supported features
+3. Register in `src/index.ts`
 
-The router handles all message logic — the channel only delivers and sends messages.
+Notifications broadcast to all channels. Health monitored with auto-reconnection.
 
 ## Environment Variables
 
@@ -224,22 +236,22 @@ Set in `~/.cc-claw/.env` (created by `cc-claw setup`):
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `TELEGRAM_BOT_TOKEN` | Yes | From @BotFather |
-| `ALLOWED_CHAT_ID` | Yes | Comma-separated chat IDs (your user ID + group IDs) |
+| `ALLOWED_CHAT_ID` | Yes | Comma-separated chat IDs |
 | `CLAUDE_CODE_USE_VERTEX` | For Claude | Set to `1` |
-| `CLOUD_ML_REGION` | For Claude | e.g. `us-east5` |
-| `ANTHROPIC_VERTEX_PROJECT_ID` | For Claude | Your GCP project |
+| `CLOUD_ML_REGION` | For Claude | e.g., `us-east5` |
+| `ANTHROPIC_VERTEX_PROJECT_ID` | For Claude | GCP project ID |
 | `GROQ_API_KEY` | No | Voice transcription |
-| `ELEVENLABS_API_KEY` | No | Voice replies (TTS) |
+| `ELEVENLABS_API_KEY` | No | Voice replies |
 | `GEMINI_API_KEY` | No | Video analysis |
-| `DASHBOARD_ENABLED` | No | Set to `1` for web dashboard |
-| `DASHBOARD_TOKEN` | No | Fixed auth token for dashboard API (auto-generated if not set) |
-| `CLAUDE_CODE_EXECUTABLE` | No | Path to claude CLI (auto-detected) |
-| `GEMINI_CLI_EXECUTABLE` | No | Path to gemini CLI (auto-detected) |
-| `CODEX_EXECUTABLE` | No | Path to codex CLI (auto-detected) |
-| `EMBEDDING_PROVIDER` | No | Embedding provider: `ollama` (default), `gemini`, `openai`, `off` |
-| `MEMORY_VECTOR_WEIGHT` | No | Vector vs keyword weight for memory search (default: `0.7`) |
-| `OLLAMA_URL` | No | Ollama server URL (default: `http://localhost:11434`) |
-| `CC_CLAW_HOME` | No | Config dir (default: `~/.cc-claw`) |
+| `DASHBOARD_ENABLED` | No | `1` for web dashboard on port 3141 |
+| `EMBEDDING_PROVIDER` | No | `ollama` (default), `gemini`, `openai`, `off` |
+| `CC_CLAW_HOME` | No | Config directory (default: `~/.cc-claw`) |
+
+## Documentation
+
+- **[Quick Start](docs/QUICKSTART.md)** — Zero to working bot in 10 minutes
+- **[User Guide](docs/USER_GUIDE.md)** — Full reference for all features
+- **[Roadmap](docs/ROADMAP.md)** — Planned features
 
 ## License
 

package/dist/agents/mcp-server.js

@@ -9,19 +9,42 @@ var CHAT_ID = process.env.CC_CLAW_CHAT_ID ?? "";
 var AGENT_ID = process.env.CC_CLAW_AGENT_ID ?? "main";
 var DASHBOARD_TOKEN = process.env.CC_CLAW_DASHBOARD_TOKEN ?? "";
 var IS_SUB_AGENT = AGENT_ID !== "main";
+var MAX_RETRIES = 3;
+var RETRY_BASE_MS = 500;
 async function callApi(path, body) {
   const url = `${BASE_URL}${path}`;
   const headers = { "Content-Type": "application/json" };
   if (DASHBOARD_TOKEN) {
     headers["Authorization"] = `Bearer ${DASHBOARD_TOKEN}`;
   }
-  const opts = body ? { method: "POST", headers, body: JSON.stringify(body) } : { method: "GET", headers };
-  const res = await fetch(url, opts);
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`API error ${res.status}: ${text}`);
+  const reqInit = body ? { method: "POST", headers, body: JSON.stringify(body) } : { method: "GET", headers };
+  let lastError = null;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const res = await fetch(url, reqInit);
+      if (!res.ok) {
+        const text = await res.text();
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+          lastError = new Error(`API error ${res.status}: ${text}`);
+          await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+        throw new Error(`API error ${res.status}: ${text}`);
+      }
+      return res.json();
+    } catch (err) {
+      if (err instanceof TypeError && attempt < MAX_RETRIES) {
+        lastError = err;
+        await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+        continue;
+      }
+      throw err;
+    }
   }
-  return res.json();
+  throw lastError ?? new Error(`API call failed after ${MAX_RETRIES} retries`);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 var server = new McpServer({
   name: "cc-claw-orchestrator",
@@ -304,6 +327,35 @@ server.tool(
     return { content: [{ type: "text", text: `Broadcast sent to ${result.sent} agent(s).` }] };
   }
 );
+server.tool(
+  "report_progress",
+  "Report progress on a long-running task. Writes to the shared whiteboard and notifies the main agent. Call periodically (every few minutes) during tasks that take more than a couple of minutes.",
+  {
+    status: z.string().describe("Short status message (e.g., 'Analyzing 5 of 12 files', '70% complete')"),
+    detail: z.string().optional().describe("Optional longer description of current work")
+  },
+  async ({ status, detail }) => {
+    const shortId = AGENT_ID.slice(0, 8);
+    await callApi("/api/orchestrator/set-state", {
+      chatId: CHAT_ID,
+      key: `progress:${shortId}`,
+      value: JSON.stringify({ status, detail, timestamp: (/* @__PURE__ */ new Date()).toISOString() }),
+      setBy: AGENT_ID
+    });
+    if (IS_SUB_AGENT) {
+      await callApi("/api/orchestrator/send-message", {
+        chatId: CHAT_ID,
+        message: {
+          toAgentId: "main",
+          fromAgentId: AGENT_ID,
+          messageType: "status_update",
+          content: `Progress: ${status}${detail ? ` \u2014 ${detail}` : ""}`
+        }
+      });
+    }
+    return { content: [{ type: "text", text: `Progress reported: ${status}` }] };
+  }
+);
 server.tool(
   "list_runners",
   "List all registered CLI runners and their capabilities",

package/dist/cli.js

@@ -48,7 +48,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.1.0" : (() => {
+    VERSION = true ? "0.2.1" : (() => {
       try {
         return JSON.parse(readFileSync(join2(process.cwd(), "package.json"), "utf-8")).version ?? "unknown";
       } catch {
@@ -9996,11 +9996,17 @@ async function patchUsmForCcClaw(usmDir) {
         }
       }
     }
-    const oldFind = "find ~/.{claude,agents,gemini,gemini/antigravity,openclaw/workspace,cursor,config/opencode,config/goose,roo,cline}/skills";
-    const newFind = "find ~/.{claude,agents,gemini,gemini/antigravity,openclaw/workspace,cc-claw/workspace,cursor,config/opencode,config/goose,roo,cline}/skills";
-    if (content.includes(oldFind)) {
-      content = content.replace(oldFind, newFind);
-      patched = true;
+    const findPatterns = [
+      "find ~/.{claude,agents,gemini/antigravity,openclaw/workspace,cursor,config/opencode,config/goose,roo,cline}/skills",
+      "find ~/.{claude,agents,gemini,gemini/antigravity,openclaw/workspace,cursor,config/opencode,config/goose,roo,cline}/skills"
+    ];
+    for (const oldFind of findPatterns) {
+      if (content.includes(oldFind) && !content.includes("cc-claw/workspace")) {
+        const newFind = oldFind.replace("openclaw/workspace,", "openclaw/workspace,cc-claw/workspace,");
+        content = content.replace(oldFind, newFind);
+        patched = true;
+        break;
+      }
     }
     if (patched) {
       await writeFile3(skillPath, content, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-claw",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CC-Claw: Personal AI assistant on Telegram — multi-backend (Claude, Gemini, Codex), sub-agent orchestration, MCP management",
   "type": "module",
   "main": "dist/cli.js",