TG Claude

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.

TG Claude 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/tg-claude.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 · ████░░░░ 52k/100k

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 with warning at 190k (auto-compaction by Claude Code CLI)

Terminal ↔ Telegram Session Sync (experimental — testing)

Status: feature is being tested. The problem: terminal and Telegram use separate Claude Code sessions, so progress/context is lost when switching between them.

One shared session between terminal and Telegram. Both read/write to worker/state.json. The session itself is a single .jsonl file on disk — not a copy, the same conversation.

How it works

Telegram → Terminal:

1. You work in terminal → session .jsonl file gets updated
2. You switch to Telegram and send a message
3. Bot detects a newer session exists → asks "Switch to session-name?" with ✅/❌ buttons
4. ✅ — bot resumes the terminal session. ❌ — stays in current, pins it (no more prompts)

Terminal → Telegram:

1. You work in Telegram → bot saves session to state.json
2. You switch to terminal and run cc
3. cc reads state.json, finds the freshest session, cds into its project directory, and runs claude --resume <id>

New session in Telegram:

• /new in Telegram creates a session in the same project directory as the previous one (or whatever you set via /cd)
• After first message, cc in terminal will pick it up

The cc command

Use cc instead of claude to continue the shared session. Works from any directory — auto-navigates to the project.

cc                    # resume the most recent shared session
cc "fix the bug"      # resume with a prompt

If no shared session found — falls back to claude -c (standard "continue last").

Pinned sessions

When you manually select a session via /sessions in Telegram, it gets pinned — the bot won't suggest switching away from it. The pin is cleared after the next Claude run, so the auto-detect resumes naturally.

Declining a switch (❌) also pins the current session.

Setup

1. Copy cc to your PATH:

   cp scripts/cc ~/.local/bin/cc && chmod +x ~/.local/bin/cc
   

2. Add the Stop hook to ~/.claude/settings.json (syncs terminal sessions to state.json):

   {
     "hooks": {
       "Stop": [{
         "hooks": [{
           "type": "command",
           "command": "node /path/to/tg-claude/stop-hook.mjs",
           "timeout": 10
         }]
       }]
     }
   }
   

Known limitations

• cc picks the most recent session across all projects — if you have multiple active projects, it may pick the wrong one
• Terminal sessions only sync to state.json when Claude finishes a turn (Stop hook), not mid-conversation
• If a session is deleted in Telegram, terminal gets "session not found" — just run claude to start fresh

Approval System

Dangerous operations require your approval via Telegram inline buttons:

• 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)

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/tg-claude.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 → Telegram approval buttons
stop-hook.mjs          Stop hook → Telegram completion notification
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:

• Zero runtime dependencies (except Puppeteer for optional 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