{"_id":"@artickc/claude-telegram-bot","_rev":"2-f5ea3c3f0259c4ccf3c274d7a27ed909","name":"@artickc/claude-telegram-bot","dist-tags":{"latest":"3.1.1"},"versions":{"3.1.0":{"name":"@artickc/claude-telegram-bot","version":"3.1.0","keywords":["claude","claude-code","anthropic","telegram","telegram-bot","ai-agent","ai-coding-assistant","mobile-coding","chatops","devtools","daemon","cross-platform","grammy","acp","agent-client-protocol"],"license":"MIT","_id":"@artickc/claude-telegram-bot@3.1.0","maintainers":[{"name":"artickc","email":"artick.fl@gmail.com"}],"homepage":"https://github.com/artickc/claude-telegram-bot#readme","bugs":{"url":"https://github.com/artickc/claude-telegram-bot/issues"},"bin":{"claude-tg":"bin/claude-tg.mjs","claude-telegram-bot":"bin/claude-tg.mjs"},"dist":{"shasum":"484a14a2419e534f881a9d4e4521f8d1502774ac","tarball":"https://registry.npmjs.org/@artickc/claude-telegram-bot/-/claude-telegram-bot-3.1.0.tgz","fileCount":125,"integrity":"sha512-zhuXb5Y/Ip/bYn0Sda/JTXzn+gV8jqGxp5S/NpVNeRZ9BOO+xjZyzygj0UycMlrpmOsS2dzfpwmqJKPGvjMpSA==","signatures":[{"sig":"MEYCIQCTDM5svWX05NTWpW462KgbBXP+MD6I8ukNfEz9FK4yHwIhAKYo4DvGUyAf7n0BF6jMdvPlSEzaZv2o/Kl4OdGynzwC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":859806},"main":"src/index.ts","type":"module","engines":{"node":">=20"},"gitHead":"5e8794af1fc8f0db893fd4deddf6ed3b007458b7","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/**/*.test.ts","setup":"node scripts/setup.mjs","start":"tsx src/index.ts","service":"tsx src/cli.ts","typecheck":"tsc --noEmit","service:logs":"tsx src/cli.ts logs","prepublishOnly":"npm run typecheck","service:status":"tsx src/cli.ts status","install:service":"tsx src/cli.ts install","uninstall:service":"tsx src/cli.ts uninstall"},"_npmUser":{"name":"artickc","email":"artick.fl@gmail.com"},"repository":{"url":"git+https://github.com/artickc/claude-telegram-bot.git","type":"git"},"_npmVersion":"10.8.0","description":"Control Claude Code from Telegram over ACP. Switch native or custom OpenAI-compatible accounts, resume sessions, stream rich responses, queue follow-ups, and run 24/7 as a background service.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"tsx":"^4.19.2","diff":"^7.0.0","dotenv":"^16.4.7","grammy":"^1.30.0","@zed-industries/claude-code-acp":"^0.16.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.2","@types/diff":"^7.0.0","@types/node":"^22.10.0"},"optionalDependencies":{"@homebridge/node-pty-prebuilt-multiarch":"0.13.1"},"_npmOperationalInternal":{"tmp":"tmp/claude-telegram-bot_3.1.0_1785538260006_0.8838511624703058","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@artickc/claude-telegram-bot","version":"3.1.1","publishConfig":{"access":"public"},"description":"Control Claude Code from Telegram over ACP. Switch native or custom OpenAI-compatible accounts, resume sessions, stream rich responses, queue follow-ups, and run 24/7 as a background service.","type":"module","main":"src/index.ts","bin":{"claude-tg":"bin/claude-tg.mjs","claude-telegram-bot":"bin/claude-tg.mjs"},"engines":{"node":">=20"},"scripts":{"start":"tsx src/index.ts","dev":"tsx watch src/index.ts","typecheck":"tsc --noEmit","test":"node --import tsx --test test/**/*.test.ts","prepublishOnly":"npm run typecheck","setup":"node scripts/setup.mjs","service":"tsx src/cli.ts","install:service":"tsx src/cli.ts install","uninstall:service":"tsx src/cli.ts uninstall","service:status":"tsx src/cli.ts status","service:logs":"tsx src/cli.ts logs"},"keywords":["claude","claude-code","anthropic","telegram","telegram-bot","ai-agent","ai-coding-assistant","mobile-coding","chatops","devtools","daemon","cross-platform","grammy","acp","agent-client-protocol"],"repository":{"type":"git","url":"git+https://github.com/artickc/claude-telegram-bot.git"},"homepage":"https://github.com/artickc/claude-telegram-bot#readme","bugs":{"url":"https://github.com/artickc/claude-telegram-bot/issues"},"license":"MIT","dependencies":{"diff":"^7.0.0","dotenv":"^16.4.7","grammy":"^1.30.0","tsx":"^4.19.2","@zed-industries/claude-code-acp":"^0.16.2"},"optionalDependencies":{"@homebridge/node-pty-prebuilt-multiarch":"0.13.1"},"devDependencies":{"@types/diff":"^7.0.0","@types/node":"^22.10.0","typescript":"^5.7.2"},"_id":"@artickc/claude-telegram-bot@3.1.1","gitHead":"5e8794af1fc8f0db893fd4deddf6ed3b007458b7","_nodeVersion":"24.13.0","_npmVersion":"10.8.0","dist":{"integrity":"sha512-MgcSItsd+uPYKGv81TpFlL5TFdrr5tLJaIzh//IWosysrllp67M92WpFBDwW2bJPa+MRngNZoG8wltn2e9jkrg==","shasum":"189430b877cf92f92500b8431d56b0b723319f1f","tarball":"https://registry.npmjs.org/@artickc/claude-telegram-bot/-/claude-telegram-bot-3.1.1.tgz","fileCount":125,"unpackedSize":859806,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDimbnUClnidt2qe62/Uzv6UD+e/t+IbJM0dkN6ilY7/wIhAIJjm+RnV0ndEaeCIRGIZBDORIJf/TpB7DNWf5bgcwkg"}]},"_npmUser":{"name":"artickc","email":"artick.fl@gmail.com"},"directories":{},"maintainers":[{"name":"artickc","email":"artick.fl@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-telegram-bot_3.1.1_1785538410314_0.6329012254280675"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-31T22:50:59.833Z","modified":"2026-07-31T22:53:30.759Z","3.1.0":"2026-07-31T22:51:00.172Z","3.1.1":"2026-07-31T22:53:30.594Z"},"bugs":{"url":"https://github.com/artickc/claude-telegram-bot/issues"},"license":"MIT","homepage":"https://github.com/artickc/claude-telegram-bot#readme","keywords":["claude","claude-code","anthropic","telegram","telegram-bot","ai-agent","ai-coding-assistant","mobile-coding","chatops","devtools","daemon","cross-platform","grammy","acp","agent-client-protocol"],"repository":{"type":"git","url":"git+https://github.com/artickc/claude-telegram-bot.git"},"description":"Control Claude Code from Telegram over ACP. Switch native or custom OpenAI-compatible accounts, resume sessions, stream rich responses, queue follow-ups, and run 24/7 as a background service.","maintainers":[{"name":"artickc","email":"artick.fl@gmail.com"}],"readme":"# Claude Telegram Bot 🤖\n\n> **Control [Claude Code](https://docs.anthropic.com/en/docs/claude-code) from Telegram.** Your AI coding\n> assistant in your pocket — switch projects, resume and attach to live coding\n> sessions, stream answers with diffs, manage multiple Anthropic / OAuth accounts\n> with live plan usage, queue follow-ups, and run it 24/7 as a background service\n> on Windows, Linux, and macOS.\n\n![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)\n![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20Linux%20%7C%20macOS-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Powered by](https://img.shields.io/badge/powered%20by-Claude%20Code%20ACP-orange)\n\nA professional Telegram bridge that drives **Claude Code** over the **Agent\nClient Protocol (ACP)** via the official `claude-code-acp` adapter. Sign in with\nan Anthropic API key, a Claude Code OAuth token (`claude setup-token` /\n`CLAUDE_CODE_OAUTH_TOKEN`), or the host’s `claude /login` session — then plan,\nread files, run commands, and edit code from your phone.\n\nA fork of the earlier Grok ACP Telegram bot, remade for Claude Code (v3.0).\n\n---\n\n## ✨ Features\n\n| Capability | What it does |\n|---|---|\n| 🗂 **Projects** | `/projects` browses your folders and runs Claude in the one you pick. |\n| ♻️ **Resume sessions** | `/sessions` lists recent sessions; tap to resume. |\n| 🟢 **Connect to live sessions** | `/active` shows sessions running **right now** on your PC. Watch them live, or continue them. |\n| 🛑 **Kill a session / PID** | Each live card has a **🛑 Kill · pid N** button; `/killall` stops them all. |\n| 📡 **Live watch** | Follow a running session read-only in real time. |\n| 🧭 **Always-visible menu** | Persistent keyboard + pinned status panel (project, agent, model, session, queue, progress). |\n| ⏰ **Scheduled tasks** | Once / daily / weekly / monthly / every-N-minutes prompts in a chosen project. |\n| 🖼 **Multi-image prompts** | Albums + captions attached as image content blocks. |\n| 📜 **History** | `/history` shows the latest messages of any session. |\n| 🧩 **MCP control** | `/mcp` lists, health-checks, enables/disables MCP servers. |\n| 👥 **Subagent visibility** | See subagents start / work / finish. |\n| 📈 **Task progress bar** | `{progress: N%}` markers → green bar (`SHOW_PROGRESS`). |\n| 🔐 **Sign in from chat** | `/reauth` runs `claude setup-token` (URL/code in chat) or imports host login. |\n| 👥 **Multiple accounts** | `/accounts` saves Anthropic credentials or custom OpenAI-compatible providers; switches by **stop agent → apply profile → restart**. |\n| 🔁 **Auto-rotate on limits** | On plan limit / 402 / access errors, cycle other saved accounts once (toggle in `/accounts`). |\n| 📊 **Real plan usage** | `/usage` + `/accounts` show live **5-hour** and **weekly** utilization for OAuth, with **reset times**. |\n| ✅ **Auto-approve tools** | Default session auto-approve; optional pinned Approve/Deny. |\n| ⌨️ **Typing indicator** | Stays on for the whole turn. |\n| 📥 **Queued follow-ups** | Message while busy; `/btw`, `/flush`, `/queue`. |\n| ✏️ **Edit diffs** | Unified `diff` blocks with `+N -M` stats. |\n| 🔁 **Self-healing** | Auto-restart, re-bind, single-instance token lock (no 409 ghosts). |\n| 🖥 **Runs 24/7** | User-level service on Windows, Linux, macOS. |\n| 🔒 **Access control** | Restrict to specific Telegram user IDs. |\n\n---\n\n## ⚡ Install from npm\n\n```bash\nnpm install -g @artickc/claude-telegram-bot\n```\n\nConfig lives in a **canonical home** — `~/.claude/tg/` (`.env`, `logs/`, `data/`)\n— so the same config is found from any cwd. A `.env` in the current folder still\nwins. Print the path with `claude-tg setup --path`.\n\n```bash\nclaude-tg setup            # writes ~/.claude/tg/.env\nclaude-tg setup --path\n# edit .env: TELEGRAM_BOT_TOKEN, ALLOWED_USERS\n# optional: ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN\nclaude-tg run              # foreground\nclaude-tg install          # 24/7 background service\n```\n\n**Single-instance per token:** starting again terminates a ghost copy of *this*\nbot still polling Telegram. A plain `claude-tg run` **yields** to an already-running\nsupervised service. Sibling bots need their **own** BotFather tokens.\n\nSee **[docs/INSTALL.md](./docs/INSTALL.md)** and **[docs/UPGRADE.md](./docs/UPGRADE.md)**.\n\n---\n\n## 🚀 1-click install\n\n**Windows** — double-click `install.cmd`\n\n**Linux / macOS**:\n\n```bash\nchmod +x install.sh && ./install.sh\n```\n\n### Prerequisites\n\n- **Node.js 20+**\n- **Claude Code** optional on PATH (`claude`) — for `/reauth`’s `setup-token`; the\n  ACP agent is bundled via `@zed-industries/claude-code-acp`\n- Auth: **API key**, **`CLAUDE_CODE_OAUTH_TOKEN`**, or host **`claude /login`**\n- Bot token from [@BotFather](https://t.me/BotFather)\n- Your Telegram user ID from [@userinfobot](https://t.me/userinfobot)\n\n> ⚠️ **Dedicated bot token.** Telegram allows one long-polling consumer per\n> token. Config home is `~/.claude/tg` — separate from sibling bots.\n\n---\n\n## 🧑‍💻 Manual setup\n\n```bash\nnpm install\nnpm run setup\n# edit .env\nnpm start\n```\n\nNo build step — TypeScript via `tsx`.\n\n---\n\n## 💬 Commands\n\n```\n/menu         Persistent menu keyboard\n/projects     List / search / open projects\n/sessions     List & resume sessions\n/active       Sessions running now on the PC\n/running      Sessions this chat controls\n/killall      Kill all active sessions (confirm)\n/mcp          MCP servers · health-check · enable/disable\n/tasks        Scheduled tasks\n/newtask      Create a scheduled task (wizard)\n/history      Recent conversation history\n/new          Fresh session\n/status       Session, project & queue\n/usage        Account + live plan usage + context\n/btw <text>   Run now if idle, else next\n/flush        Send queued follow-ups now\n/queue        Show queue\n/clearqueue   Clear queue\n/cancel       Stop the current turn\n/unwatch      Stop live watch\n/model <id>   Switch model for this session\n/restart      Restart the Claude ACP agent\n/reauth       Sign in (setup-token) or import host login\n/accounts     Multi-account · usage resets · auto-rotate\n/help         Help\n```\n\nAnything that isn’t a command is a Claude prompt.\n\n---\n\n## 🔐 Auth & accounts\n\nFour ways to authenticate (priority when spawning the agent):\n\n1. **Saved native account** (`/accounts`) — paste `sk-ant-api…` or `sk-ant-oat…`\n2. **Saved custom provider** (`/accounts`) — base URL, API key, model, and\n   OpenAI **Chat Completions** or **Responses** wire API\n3. **`.env`** — `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY`\n4. **Host login** — `claude /login` → `~/.claude/.credentials.json`\n\n`/reauth` runs **`claude setup-token`**: authorization URL streams to chat, you\npaste the code, the bot captures the long-lived OAuth token and can save it.\n\n### `/accounts`\n\n- Add / rename / delete native credentials and custom providers\n- Fetch custom models from `/v1/models`, search the results, or enter a model manually\n- Select OpenAI Chat Completions or Responses per custom provider\n- One-tap **switch** (stop agent → apply the complete account profile → restart)\n- Switching back to a native account clears the custom base URL, model, and API bridge\n- **Auto-rotate** on plan limit, billing, or access errors\n- Per-OAuth-account **5-hour / weekly %** and **reset times** (Anthropic usage API)\n- Legacy **Grok/xAI** secrets from the fork are **not** supported and are removed on startup\n\n### `/usage`\n\nShows active identity, live OAuth plan windows (when applicable), session\ncontext %, turns, and saved account count.\n\n---\n\n## 🧩 How it works\n\n```\nTelegram  ──HTTPS──▶  Bot (grammY)\n                         │  spawns once\n                         ▼\n   claude-code-acp (stdio)  ◀── JSON-RPC 2.0 (ACP) ──▶  Bot\n                         │\n                         ├─ initialize\n                         ├─ authenticate (env key/token or host login — never browser)\n                         ├─ session/new · session/load\n                         ├─ session/prompt\n                         └─ session/update (streamed text, tools)\n```\n\nThe active credential is exported as `ANTHROPIC_API_KEY` or\n`CLAUDE_CODE_OAUTH_TOKEN` on every agent spawn. Bot-driven sessions are recorded\nunder `<data>/sessions/`.\n\n---\n\n## ⚙️ Configuration (`.env`)\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `TELEGRAM_BOT_TOKEN` | **yes** | — | Bot token from @BotFather. |\n| `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs. Empty = anyone (unsafe). |\n| `ANTHROPIC_API_KEY` | no | — | Anthropic API key (when not using OAuth / accounts). |\n| `CLAUDE_CODE_OAUTH_TOKEN` | no | — | Long-lived OAuth token from `claude setup-token`. |\n| `ANTHROPIC_BASE_URL` | no | — | Anthropic-compatible gateway base URL. |\n| `CLAUDE_MODEL` / `ANTHROPIC_MODEL` | no | `claude-opus-4-8` | Default model. |\n| `CLAUDE_CLI_PATH` | no | auto | Path to `claude` (for setup-token). |\n| `CLAUDE_ACP_PATH` | no | bundled | Override `claude-code-acp` entrypoint. |\n| `CLAUDE_WORKSPACE` | no | cwd | Default working directory. |\n| `CLAUDE_TG_DIR` | no | `~/.claude/tg` | Instance `.env` / `logs` / `data` home. |\n| `CLAUDE_TRUST_ALL_TOOLS` | no | `true` | Prefer permissive tool mode. |\n| `AUTO_APPROVE_PERMISSIONS` | no | `true` | Auto-approve ACP permission requests. |\n| `CLAUDE_TG_SINGLE_INSTANCE` | no | `true` | One running bot **per token**; take over ghosts. |\n| `PROJECT_ROOTS` | no | workspace parent + home | Roots for `/projects`. |\n| `SHOW_PROGRESS` | no | `true` | Parse `{progress: N%}` markers. |\n| `PROMPT_RETRY_ATTEMPTS` | no | `5` | Transient-error retries. |\n| `AUTO_FORK_ON_ERROR` | no | `true` | Fork session after exhausted retries / context full. |\n| `LOG_LEVEL` | no | `info` | `debug` \\| `info` \\| `warn` \\| `error`. |\n\nSee [`.env.example`](./.env.example) for the full list.\n\n---\n\n## 📁 Project layout\n\n```\nsrc/\n├── index.ts     Entry, shutdown, invalid-account prune\n├── cli.ts       run / install / status / logs\n├── config.ts    .env, ~/.claude/tg paths\n├── claude/      ACP client, transport, models, session log\n├── app/         accounts, credentials, OAuth usage, auth, locks\n├── sessions/    discovery, history, live tail\n├── projects/    project browser\n├── mcp/         MCP list/toggle + probe\n├── render/      MarkdownV2, diffs, tools, progress\n├── stream/      Incremental streaming\n├── service/     Windows / Linux / macOS daemon\n├── tasks/       Scheduled tasks\n└── bot/         grammY bot, handlers, rotator\n```\n\n---\n\n## 🔐 Security\n\nAuthorized Telegram users can run tools and edit files on the host.\n**Always set `ALLOWED_USERS`**, keep `.env` private, use a non-privileged user.\nSee [SECURITY.md](./SECURITY.md).\n\n---\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). `npm run typecheck` and `npm test`\nmust pass. By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md).\n\n```bash\nnpm version minor\ngit push --follow-tags\n```\n\n---\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md"}