Claude CLI ↔ Telegram

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 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.

Quick Start

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 <title> — rename
• /detach — disconnect; /cd <path> — 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
2. If unanswered for 5 minutes, Telegram sends inline buttons
3. Tap Approve/Deny on your phone - terminal prompt resolves automatically via TTY injection

Telegram sessions: inline buttons sent immediately as before.

Output Modes

Switch with /mode in Telegram or node mode.mjs <mode> in terminal.

Commands

Main

Sessions

Display & Output

Git

Quick Commands (instant, no Claude)

Mac Remote Control

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
• Groq API key (free): groq.com → API Keys
• Optional: FFmpeg (brew install ffmpeg) for voice fallback

Install

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:

{
  "botToken": "YOUR_BOT_TOKEN",
  "chatId": "YOUR_TELEGRAM_CHAT_ID",
  "groqApiKey": "YOUR_GROQ_API_KEY",
  "timeoutMs": 300000,
  "claudeTimeoutMs": 1800000,
}

Get your chatId: send any message to your bot, then open https://api.telegram.org/bot<TOKEN>/getUpdates — find chat.id.

Claude Code Hooks

Add to ~/.claude/settings.json for approval forwarding and completion notifications:

{
  "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

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 for guidelines.

License

MIT — Andrey Petrushikhin