tg-claude

Claude Telegram Bridge

Control Claude Code from your phone via Telegram. Get notifications when Claude needs input, respond with buttons or text, and monitor progress from anywhere.

Features

• Mobile Notifications: Get Telegram alerts when Claude needs a decision
• Interactive Buttons: Tap to select options without typing
• Multi-Select Support: Handle questions with multiple choices
• Dual Interface: Use both terminal and Telegram simultaneously
• Session Continuity: Continue conversations across turns
• Autonomous Mode: Runs with --dangerously-skip-permissions for unattended operation

Quick Start

Prerequisites

• Node.js 20+
• Claude Code CLI installed and authenticated
• A Telegram account

Installation

npm install -g tg-claude

Setup (Interactive Wizard)

Just run the command — the setup wizard guides you through everything:

tg-claude

The wizard will:

• Walk you through creating a Telegram bot via @BotFather
• Help you get your user ID from @userinfobot
• Save credentials to .env automatically

That's it! Now run with a prompt:

tg-claude "Fix the bug in app.js"

Alternative: npx (no install)

npx tg-claude

Note: With npx, the .env file is created in your current directory. Run from your project folder.

Re-run Setup

To reconfigure your Telegram credentials anytime:

tg-claude --setup

Usage

tg-claude [options] "Your prompt"

Options

Flag	Description
--setup	Run setup wizard to configure Telegram credentials
--help, -h	Show help message
--version, -v	Show version number
--verbose	Show additional logging
--debug	Enable debug output
--quiet	Suppress bridge logs, show only Claude output

Examples

# Basic usage
tg-claude "Explain this codebase"

# Verbose output
tg-claude --verbose "Refactor the auth module"

# Quiet mode (only Claude's output)
tg-claude --quiet "Write tests for user.ts"

# Using npx
npx tg-claude "Create a README"

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather
TELEGRAM_USER_ID	Yes	Your numeric Telegram user ID

Without Telegram credentials, the bridge runs in terminal-only mode.

How It Works

• Start: You run tg-claude "your prompt"
• Execute: Claude Code processes your request autonomously
• Notify: When Claude needs input, you get a Telegram notification
• Respond: Tap a button or type a response
• Continue: Claude resumes with your answer
• Complete: Get a completion notification when done

The bridge uses Claude's --output-format stream-json for structured events and --resume for session continuity.

Dual Interface

Both terminal and Telegram can respond to prompts:

• Terminal: Type option numbers or freeform text
• Telegram: Tap buttons or send messages
• Responses from either interface are echoed to the other

Security

Only the configured TELEGRAM_USER_ID can interact with your bot. All other users are silently ignored.

Troubleshooting

"TELEGRAM_USER_ID must be a number"

Your user ID should be a numeric value like 123456789, not a username. Get it from @userinfobot.

"Claude CLI not found"

Install Claude Code CLI:

npm install -g @anthropic-ai/claude-code
claude auth login

"Permission denied" or EACCES errors

Fix npm permissions (recommended one-time fix):

sudo chown -R $(whoami) ~/.npm

Then install normally:

npm install -g tg-claude

Or use a custom npm prefix:

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g tg-claude

Avoid using sudo with npx — it creates files with root ownership which causes issues.

Bot not responding

• Make sure you messaged your bot at least once to start a conversation
• Verify TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID are correct
• Check that Claude Code CLI is authenticated (claude auth status)

Development

git clone https://github.com/memehalis/tg-claude
cd tg-claude
npm install
npm run dev "test prompt"

License

MIT