{"id":51551323,"url":"https://github.com/Imolatte/claude-cli-telegram","last_synced_at":"2026-07-12T14:01:17.667Z","repository":{"id":345036645,"uuid":"1183234627","full_name":"Imolatte/claude-cli-telegram","owner":"Imolatte","description":"Turn your Mac/Linux into a remote Claude Code terminal via Telegram. Spawns real CLI — sessions, streaming, approvals, voice, git panel, 30+ commands.","archived":false,"fork":false,"pushed_at":"2026-04-03T12:01:40.000Z","size":1262,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T11:44:20.828Z","etag":null,"topics":["ai-agent","anthropic","automation","claude-ai","claude-code","cli","developer-tools","mcp","nodejs","remote-access","remote-terminal","self-hosted","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"https://github.com/Imolatte/tg-claude#readme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Imolatte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-03-16T12:06:42.000Z","updated_at":"2026-04-03T12:01:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Imolatte/claude-cli-telegram","commit_stats":null,"previous_names":["imolatte/tg-claude","imolatte/claude-cli-telegram"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Imolatte/claude-cli-telegram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imolatte%2Fclaude-cli-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imolatte%2Fclaude-cli-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imolatte%2Fclaude-cli-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imolatte%2Fclaude-cli-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Imolatte","download_url":"https://codeload.github.com/Imolatte/claude-cli-telegram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imolatte%2Fclaude-cli-telegram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agent","anthropic","automation","claude-ai","claude-code","cli","developer-tools","mcp","nodejs","remote-access","remote-terminal","self-hosted","telegram","telegram-bot"],"created_at":"2026-07-10T00:00:52.211Z","updated_at":"2026-07-12T14:01:17.662Z","avatar_url":"https://github.com/Imolatte.png","language":"JavaScript","funding_links":[],"categories":["Remote Control, Notifications \u0026 Voice I/O"],"sub_categories":[],"readme":"# Claude CLI ↔ Telegram\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-CLI-blueviolet.svg)](https://claude.ai/claude-code)\n![GitHub stars](https://img.shields.io/github/stars/Imolatte/claude-cli-telegram?style=flat-square)\n![GitHub last commit](https://img.shields.io/github/last-commit/Imolatte/claude-cli-telegram?style=flat-square)\n![GitHub issues](https://img.shields.io/github/issues/Imolatte/claude-cli-telegram?style=flat-square)\n\n**Turn your Mac or Linux machine into a remote Claude Code terminal — controlled from your phone via Telegram.**\n\nSend a message from Telegram → bot spawns real Claude Code CLI → streams progress → sends response back. Not an API wrapper — runs the actual CLI with full tool access (Bash, Read, Write, Edit, Grep, Glob, etc).\n\n```\nYou (Telegram) → Bot (Node.js) → Claude Code CLI → tools → response → You\n```\n\n| Voice input + streaming | Approval buttons | Full approval flow |\n|---|---|---|\n| ![Voice and tools](assets/demo-voice-tools.jpg) | ![Approval](assets/demo-approval.jpg) | ![Approved](assets/demo-approved-deleted.jpg) |\n\n| /status | /sessions |\n|---|---|\n| ![Status](assets/demo-status.jpg) | ![Sessions](assets/demo-sessions.jpg) |\n\n## Why This Exists\n\nAnthropic's [official Telegram plugin](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) is a minimal MCP bridge — 3 tools, no history, no session management.\n\n**Claude CLI ↔ Telegram** is a full remote terminal: sessions, streaming progress, approval system for dangerous ops, git panel, voice input, file/photo handling, Mac remote control, and 30+ commands - all from your phone.\n\n| | Official Plugin | Claude CLI ↔ Telegram |\n|---|---|---|\n| Architecture | MCP bridge | Full bot wrapper around CLI |\n| Session management | None | Auto-resume, rotate, switch, rename |\n| Streaming progress | None | Live tool activity display |\n| Dangerous op approval | None | Inline buttons (approve/deny) |\n| Voice input | None | Groq Whisper STT |\n| Git integration | None | Full panel (status/diff/log/push/pull) |\n| Quick commands | None | Shell, system info, clipboard, files |\n| i18n | None | EN + RU (auto-detected) |\n\n## Quick Start\n\n```bash\ngit clone https://github.com/Imolatte/claude-cli-telegram.git\ncd tg-claude \u0026\u0026 cp config.example.json config.json\n# Edit config.json — add bot token, chat ID, Groq API key\ncd worker \u0026\u0026 npm install \u0026\u0026 node index.mjs\n```\n\nOn first `/start`, a setup wizard walks you through OS, output mode, and token rotation settings.\n\n## Features\n\n### Input Types\n- **Text** → Claude Code with full tool access\n- **Voice** → Groq Whisper STT → Claude\n- **Photos** → downloaded, passed to Claude for vision analysis\n- **Files** → downloaded with original extension, passed to Claude\n- **Forwards** → analyzed by Claude (text before forward auto-combined)\n\n### Live Streaming Progress\nWhile Claude works, see exactly what's happening:\n```\n🔧 Read: /src/auth.ts\n🔧 Edit: /src/auth.ts\n🔧 Bash: npm run build\n📝 Writing response...\n```\n\nWith `/codediff` enabled, edits show inline diffs:\n```\n🔧 Edit: /src/auth.ts\n- import { getRegion } from './geo'\n+ import { getRegion, USDT_PRICE } from './geo'\n```\n\nToken usage shown after each response: `↓3.2k ↑17k · 4.5s`\n\n### Session Management\n- Auto-resume sessions across messages (`--resume`)\n- `/sessions` — inline keyboard to switch/delete\n- `/new [name]` — start fresh; `/name \u003ctitle\u003e` — rename\n- `/detach` — disconnect; `/cd \u003cpath\u003e` — change working directory\n- Token usage tracking per session\n\n### Approval System\nDangerous operations require your approval:\n- `git push/reset/clean`, `rm -rf`, Docker commands\n- DB migrations (`prisma migrate`, `DROP TABLE`)\n- Deploys (`vercel --prod`, `npm publish`)\n- Sensitive file edits (`.env`, `docker-compose`, CI configs)\n\n**Dual-channel approval** (terminal sessions):\n1. Terminal shows its normal permission prompt (1/2/3)\n2. If unanswered for 5 minutes, Telegram sends a notification\n3. **With tmux** (recommended): Approve/Deny buttons - taps inject `1` or `3` directly into the native prompt via `tmux send-keys`. Session keeps running, no context lost.\n4. **Without tmux**: only a `Take over session` button is offered as fallback. It kills the terminal Claude and resumes the same session in Telegram (context preserved on disk, but in-memory state like the current plan/todos is lost).\n\n\u003e **Tip:** install [tmux](https://github.com/tmux/tmux) (`brew install tmux`) and launch Claude with `tmux new -A -s claude claude` (or add `alias cc='tmux new -A -s claude claude'` to your shell rc). Then dangerous-op approvals from Telegram answer the real terminal prompt without restarting anything. Without tmux only the takeover fallback works.\n\n**Telegram sessions**: inline buttons sent immediately as before.\n\n### Output Modes\n\n| Mode | Responses | Approvals | Use case |\n|------|-----------|-----------|----------|\n| `terminal` | Terminal | Terminal (+ TG after 5 min) | At desk |\n| `hybrid` | Terminal | Telegram | Away, approvals on phone |\n| `telegram` | Telegram | Telegram | Fully remote |\n\nSwitch with `/mode` in Telegram or `node mode.mjs \u003cmode\u003e` in terminal.\n\n## Commands\n\n### Main\n| Command | Description |\n|---------|-------------|\n| `/help` | Full command reference |\n| `/status` | Mode, model, session, cwd, token progress bar |\n| `/setup` | Re-run first-time setup wizard |\n| `/stop` | Kill running Claude process |\n| `/plan` | Toggle Plan / Build mode |\n\n### Sessions\n| Command | Description |\n|---------|-------------|\n| `/sessions` | Session list with connect/delete buttons |\n| `/new [name]` | Start a new session |\n| `/name \u003ctitle\u003e` | Rename current session |\n| `/detach` | Disconnect from session |\n| `/cd \u003cpath\u003e` | Set working directory (`-` to reset) |\n\n### Display \u0026 Output\n| Command | Description |\n|---------|-------------|\n| `/codediff` | Toggle inline code diff in tool updates |\n| `/mode` | Output mode: `terminal` / `hybrid` / `telegram` |\n| `/model` | Switch model: `sonnet` / `opus` / `haiku` |\n| `/botlang` | Bot UI language: `en` / `ru` |\n| `/lang` | Voice recognition language: `ru` / `en` / `auto` |\n\n### Git\n| Command | Description |\n|---------|-------------|\n| `/git` | Git panel — Status, Diff, Log, Stage, Commit (AI message), Push, Pull |\n| `/git \u003cargs\u003e` | Direct git command, e.g. `/git log --oneline -5` |\n| `/undo` | Rollback last commit (soft/hard, with confirmation) |\n| `/diff [ref]` | Show git diff with pagination |\n\n### Quick Commands (instant, no Claude)\n| Command | Description |\n|---------|-------------|\n| `/sh \u003ccmd\u003e` | Run shell command |\n| `/sys` | CPU, RAM, disk, battery, Wi-Fi, IP, uptime |\n| `/clip` | Get/set clipboard |\n| `/dl \u003cpath\u003e` | Download file to Telegram |\n| `/recent` | Recently edited files with one-tap download |\n| `/screenshot \u003curl\u003e` | Screenshot via Puppeteer |\n| `/cron \u003cXh/Xm\u003e \u003ctext\u003e` | Set a reminder |\n\n### Mac Remote Control\n| Command | Description |\n|---------|-------------|\n| `/sleep` | Put Mac to sleep |\n| `/lock` | Lock screen |\n| `/shutdown` | Shut down (with confirmation) |\n| `/reboot` | Restart (with confirmation) |\n| `/battery` | Battery status with low-battery alerts |\n\n### MCP: Claude → Telegram\nClaude can proactively message you:\n- `send_telegram(text)` — send text message\n- `send_file_telegram(file_path, caption?)` — send file\n\n### Group Chat Support\nAdd the bot to any Telegram group:\n- Only the **owner** + users on the **allowed list** can interact\n- Bot responds when **@mentioned** or when **replying** to its messages\n- Dangerous operations from non-owners are automatically denied (owner gets a DM notification)\n\n## Setup\n\n### Prerequisites\n- **Node.js** 20+\n- **Claude Code CLI** installed and in PATH\n- **Telegram Bot** — create via [@BotFather](https://t.me/BotFather)\n- **Groq API key** (free): [groq.com](https://groq.com) → API Keys\n- Optional: **FFmpeg** (`brew install ffmpeg`) for voice fallback\n\n### Install\n\n```bash\ngit clone https://github.com/Imolatte/claude-cli-telegram.git\ncd tg-claude/worker \u0026\u0026 npm install\ncp ../config.example.json ../config.json\n```\n\n### Configure\n\nEdit `config.json`:\n```json\n{\n  \"botToken\": \"YOUR_BOT_TOKEN\",\n  \"chatId\": \"YOUR_TELEGRAM_CHAT_ID\",\n  \"groqApiKey\": \"YOUR_GROQ_API_KEY\",\n  \"timeoutMs\": 300000,\n  \"claudeTimeoutMs\": 1800000,\n}\n```\n\n| Field | Description | Default |\n|-------|-------------|---------|\n| `botToken` | Telegram bot token from @BotFather | required |\n| `chatId` | Your Telegram user ID (owner) | required |\n| `groqApiKey` | Groq API key for voice STT | required |\n| `timeoutMs` | Approval request timeout (ms) | 300000 (5 min) |\n| `claudeTimeoutMs` | Max time for a single Claude task (ms) | 1800000 (30 min) |\n\n**Get your `chatId`:** send any message to your bot, then open `https://api.telegram.org/bot\u003cTOKEN\u003e/getUpdates` — find `chat.id`.\n\n### Claude Code Hooks\n\nAdd to `~/.claude/settings.json` for approval forwarding and completion notifications:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"\",\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"node /full/path/to/tg-claude/approval-hook.mjs\", \"timeout\": 310 }]\n    }],\n    \"Stop\": [{\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"node /full/path/to/tg-claude/stop-hook.mjs\", \"timeout\": 10 }]\n    }]\n  }\n}\n```\n\n### Start\n\n```bash\ncd worker \u0026\u0026 node index.mjs\n```\n\n### Autostart (macOS)\n\nCreate `~/Library/LaunchAgents/com.tg-claude.worker.plist` pointing to `node index.mjs` in the worker directory. See `launcher.sh` for reference.\n\nLogs: `/tmp/tg-claude.log`\n\n## Architecture\n\n```\nworker/\n  index.mjs           Bot core: polling, commands, streaming, task queue\n  executor.mjs         Spawns Claude Code CLI, parses stream-json events\n  sessions.mjs         Session state management\n  locale.mjs           i18n: EN + RU strings\n  voice.mjs            Groq STT with local Whisper fallback\n  mcp-telegram.mjs     MCP server: send_telegram + send_file_telegram\n\napproval-hook.mjs      PreToolUse hook → dual-channel approval (terminal + TG)\nstop-hook.mjs          Stop hook → Telegram completion notification\nCLAUDE.md              Project context for Claude Code sessions\nmode.mjs               CLI: switch output mode (terminal/hybrid/telegram)\nbot-system-prompt.md   System prompt appended to Claude Code\nconfig.json            Credentials (gitignored)\n```\n\n**Design principles:**\n- Minimal runtime dependencies (Puppeteer optional for screenshots)\n- No frameworks — vanilla Node.js, ESM modules\n- Single-process architecture — one `node index.mjs` runs everything\n- File-based IPC between hooks and bot (via `/tmp/` files)\n- Works on macOS and Linux\n\n## i18n\n\nBot UI supports **English** and **Russian**. Language is auto-detected from your Telegram profile on first `/start`. Switch anytime with `/botlang`.\n\nAdding a new language: copy the `en` object in `worker/locale.mjs`, translate all values, submit a PR.\n\n## Security\n\n- **Owner-only** — single `chatId`, all other users silently ignored\n- **Group access control** — explicit allowlist per user ID\n- **No credentials in repo** — `config.json` is gitignored\n- **Duplicate protection** — kills previous instances on startup\n- **Stale session recovery** — auto-retries without `--resume` on failure\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[MIT](LICENSE) — Andrey Petrushikhin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FImolatte%2Fclaude-cli-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FImolatte%2Fclaude-cli-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FImolatte%2Fclaude-cli-telegram/lists"}