Claude Telegram Bot 🤖

Control Claude Code from Telegram. Your AI coding assistant in your pocket — switch projects, resume and attach to live coding sessions, stream answers with diffs, manage multiple Anthropic / OAuth accounts with live plan usage, queue follow-ups, and run it 24/7 as a background service on Windows, Linux, and macOS.

A professional Telegram bridge that drives Claude Code over the Agent Client Protocol (ACP) via the official claude-code-acp adapter. Sign in with an Anthropic API key, a Claude Code OAuth token (claude setup-token / CLAUDE_CODE_OAUTH_TOKEN), or the host’s claude /login session — then plan, read files, run commands, and edit code from your phone.

A fork of the earlier Grok ACP Telegram bot, remade for Claude Code (v3.0).

✨ Features

| Capability | What it does | |---|---| | 🗂 Projects | /projects browses your folders and runs Claude in the one you pick. | | ♻️ Resume sessions | /sessions lists recent sessions; tap to resume. | | 🟢 Connect to live sessions | /active shows sessions running right now on your PC. Watch them live, or continue them. | | 🛑 Kill a session / PID | Each live card has a 🛑 Kill · pid N button; /killall stops them all. | | 📡 Live watch | Follow a running session read-only in real time. | | 🧭 Always-visible menu | Persistent keyboard + pinned status panel (project, agent, model, session, queue, progress). | | ⏰ Scheduled tasks | Once / daily / weekly / monthly / every-N-minutes prompts in a chosen project. | | 🖼 Multi-image prompts | Albums + captions attached as image content blocks. | | 📜 History | /history shows the latest messages of any session. | | 🧩 MCP control | /mcp lists, health-checks, enables/disables MCP servers. | | 👥 Subagent visibility | See subagents start / work / finish. | | 📈 Task progress bar | {progress: N%} markers → green bar (SHOW_PROGRESS). | | 🔐 Sign in from chat | /reauth runs claude setup-token (URL/code in chat) or imports host login. | | 👥 Multiple accounts | /accounts saves Anthropic credentials or custom OpenAI-compatible providers; switches by stop agent → apply profile → restart. | | 🔁 Auto-rotate on limits | On plan limit / 402 / access errors, cycle other saved accounts once (toggle in /accounts). | | 📊 Real plan usage | /usage + /accounts show live 5-hour and weekly utilization for OAuth, with reset times. | | ✅ Auto-approve tools | Default session auto-approve; optional pinned Approve/Deny. | | ⌨️ Typing indicator | Stays on for the whole turn. | | 📥 Queued follow-ups | Message while busy; /btw, /flush, /queue. | | ✏️ Edit diffs | Unified diff blocks with +N -M stats. | | 🔁 Self-healing | Auto-restart, re-bind, single-instance token lock (no 409 ghosts). | | 🖥 Runs 24/7 | User-level service on Windows, Linux, macOS. | | 🔒 Access control | Restrict to specific Telegram user IDs. |

⚡ Install from npm

npm install -g @artickc/claude-telegram-bot

Config lives in a canonical home — ~/.claude/tg/ (.env, logs/, data/) — so the same config is found from any cwd. A .env in the current folder still wins. Print the path with claude-tg setup --path.

claude-tg setup            # writes ~/.claude/tg/.env
claude-tg setup --path
# edit .env: TELEGRAM_BOT_TOKEN, ALLOWED_USERS
# optional: ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN
claude-tg run              # foreground
claude-tg install          # 24/7 background service

Single-instance per token: starting again terminates a ghost copy of this bot still polling Telegram. A plain claude-tg run yields to an already-running supervised service. Sibling bots need their own BotFather tokens.

See docs/INSTALL.md and docs/UPGRADE.md.

🚀 1-click install

Windows — double-click install.cmd

Linux / macOS:

chmod +x install.sh && ./install.sh

Prerequisites

• Node.js 20+
• Claude Code optional on PATH (claude) — for /reauth’s setup-token; the ACP agent is bundled via @zed-industries/claude-code-acp
• Auth: API key, CLAUDE_CODE_OAUTH_TOKEN, or host claude /login
• Bot token from @BotFather
• Your Telegram user ID from @userinfobot

⚠️ Dedicated bot token. Telegram allows one long-polling consumer per token. Config home is ~/.claude/tg — separate from sibling bots.

🧑‍💻 Manual setup

npm install
npm run setup
# edit .env
npm start

No build step — TypeScript via tsx.

💬 Commands

/menu         Persistent menu keyboard
/projects     List / search / open projects
/sessions     List & resume sessions
/active       Sessions running now on the PC
/running      Sessions this chat controls
/killall      Kill all active sessions (confirm)
/mcp          MCP servers · health-check · enable/disable
/tasks        Scheduled tasks
/newtask      Create a scheduled task (wizard)
/history      Recent conversation history
/new          Fresh session
/status       Session, project & queue
/usage        Account + live plan usage + context
/btw <text>   Run now if idle, else next
/flush        Send queued follow-ups now
/queue        Show queue
/clearqueue   Clear queue
/cancel       Stop the current turn
/unwatch      Stop live watch
/model <id>   Switch model for this session
/restart      Restart the Claude ACP agent
/reauth       Sign in (setup-token) or import host login
/accounts     Multi-account · usage resets · auto-rotate
/help         Help

Anything that isn’t a command is a Claude prompt.

🔐 Auth & accounts

Four ways to authenticate (priority when spawning the agent):

1. Saved native account (/accounts) — paste sk-ant-api… or sk-ant-oat…
2. Saved custom provider (/accounts) — base URL, API key, model, and OpenAI Chat Completions or Responses wire API
3. .env — CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY
4. Host login — claude /login → ~/.claude/.credentials.json

/reauth runs claude setup-token: authorization URL streams to chat, you paste the code, the bot captures the long-lived OAuth token and can save it.

/accounts

• Add / rename / delete native credentials and custom providers
• Fetch custom models from /v1/models, search the results, or enter a model manually
• Select OpenAI Chat Completions or Responses per custom provider
• One-tap switch (stop agent → apply the complete account profile → restart)
• Switching back to a native account clears the custom base URL, model, and API bridge
• Auto-rotate on plan limit, billing, or access errors
• Per-OAuth-account 5-hour / weekly % and reset times (Anthropic usage API)
• Legacy Grok/xAI secrets from the fork are not supported and are removed on startup

/usage

Shows active identity, live OAuth plan windows (when applicable), session context %, turns, and saved account count.

🧩 How it works

Telegram  ──HTTPS──▶  Bot (grammY)
                         │  spawns once
                         ▼
   claude-code-acp (stdio)  ◀── JSON-RPC 2.0 (ACP) ──▶  Bot
                         │
                         ├─ initialize
                         ├─ authenticate (env key/token or host login — never browser)
                         ├─ session/new · session/load
                         ├─ session/prompt
                         └─ session/update (streamed text, tools)

The active credential is exported as ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN on every agent spawn. Bot-driven sessions are recorded under <data>/sessions/.

⚙️ Configuration (.env)

| Variable | Required | Default | Description | |---|---|---|---| | TELEGRAM_BOT_TOKEN | yes | — | Bot token from @BotFather. | | ALLOWED_USERS | recommended | (all) | Comma-separated Telegram user IDs. Empty = anyone (unsafe). | | ANTHROPIC_API_KEY | no | — | Anthropic API key (when not using OAuth / accounts). | | CLAUDE_CODE_OAUTH_TOKEN | no | — | Long-lived OAuth token from claude setup-token. | | ANTHROPIC_BASE_URL | no | — | Anthropic-compatible gateway base URL. | | CLAUDE_MODEL / ANTHROPIC_MODEL | no | claude-opus-4-8 | Default model. | | CLAUDE_CLI_PATH | no | auto | Path to claude (for setup-token). | | CLAUDE_ACP_PATH | no | bundled | Override claude-code-acp entrypoint. | | CLAUDE_WORKSPACE | no | cwd | Default working directory. | | CLAUDE_TG_DIR | no | ~/.claude/tg | Instance .env / logs / data home. | | CLAUDE_TRUST_ALL_TOOLS | no | true | Prefer permissive tool mode. | | AUTO_APPROVE_PERMISSIONS | no | true | Auto-approve ACP permission requests. | | CLAUDE_TG_SINGLE_INSTANCE | no | true | One running bot per token; take over ghosts. | | PROJECT_ROOTS | no | workspace parent + home | Roots for /projects. | | SHOW_PROGRESS | no | true | Parse {progress: N%} markers. | | PROMPT_RETRY_ATTEMPTS | no | 5 | Transient-error retries. | | AUTO_FORK_ON_ERROR | no | true | Fork session after exhausted retries / context full. | | LOG_LEVEL | no | info | debug | info | warn | error. |

See .env.example for the full list.

📁 Project layout

src/
├── index.ts     Entry, shutdown, invalid-account prune
├── cli.ts       run / install / status / logs
├── config.ts    .env, ~/.claude/tg paths
├── claude/      ACP client, transport, models, session log
├── app/         accounts, credentials, OAuth usage, auth, locks
├── sessions/    discovery, history, live tail
├── projects/    project browser
├── mcp/         MCP list/toggle + probe
├── render/      MarkdownV2, diffs, tools, progress
├── stream/      Incremental streaming
├── service/     Windows / Linux / macOS daemon
├── tasks/       Scheduled tasks
└── bot/         grammY bot, handlers, rotator

🔐 Security

Authorized Telegram users can run tools and edit files on the host. Always set ALLOWED_USERS, keep .env private, use a non-privileged user. See SECURITY.md.

🤝 Contributing

See CONTRIBUTING.md. npm run typecheck and npm test must pass. By participating you agree to the Code of Conduct.

npm version minor
git push --follow-tags

📄 License

MIT