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

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

Read commands work offline (direct DB access). Write commands require the daemon.

Telegram Commands

Core

Backend & Model

Scheduling

Agents

Settings

Memory & Context

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

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

Documentation

• Quick Start — Zero to working bot in 10 minutes
• User Guide — Full reference for all features
• Roadmap — Planned features

License

MIT