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

$3

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

$3

``bash
npm install -g tg-claude
`

$3

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

`bash
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:

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

$3

`bash
npx tg-claude
`

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

$3

To reconfigure your Telegram credentials anytime:

`bash
tg-claude --setup
`

Usage

`bash
tg-claude [options] "Your prompt"
`

$3

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

$3

`bash


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.

$3

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

$3

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

Troubleshooting

$3

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

$3

Install Claude Code CLI:

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

$3

Fix npm permissions (recommended one-time fix):

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

Then install normally:

`bash
npm install -g tg-claude
`

Or use a custom npm prefix:

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

$3

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

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

License

MIT