<img src="claudebot-logo.png" alt="ClaudeBot" width="160" /> <h1 align="center">ClaudeBot</h1> Not a pipe to Claude. A command center on your phone. <a href="README.zh-TW.md">繁體中文</a> | English <a href="https://jeffrey0117.github.io/ClaudeBot/">Documentation</a> · <a href="https://jeffrey0117.github.io/ClaudeBot/guide.html">Guide</a> · <a href="https://github.com/Jeffrey0117/claudebot-plugins">Plugin Store</a>

Send a Telegram message. Claude rewrites your codebase. Stream the output live. Switch AI models mid-conversation. Queue 10 tasks and walk away. All from your phone.

No API keys. No cloud relay. ClaudeBot calls the CLI tools already on your machine — you own the entire pipeline.

Why ClaudeBot?

Most "Telegram + AI" projects are thin wrappers — paste a prompt, get a response. ClaudeBot is a platform:

You send a message, AI edits your code — real files, real git repos, full project context
Live streaming — responses stream into Telegram in real-time, draft-style editing every 300ms
Multi-AI routing — Claude for heavy lifting, Gemini for quick tasks, auto-router picks for you
Queue system — fire off multiple requests, they execute in order with cross-bot mutex locks
Session memory — conversations persist per-project via --resume, context never drops
Plugins at zero AI cost — screenshots, dice, timers, system info, web search — instant, free
Multi-bot from one codebase — run 5+ bots, add new ones with /newbot from Telegram
Voice-to-code — speak into Telegram, local Sherpa-ONNX transcribes, AI executes
Remote pairing — /pair a remote machine, AI reads & writes files there via WebSocket + MCP
AI directives — Claude autonomously triggers commands, sends files, asks questions with buttons
4-layer memory — bookmarks, pins, AI memory, and vault indexing keep context across sessions
Git worktree isolation — multiple bots work on the same project simultaneously on separate branches
Deep analysis — /deep switches to Opus + subagents for multi-angle investigation
Parallel execution — /parallel runs multiple tasks concurrently in separate worktrees
Cross-project delegation — AI detects when another project needs changes and auto-queues the task

How It Compares

| | ClaudeBot | tmux bridge | API wrapper | |---|---|---|---| | Output | Real-time draft streaming (300ms) | After completion | N/A | | Concurrency | Queue + cross-bot file lock | Single request | N/A | | Auth | Chat ID + bcrypt + rate limit | None | API key | | Multi-project | Session per project, auto-resume | Single session | N/A | | UI | Buttons, suggestions, voice | Plain text | Web form | | Extensibility | Plugin system + Plugin Store | Shell scripts | YAML config | | Memory | 4-layer (bookmark/pin/AI/vault) | None | Stateless | | Remote | WebSocket pairing with 10 MCP tools | SSH only | N/A |

Architecture

Telegram ──> ClaudeBot ──> Claude / Gemini / Codex
  (you)          │              │
              Plugins       Projects ──> @run(other-project)
           (zero cost)         │
                          CloudPipe ──> Auto-deploy

Features

AI Directive System

Claude doesn't just reply — it takes action. The AI can embed directives in its responses that the bot intercepts and executes:

| Directive | What It Does | Example | |-----------|-------------|---------| | @cmd(/command) | Execute any bot command | @cmd(/restart), @cmd(/schedule bitcoin 09:00) | | @file(path) | Send a file to the user | @file(report.md) | | @confirm(q\|a\|b) | Show inline buttons for choices | @confirm(Which DB?\|PostgreSQL\|SQLite) | | @notify(msg) | Send a standalone notification | @notify(Build complete, 0 errors) | | @run(project) | Delegate a task to another project | @run(CloudPipe) update the endpoint | | @pipe(service.action) | Call CloudPipe APIs | @pipe(monitor.status) |

You say "set a daily Bitcoin alert at 9am" and Claude responds with a confirmation while silently executing @cmd(/schedule bitcoin 09:00). It just works.

4-Layer Memory System

Context is the hardest problem in AI chat. ClaudeBot solves it with four complementary layers:

| Layer | Command | Persistence | Use Case | |-------|---------|-------------|----------| | Bookmarks | /save → 📌 | Per-project JSON | Quick recall of code snippets, configs | | Context Pins | /save → 📎 | Auto-injected every prompt | "Always remember: we use Prisma, not Sequelize" | | AI Memory | /save → 🧠 | External knowledge base | Long-term project knowledge | | Vault | /vault | Message index | Search/recall any past conversation |

Vault silently indexes every message. When the AI loses context, /vault inject pulls relevant history back in. /vault summary generates a digest of today's conversation.

Context Digest — Claude generates a structured [CTX] block with every response (status, summary, pending items, next steps). When you reply with just "OK" or "好", the bot auto-injects this digest so Claude knows exactly what you were discussing.

Smart UI

ClaudeBot turns Claude's responses into interactive Telegram UI:

Choice detection — numbered lists with selection prompts become inline buttons
Yes/No detection — questions at the end of responses get confirmation buttons
Follow-up suggestions — after each response, AI generates 1-3 actionable next steps as buttons
Parallel task detection — when you send a list of tasks, the bot suggests /parallel for concurrent execution

Multi-Bot & Git Worktree

Run 5+ bot instances from one codebase. Each bot gets its own git worktree branch:

ProjectName/           ← main branch (production)
ProjectName--bot1/     ← bot1's worktree
ProjectName--bot2/     ← bot2's worktree

WORKTREE_BRANCH=bot1 in .env → auto-creates isolated worktree
Queue, lock, and session all key on worktree path — zero conflicts
/deploy on worktree → commit → merge to main → push

Remote Pairing

Pair any machine to your bot. The AI operates on the remote filesystem via WebSocket:

Telegram → Bot (your PC) → WebSocket → Agent (remote machine)
                                          └── 11 MCP tools:
                                              read, write, list, search,
                                              grep, execute, system info,
                                              project overview, fetch, push,
                                              list projects

/pair code@192.168.1.50:3100 — connect
/projects — list project folders on the remote machine
/grab /path/to/file — download from remote
/rstatus — check remote system health
Doc push — send any file to the bot while paired → it lands on the remote machine
Remote-only users — set REMOTE_CHAT_IDS to grant users access only through remote pairing (blocked from local commands)
Quota management — allot plugin manages per-remote rate limits and weekly budgets (admin only)

Voice Pipeline

Telegram voice → OGG → ffmpeg 16kHz WAV → Sherpa-ONNX (local)
     → biaodian punctuation → optional Gemini refinement (⚡)

Fully offline ASR — no API calls for basic transcription
Ordered message buffer ensures voice + text arrive in exact send order
/asr on/off toggles voice recognition per user

Ordered Message Buffer

Messages arrive at the bot out of order (network latency, voice transcription delay). The buffer fixes this:

Keyed by Telegram message_id (ascending) per chat
Voice entries start as pending — block flush until transcribed
1-second text timer, 30-second staleness sweep
Auto-flush on project switch

Plugin Ecosystem

20+ built-in plugins, all at zero AI cost (no tokens consumed) — allot, browse, calc, clip, cost, dice, github, map, mcp, remote, reminder, scheduler, search, screenshot, stats, sysinfo, task, vault, write, and more.

Full plugin list & documentation →

Plugin Store — browse and install community plugins directly from Telegram:

/store          — browse available plugins
/install name   — install from registry
/uninstall name — remove
/reload         — hot-reload without restart

Productivity Tools

Todos (/todo, /todos) — per-project task lists, /todos all for cross-project view
Ideas (/idea, /ideas) — tag-categorized idea log with #dev, #biz, #life auto-icons
Task planner (/task) — daily schedule with time slots, status indicators (✅🔔⏰⬜), auto-notification
Scheduler (/schedule) — recurring daily pushes at fixed times
Reminders (/remind) — one-off timers with relative (5m) or absolute (14:30) time

Cross-Project Delegation

Claude can detect when a task spans multiple projects and auto-delegate:

You: "Update the API format and make ClaudeBot use the new format"
Claude: fixes ClaudeBot code, then:
  @run(CloudPipe) update the API endpoint to accept the new format

The bot auto-queues the task on the target project. Zero manual switching.

CloudPipe Integration

If you run CloudPipe, ClaudeBot can control it via @pipe:

@pipe(monitor.status)         ← check all monitored URLs
@pipe(monitor.add, URL)       ← add a health check
@pipe(gateway.tools)          ← list all cross-project MCP tools
@pipe(health)                 ← is CloudPipe running?

Live Draft Streaming

Claude's response streams directly into the Telegram message — you see it being written in real-time:

300ms throttled edits — smooth updates without API spam
Auto-strips internal metadata — [CTX] blocks never leak into your view
Graceful fallback — if editing fails, dirt

ClaudeBot

Install / Use

README