{"id":47231552,"url":"https://github.com/jeffrey0117/claudebot","last_synced_at":"2026-06-08T03:04:06.323Z","repository":{"id":338576406,"uuid":"1157165153","full_name":"Jeffrey0117/ClaudeBot","owner":"Jeffrey0117","description":"Not a pipe to Claude. A command center on your phone. — Telegram bot for Claude Code CLI with plugin system, multi-bot, queue, streaming, and hot-reload.","archived":false,"fork":false,"pushed_at":"2026-05-23T18:31:32.000Z","size":20583,"stargazers_count":61,"open_issues_count":0,"forks_count":13,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-23T19:17:25.055Z","etag":null,"topics":["bot","claude","claude-code","telegram","telegram-bot","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jeffrey0117.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T14:05:15.000Z","updated_at":"2026-05-23T18:31:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Jeffrey0117/ClaudeBot","commit_stats":null,"previous_names":["jeffrey0117/claudebot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Jeffrey0117/ClaudeBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jeffrey0117%2FClaudeBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jeffrey0117%2FClaudeBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jeffrey0117%2FClaudeBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jeffrey0117%2FClaudeBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jeffrey0117","download_url":"https://codeload.github.com/Jeffrey0117/ClaudeBot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jeffrey0117%2FClaudeBot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","claude","claude-code","telegram","telegram-bot","typescript"],"created_at":"2026-03-13T20:29:42.881Z","updated_at":"2026-05-24T00:01:36.043Z","avatar_url":"https://github.com/Jeffrey0117.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"claudebot-logo.png\" alt=\"ClaudeBot\" width=\"160\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eClaudeBot\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eNot a pipe to Claude. A command center on your phone.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.zh-TW.md\"\u003e繁體中文\u003c/a\u003e | English\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://jeffrey0117.github.io/ClaudeBot/\"\u003eDocumentation\u003c/a\u003e ·\n  \u003ca href=\"https://jeffrey0117.github.io/ClaudeBot/guide.html\"\u003eGuide\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/Jeffrey0117/claudebot-plugins\"\u003ePlugin Store\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nSend 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.\n\nNo API keys. No cloud relay. ClaudeBot calls the CLI tools already on your machine — you own the entire pipeline.\n\n## Why ClaudeBot?\n\nMost \"Telegram + AI\" projects are thin wrappers — paste a prompt, get a response. ClaudeBot is a **platform**:\n\n- **You send a message, AI edits your code** — real files, real git repos, full project context\n- **Live streaming** — responses stream into Telegram in real-time, draft-style editing every 300ms\n- **Multi-AI routing** — Claude for heavy lifting, Gemini for quick tasks, auto-router picks for you\n- **Queue system** — fire off multiple requests, they execute in order with cross-bot mutex locks\n- **Session memory** — conversations persist per-project via `--resume`, context never drops\n- **Plugins at zero AI cost** — screenshots, dice, timers, system info, web search — instant, free\n- **Multi-bot from one codebase** — run 5+ bots, add new ones with `/newbot` from Telegram\n- **Voice-to-code** — speak into Telegram, local Sherpa-ONNX transcribes, AI executes\n- **Remote pairing** — `/pair` a remote machine, AI reads \u0026 writes files there via WebSocket + MCP\n- **AI directives** — Claude autonomously triggers commands, sends files, asks questions with buttons\n- **4-layer memory** — bookmarks, pins, AI memory, and vault indexing keep context across sessions\n- **Git worktree isolation** — multiple bots work on the same project simultaneously on separate branches\n- **Deep analysis** — `/deep` switches to Opus + subagents for multi-angle investigation\n- **Parallel execution** — `/parallel` runs multiple tasks concurrently in separate worktrees\n- **Cross-project delegation** — AI detects when another project needs changes and auto-queues the task\n\n## How It Compares\n\n| | ClaudeBot | tmux bridge | API wrapper |\n|---|---|---|---|\n| Output | Real-time draft streaming (300ms) | After completion | N/A |\n| Concurrency | Queue + cross-bot file lock | Single request | N/A |\n| Auth | Chat ID + bcrypt + rate limit | None | API key |\n| Multi-project | Session per project, auto-resume | Single session | N/A |\n| UI | Buttons, suggestions, voice | Plain text | Web form |\n| Extensibility | Plugin system + Plugin Store | Shell scripts | YAML config |\n| Memory | 4-layer (bookmark/pin/AI/vault) | None | Stateless |\n| Remote | WebSocket pairing with 10 MCP tools | SSH only | N/A |\n\n## Architecture\n\n```\nTelegram ──\u003e ClaudeBot ──\u003e Claude / Gemini / Codex\n  (you)          │              │\n              Plugins       Projects ──\u003e @run(other-project)\n           (zero cost)         │\n                          CloudPipe ──\u003e Auto-deploy\n```\n\n## Features\n\n### AI Directive System\n\nClaude doesn't just reply — it **takes action**. The AI can embed directives in its responses that the bot intercepts and executes:\n\n| Directive | What It Does | Example |\n|-----------|-------------|---------|\n| `@cmd(/command)` | Execute any bot command | `@cmd(/restart)`, `@cmd(/schedule bitcoin 09:00)` |\n| `@file(path)` | Send a file to the user | `@file(report.md)` |\n| `@confirm(q\\|a\\|b)` | Show inline buttons for choices | `@confirm(Which DB?\\|PostgreSQL\\|SQLite)` |\n| `@notify(msg)` | Send a standalone notification | `@notify(Build complete, 0 errors)` |\n| `@run(project)` | Delegate a task to another project | `@run(CloudPipe) update the endpoint` |\n| `@pipe(service.action)` | Call CloudPipe APIs | `@pipe(monitor.status)` |\n\nYou 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.\n\n### 4-Layer Memory System\n\nContext is the hardest problem in AI chat. ClaudeBot solves it with four complementary layers:\n\n| Layer | Command | Persistence | Use Case |\n|-------|---------|-------------|----------|\n| **Bookmarks** | `/save` → 📌 | Per-project JSON | Quick recall of code snippets, configs |\n| **Context Pins** | `/save` → 📎 | Auto-injected every prompt | \"Always remember: we use Prisma, not Sequelize\" |\n| **AI Memory** | `/save` → 🧠 | External knowledge base | Long-term project knowledge |\n| **Vault** | `/vault` | Message index | Search/recall any past conversation |\n\n**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.\n\n**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.\n\n### Smart UI\n\nClaudeBot turns Claude's responses into interactive Telegram UI:\n\n- **Choice detection** — numbered lists with selection prompts become inline buttons\n- **Yes/No detection** — questions at the end of responses get confirmation buttons\n- **Follow-up suggestions** — after each response, AI generates 1-3 actionable next steps as buttons\n- **Parallel task detection** — when you send a list of tasks, the bot suggests `/parallel` for concurrent execution\n\n### Multi-Bot \u0026 Git Worktree\n\nRun 5+ bot instances from one codebase. Each bot gets its own git worktree branch:\n\n```\nProjectName/           ← main branch (production)\nProjectName--bot1/     ← bot1's worktree\nProjectName--bot2/     ← bot2's worktree\n```\n\n- `WORKTREE_BRANCH=bot1` in `.env` → auto-creates isolated worktree\n- Queue, lock, and session all key on worktree path — zero conflicts\n- `/deploy` on worktree → commit → merge to main → push\n\n### Remote Pairing\n\nPair any machine to your bot. The AI operates on the remote filesystem via WebSocket:\n\n```\nTelegram → Bot (your PC) → WebSocket → Agent (remote machine)\n                                          └── 11 MCP tools:\n                                              read, write, list, search,\n                                              grep, execute, system info,\n                                              project overview, fetch, push,\n                                              list projects\n```\n\n- `/pair code@192.168.1.50:3100` — connect\n- `/projects` — list project folders on the remote machine\n- `/grab /path/to/file` — download from remote\n- `/rstatus` — check remote system health\n- **Doc push** — send any file to the bot while paired → it lands on the remote machine\n- **Remote-only users** — set `REMOTE_CHAT_IDS` to grant users access only through remote pairing (blocked from local commands)\n- **Quota management** — `allot` plugin manages per-remote rate limits and weekly budgets (admin only)\n\n### Voice Pipeline\n\n```\nTelegram voice → OGG → ffmpeg 16kHz WAV → Sherpa-ONNX (local)\n     → biaodian punctuation → optional Gemini refinement (⚡)\n```\n\n- Fully offline ASR — no API calls for basic transcription\n- Ordered message buffer ensures voice + text arrive in exact send order\n- `/asr on/off` toggles voice recognition per user\n\n### Ordered Message Buffer\n\nMessages arrive at the bot out of order (network latency, voice transcription delay). The buffer fixes this:\n\n- Keyed by Telegram `message_id` (ascending) per chat\n- Voice entries start as `pending` — block flush until transcribed\n- 1-second text timer, 30-second staleness sweep\n- Auto-flush on project switch\n\n### Plugin Ecosystem\n\n20+ 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.\n\n**[Full plugin list \u0026 documentation →](https://github.com/Jeffrey0117/claudebot-plugins)**\n\n**Plugin Store** — browse and install community plugins directly from Telegram:\n```\n/store          — browse available plugins\n/install name   — install from registry\n/uninstall name — remove\n/reload         — hot-reload without restart\n```\n\n### Productivity Tools\n\n- **Todos** (`/todo`, `/todos`) — per-project task lists, `/todos all` for cross-project view\n- **Ideas** (`/idea`, `/ideas`) — tag-categorized idea log with `#dev`, `#biz`, `#life` auto-icons\n- **Task planner** (`/task`) — daily schedule with time slots, status indicators (✅🔔⏰⬜), auto-notification\n- **Scheduler** (`/schedule`) — recurring daily pushes at fixed times\n- **Reminders** (`/remind`) — one-off timers with relative (`5m`) or absolute (`14:30`) time\n\n### Cross-Project Delegation\n\nClaude can detect when a task spans multiple projects and auto-delegate:\n\n```\nYou: \"Update the API format and make ClaudeBot use the new format\"\nClaude: fixes ClaudeBot code, then:\n  @run(CloudPipe) update the API endpoint to accept the new format\n```\n\nThe bot auto-queues the task on the target project. Zero manual switching.\n\n### CloudPipe Integration\n\nIf you run [CloudPipe](https://github.com/Jeffrey0117/CloudPipe), ClaudeBot can control it via `@pipe`:\n\n```\n@pipe(monitor.status)         ← check all monitored URLs\n@pipe(monitor.add, URL)       ← add a health check\n@pipe(gateway.tools)          ← list all cross-project MCP tools\n@pipe(health)                 ← is CloudPipe running?\n```\n\n### Live Draft Streaming\n\nClaude's response streams directly into the Telegram message — you see it being written in real-time:\n\n- **300ms throttled edits** — smooth updates without API spam\n- **Auto-strips internal metadata** — `[CTX]` blocks never leak into your view\n- **Graceful fallback** — if editing fails, dirty draft is deleted and clean text sent fresh\n- **Private chat only** — groups get final message to avoid notification spam\n\n### Deep Analysis Mode\n\n```\n/deep analyze the auth module's security vulnerabilities\n```\n\nOne command switches to maximum reasoning power:\n\n- **Opus model** — strongest available Claude for deep thinking\n- **2x turn limit** — more room for multi-step analysis\n- **Subagent spawning** — Claude uses Task tool to explore from multiple angles (security, performance, architecture)\n- Powered by `data/subagent-spec.md` — a hot-reloadable spec that teaches Claude when and how to use subagents\n\n### Parallel Execution\n\n```\n/parallel\n1. Add login page to frontend\n2. Create user table in database\n3. Write API auth endpoints\n```\n\nEach task gets its own git worktree and Claude CLI process. All run concurrently. Results merge back when done.\n\n- `/parallel status` — check progress of all tasks\n- `/parallel cancel` — abort everything\n- Completion auto-merges each worktree branch back to main\n\n### Context Digest \u0026 Hot-Reload\n\nEvery Claude response generates a structured `[CTX]` block (status, summary, pending, next steps). This is the AI's working memory:\n\n- **Auto-injection** — when you reply \"OK\" or \"好\", the digest is injected so Claude never loses context\n- `/ctx` — inspect what Claude currently remembers\n- `/ctx clear` — reset the digest\n- `/ctx reload` — hot-reload the context spec and subagent spec without restarting\n\n### Additional Features\n\n- **Web dashboard** — real-time bot monitoring, heartbeat tracking, runner status\n- **Auto-commit** — timestamp-based git commits after AI completes work\n- **`/deploy`** — one command: commit → merge worktree to main → push\n- **`/sync`** — sync all worktree branches with master\n- **`/claudemd`** — auto-generate `CLAUDE.md` project documentation\n- **Bot bio auto-update** — Telegram bot description updates with current project \u0026 model\n- **Image analysis** — send photos, Claude analyzes them with vision\n- **Idle tidbits** — fun facts shown while waiting for long tasks\n- **Smart restart** — AI auto-restarts the bot after code changes, notifies all users\n- **Launcher admin notifications** — crash, respawn, startup events sent to your main bot chat\n\n## Security\n\n- **Chat ID + bcrypt** dual authentication\n- **Rate limiting** per user\n- **`shell: false`** on all process spawns\n- **Input validation** with zod\n- **Forbidden command protection** — prevents AI from running `taskkill /IM node.exe` (would kill itself)\n- **Protected files** — `.env`, `.sessions.json`, `.pairings.json` cannot be deleted by AI\n- **Cross-bot file lock** — prevents concurrent writes to the same project\n\n## Quick Start\n\n```bash\nnpx claudebot-app\n```\n\nOne command — downloads, installs, runs setup wizard, starts the bot.\n\n\u003e **Prerequisites:** Node.js 20+, [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (logged in).\n\u003e Optional: Gemini CLI, Python 3.11+ + [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) (voice recognition).\n\u003e\n\u003e ffmpeg is **bundled** — no separate install needed.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual install\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/Jeffrey0117/ClaudeBot.git\ncd ClaudeBot\nnpm install\nnpm run setup    # interactive wizard — creates .env\nnpm run dev      # or double-click start.bat on Windows\n```\n\n\u003c/details\u003e\n\n## Documentation\n\nFull setup guide, plugin development, multi-bot architecture, voice recognition, and command reference:\n\n**[jeffrey0117.github.io/ClaudeBot](https://jeffrey0117.github.io/ClaudeBot/)**\n\n---\n\n## Part of a Bigger Picture\n\nClaudeBot is one piece of a developer toolkit that covers your entire workflow — from setting up a new machine to shipping to production:\n\n| Tool | What It Does | Repo |\n|------|-------------|------|\n| [**DevUp**](https://github.com/Jeffrey0117/DevUp) | New machine? One command rebuilds your entire workspace | `npx devup-cli` |\n| [**ZeroSetup**](https://github.com/Jeffrey0117/ZeroSetup) | Any GitHub project, double-click to run. Zero setup steps | `npx zerosetup` |\n| **ClaudeBot** | Write and edit code from your phone via AI | *you are here* |\n| [**CloudPipe**](https://github.com/Jeffrey0117/CloudPipe) | Self-hosted Vercel. Auto-deploys, Telegram control, 31+ MCP tools | `npm i -g @jeffrey0117/cloudpipe` |\n| [**MemoryGuy**](https://github.com/Jeffrey0117/MemoryGuy) | Memory leak detection, safe optimization, port dashboard | Electron app |\n\n**ClaudeBot + CloudPipe** = you write code from Telegram, CloudPipe auto-deploys it, and notifies you when it's live. Idea to production without opening a laptop.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Jeffrey0117/ClaudeBot\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=Jeffrey0117%2FClaudeBot\u0026type=date\u0026legend=top-left)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffrey0117%2Fclaudebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffrey0117%2Fclaudebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffrey0117%2Fclaudebot/lists"}