https://github.com/Imolatte/claude-cli-telegram
Turn your Mac/Linux into a remote Claude Code terminal via Telegram. Spawns real CLI — sessions, streaming, approvals, voice, git panel, 30+ commands.
https://github.com/Imolatte/claude-cli-telegram
ai-agent anthropic automation claude-ai claude-code cli developer-tools mcp nodejs remote-access remote-terminal self-hosted telegram telegram-bot
Last synced: 3 days ago
JSON representation
Turn your Mac/Linux into a remote Claude Code terminal via Telegram. Spawns real CLI — sessions, streaming, approvals, voice, git panel, 30+ commands.
- Host: GitHub
- URL: https://github.com/Imolatte/claude-cli-telegram
- Owner: Imolatte
- License: mit
- Created: 2026-03-16T12:06:42.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T12:01:40.000Z (3 months ago)
- Last Synced: 2026-04-04T11:44:20.828Z (3 months ago)
- Topics: ai-agent, anthropic, automation, claude-ai, claude-code, cli, developer-tools, mcp, nodejs, remote-access, remote-terminal, self-hosted, telegram, telegram-bot
- Language: JavaScript
- Homepage: https://github.com/Imolatte/tg-claude#readme
- Size: 1.2 MB
- Stars: 13
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - Telegram-Claude (tg-claude) - A feature-rich Telegram bot that turns your machine into a remote Claude Code terminal driven from your phone: streaming tool progress, voice input, a git panel, Mac remote control, and 30+ commands. Its standout is the approval flow — dangerous-op Approve/Deny taps are injected straight into the real terminal prompt via `tmux send-keys`, so you authorize from your phone without killing the session or losing context. (Remote Control, Notifications & Voice I/O)
README
# Claude CLI ↔ Telegram
[](LICENSE)
[](https://nodejs.org)
[](https://claude.ai/claude-code)
**Turn your Mac or Linux machine into a remote Claude Code terminal — controlled from your phone via Telegram.**
Send 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).
```
You (Telegram) → Bot (Node.js) → Claude Code CLI → tools → response → You
```
| Voice input + streaming | Approval buttons | Full approval flow |
|---|---|---|
|  |  |  |
| /status | /sessions |
|---|---|
|  |  |
## Why This Exists
Anthropic'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.
**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.
| | Official Plugin | Claude CLI ↔ Telegram |
|---|---|---|
| Architecture | MCP bridge | Full bot wrapper around CLI |
| Session management | None | Auto-resume, rotate, switch, rename |
| Streaming progress | None | Live tool activity display |
| Dangerous op approval | None | Inline buttons (approve/deny) |
| Voice input | None | Groq Whisper STT |
| Git integration | None | Full panel (status/diff/log/push/pull) |
| Quick commands | None | Shell, system info, clipboard, files |
| i18n | None | EN + RU (auto-detected) |
## Quick Start
```bash
git clone https://github.com/Imolatte/claude-cli-telegram.git
cd tg-claude && cp config.example.json config.json
# Edit config.json — add bot token, chat ID, Groq API key
cd worker && npm install && node index.mjs
```
On first `/start`, a setup wizard walks you through OS, output mode, and token rotation settings.
## Features
### Input Types
- **Text** → Claude Code with full tool access
- **Voice** → Groq Whisper STT → Claude
- **Photos** → downloaded, passed to Claude for vision analysis
- **Files** → downloaded with original extension, passed to Claude
- **Forwards** → analyzed by Claude (text before forward auto-combined)
### Live Streaming Progress
While Claude works, see exactly what's happening:
```
🔧 Read: /src/auth.ts
🔧 Edit: /src/auth.ts
🔧 Bash: npm run build
📝 Writing response...
```
With `/codediff` enabled, edits show inline diffs:
```
🔧 Edit: /src/auth.ts
- import { getRegion } from './geo'
+ import { getRegion, USDT_PRICE } from './geo'
```
Token usage shown after each response: `↓3.2k ↑17k · 4.5s`
### Session Management
- Auto-resume sessions across messages (`--resume`)
- `/sessions` — inline keyboard to switch/delete
- `/new [name]` — start fresh; `/name ` — rename
- `/detach` — disconnect; `/cd ` — change working directory
- Token usage tracking per session
### Approval System
Dangerous operations require your approval:
- `git push/reset/clean`, `rm -rf`, Docker commands
- DB migrations (`prisma migrate`, `DROP TABLE`)
- Deploys (`vercel --prod`, `npm publish`)
- Sensitive file edits (`.env`, `docker-compose`, CI configs)
**Dual-channel approval** (terminal sessions):
1. Terminal shows its normal permission prompt (1/2/3)
2. If unanswered for 5 minutes, Telegram sends a notification
3. **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.
4. **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).
> **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.
**Telegram sessions**: inline buttons sent immediately as before.
### Output Modes
| Mode | Responses | Approvals | Use case |
|------|-----------|-----------|----------|
| `terminal` | Terminal | Terminal (+ TG after 5 min) | At desk |
| `hybrid` | Terminal | Telegram | Away, approvals on phone |
| `telegram` | Telegram | Telegram | Fully remote |
Switch with `/mode` in Telegram or `node mode.mjs ` in terminal.
## Commands
### Main
| Command | Description |
|---------|-------------|
| `/help` | Full command reference |
| `/status` | Mode, model, session, cwd, token progress bar |
| `/setup` | Re-run first-time setup wizard |
| `/stop` | Kill running Claude process |
| `/plan` | Toggle Plan / Build mode |
### Sessions
| Command | Description |
|---------|-------------|
| `/sessions` | Session list with connect/delete buttons |
| `/new [name]` | Start a new session |
| `/name ` | Rename current session |
| `/detach` | Disconnect from session |
| `/cd ` | Set working directory (`-` to reset) |
### Display & Output
| Command | Description |
|---------|-------------|
| `/codediff` | Toggle inline code diff in tool updates |
| `/mode` | Output mode: `terminal` / `hybrid` / `telegram` |
| `/model` | Switch model: `sonnet` / `opus` / `haiku` |
| `/botlang` | Bot UI language: `en` / `ru` |
| `/lang` | Voice recognition language: `ru` / `en` / `auto` |
### Git
| Command | Description |
|---------|-------------|
| `/git` | Git panel — Status, Diff, Log, Stage, Commit (AI message), Push, Pull |
| `/git ` | Direct git command, e.g. `/git log --oneline -5` |
| `/undo` | Rollback last commit (soft/hard, with confirmation) |
| `/diff [ref]` | Show git diff with pagination |
### Quick Commands (instant, no Claude)
| Command | Description |
|---------|-------------|
| `/sh ` | Run shell command |
| `/sys` | CPU, RAM, disk, battery, Wi-Fi, IP, uptime |
| `/clip` | Get/set clipboard |
| `/dl ` | Download file to Telegram |
| `/recent` | Recently edited files with one-tap download |
| `/screenshot ` | Screenshot via Puppeteer |
| `/cron ` | Set a reminder |
### Mac Remote Control
| Command | Description |
|---------|-------------|
| `/sleep` | Put Mac to sleep |
| `/lock` | Lock screen |
| `/shutdown` | Shut down (with confirmation) |
| `/reboot` | Restart (with confirmation) |
| `/battery` | Battery status with low-battery alerts |
### MCP: Claude → Telegram
Claude can proactively message you:
- `send_telegram(text)` — send text message
- `send_file_telegram(file_path, caption?)` — send file
### Group Chat Support
Add the bot to any Telegram group:
- Only the **owner** + users on the **allowed list** can interact
- Bot responds when **@mentioned** or when **replying** to its messages
- Dangerous operations from non-owners are automatically denied (owner gets a DM notification)
## Setup
### Prerequisites
- **Node.js** 20+
- **Claude Code CLI** installed and in PATH
- **Telegram Bot** — create via [@BotFather](https://t.me/BotFather)
- **Groq API key** (free): [groq.com](https://groq.com) → API Keys
- Optional: **FFmpeg** (`brew install ffmpeg`) for voice fallback
### Install
```bash
git clone https://github.com/Imolatte/claude-cli-telegram.git
cd tg-claude/worker && npm install
cp ../config.example.json ../config.json
```
### Configure
Edit `config.json`:
```json
{
"botToken": "YOUR_BOT_TOKEN",
"chatId": "YOUR_TELEGRAM_CHAT_ID",
"groqApiKey": "YOUR_GROQ_API_KEY",
"timeoutMs": 300000,
"claudeTimeoutMs": 1800000,
}
```
| Field | Description | Default |
|-------|-------------|---------|
| `botToken` | Telegram bot token from @BotFather | required |
| `chatId` | Your Telegram user ID (owner) | required |
| `groqApiKey` | Groq API key for voice STT | required |
| `timeoutMs` | Approval request timeout (ms) | 300000 (5 min) |
| `claudeTimeoutMs` | Max time for a single Claude task (ms) | 1800000 (30 min) |
**Get your `chatId`:** send any message to your bot, then open `https://api.telegram.org/bot/getUpdates` — find `chat.id`.
### Claude Code Hooks
Add to `~/.claude/settings.json` for approval forwarding and completion notifications:
```json
{
"hooks": {
"PreToolUse": [{
"matcher": "",
"hooks": [{ "type": "command", "command": "node /full/path/to/tg-claude/approval-hook.mjs", "timeout": 310 }]
}],
"Stop": [{
"hooks": [{ "type": "command", "command": "node /full/path/to/tg-claude/stop-hook.mjs", "timeout": 10 }]
}]
}
}
```
### Start
```bash
cd worker && node index.mjs
```
### Autostart (macOS)
Create `~/Library/LaunchAgents/com.tg-claude.worker.plist` pointing to `node index.mjs` in the worker directory. See `launcher.sh` for reference.
Logs: `/tmp/tg-claude.log`
## Architecture
```
worker/
index.mjs Bot core: polling, commands, streaming, task queue
executor.mjs Spawns Claude Code CLI, parses stream-json events
sessions.mjs Session state management
locale.mjs i18n: EN + RU strings
voice.mjs Groq STT with local Whisper fallback
mcp-telegram.mjs MCP server: send_telegram + send_file_telegram
approval-hook.mjs PreToolUse hook → dual-channel approval (terminal + TG)
stop-hook.mjs Stop hook → Telegram completion notification
CLAUDE.md Project context for Claude Code sessions
mode.mjs CLI: switch output mode (terminal/hybrid/telegram)
bot-system-prompt.md System prompt appended to Claude Code
config.json Credentials (gitignored)
```
**Design principles:**
- Minimal runtime dependencies (Puppeteer optional for screenshots)
- No frameworks — vanilla Node.js, ESM modules
- Single-process architecture — one `node index.mjs` runs everything
- File-based IPC between hooks and bot (via `/tmp/` files)
- Works on macOS and Linux
## i18n
Bot UI supports **English** and **Russian**. Language is auto-detected from your Telegram profile on first `/start`. Switch anytime with `/botlang`.
Adding a new language: copy the `en` object in `worker/locale.mjs`, translate all values, submit a PR.
## Security
- **Owner-only** — single `chatId`, all other users silently ignored
- **Group access control** — explicit allowlist per user ID
- **No credentials in repo** — `config.json` is gitignored
- **Duplicate protection** — kills previous instances on startup
- **Stale session recovery** — auto-retries without `--resume` on failure
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
[MIT](LICENSE) — Andrey Petrushikhin