CC-Claw

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, 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. Choose from ElevenLabs, Grok (xAI), or macOS 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

| Backend | CLI | Models | |---------|-----|--------| | Claude | claude | Opus 4.6, Sonnet 4.6, Haiku 4.5 | | Gemini | gemini | 3.1 Pro Preview, 3 Flash | | Codex | codex | GPT-5.4, GPT-5.3 Codex, GPT-5.2 Codex |

Prerequisites

• Node.js 20+
• 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

Install

npm install -g cc-claw

Upgrade

npm install -g cc-claw@latest    # Update to latest version
cc-claw --version                # Verify
cc-claw service restart          # Restart to pick up changes

No config changes or migrations needed.

Setup

cc-claw setup

The wizard walks you through:

1. Creating a Telegram bot and pasting the token
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

Config saved to ~/.cc-claw/.env.

Run

The setup wizard offers to install CC-Claw as a background service. If you skipped that step:

cc-claw service install     # Install + start as background service

cc-claw service restart     # Restart (pick up config changes)
cc-claw service stop        # Stop the daemon
cc-claw service status      # Check if running
cc-claw start               # Run in foreground (for debugging)

CLI

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 cron list           # Scheduled jobs
cc-claw --ai                # Generate AI skill file

| Group | Description | |-------|-------------| | service | start, stop, restart, status, install, uninstall | | status / doctor / logs | Diagnostics and monitoring | | chat / tui | Terminal AI chat | | backend / model / thinking | Backend and model management | | memory | list, search, add, forget, history | | cron / schedule | Scheduler (create, cancel, pause, resume, run) | | agents / tasks / runners | Agent orchestration | | 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 |

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) | | /summarize | Save session to memory without resetting | | /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

| Command | Description | |---------|-------------| | /agents | List sub-agents | | /tasks | Task board | | /stopagent <id> | Cancel one agent | | /stopall | Cancel all agents | | /runners | Available CLI runners |

Settings

| Command | Description | |---------|-------------| | /cwd <path> | Set working directory | | /permissions | Permission mode (yolo/safe/readonly/plan) | | /tools | Configure allowed tools | | /voice | Toggle voice replies | | /voice_config | Configure voice provider and voice | | /response_style | Set the AI response style (concise/normal/detailed) | | /verbose | Tool visibility level | | /limits | Usage limits per backend |

Memory & Context

| Command | Description | |---------|-------------| | /memory | List memories | | /remember <text> | Save a memory | | /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 → TTS (ElevenLabs/Grok/macOS)
  ├── photo/document/video → handleMedia → askAgent
  └── text → askAgent → sendResponse
                         └── [SEND_FILE:/path] → channel.sendFile

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

"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 named agents with personas, 9 role presets, file-based templates, per-agent model/tool overrides, task dependencies, idle detection, and cost tracking.

Agent Templates

Define reusable agents in ~/.cc-claw/agents/*.md:

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

No code changes needed:

1. Tell CC-Claw: "Onboard cursor CLI as a sub-agent"
2. The agent discovers capabilities, writes a JSON config to ~/.cc-claw/runners/
3. Available immediately via /runners

Adding a Channel

1. Implement the Channel interface in src/channels/<name>.ts
2. Implement getCapabilities() for supported features
3. Register in src/index.ts

Notifications broadcast to all channels. Health monitored with auto-reconnection.

Environment Variables

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 | | CLAUDE_CODE_USE_VERTEX | For Claude | Set to 1 | | 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 (ElevenLabs) | | XAI_API_KEY | No | Voice replies (Grok/xAI) | | GEMINI_API_KEY | No | Video analysis | | 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 — Zero to working bot in 10 minutes
• User Guide — Full reference for all features
• Roadmap — Planned features

License

MIT