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:

1. Walk you through creating a Telegram bot via @BotFather
2. Help you get your user ID from @userinfobot
3. 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

1. Start: You run tg-claude "your prompt"
2. Execute: Claude Code processes your request autonomously
3. Notify: When Claude needs input, you get a Telegram notification
4. Respond: Tap a button or type a response
5. Continue: Claude resumes with your answer
6. 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

1. Make sure you messaged your bot at least once to start a conversation
2. Verify TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID are correct
3. 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