claude-tg-approver-and-chat

Approve Claude Code permissions and chat with Claude — all from Telegram on your phone.

Why?

Claude Code asks for permission before running commands, editing files, or fetching URLs. Normally you have to be at your terminal to approve. This tool forwards those requests to Telegram so you can Allow / Deny from your phone while Claude works autonomously.

Plus: send messages from Telegram directly into a running Claude session (via tmux).

Quick start

npm install -g claude-tg-approver-and-chat
claude-tg-approver-and-chat setup     # Creates Telegram bot, gets chat ID, installs hooks
claude-tg-approver-and-chat start     # Start approval server
# Now use Claude Code normally — approvals come to Telegram

Requirements: Node.js >= 18, Python 3, curl

Want to also chat with Claude from Telegram?

If you want to send messages from Telegram directly into a running Claude session, set up tmux:

claude-tg-approver-and-chat setup-tmux   # Checks tmux, configures session target

# Then use it:
tmux new -s claude    # Start a tmux session
claude                # Run Claude Code inside it
# Detach: Ctrl+B, then D

# In another terminal:
claude-tg-approver-and-chat start

# Now type in Telegram — messages go straight to Claude!
# Re-attach anytime: tmux attach -t claude

Requirements: tmux (brew install tmux on macOS)

How it works

Claude Code hook (PermissionRequest)
        |
        v
hooks/telegram-approve.py  (Python, stdlib only)
        |
        v
POST /approve  -->  Telegram bot message
                    [Allow] [Deny]
                    [Allow All] [Ask in Terminal]
        |
        v
Hook returns allow/deny to Claude Code

1. Claude Code triggers a PermissionRequest hook
2. telegram-approve.py sends it to the local approval server
3. Server forwards to Telegram with inline buttons
4. You tap Allow or Deny on your phone
5. Decision flows back to Claude Code

Additionally:

• telegram-notify.py forwards passive notifications (errors, progress)
• telegram-stop.py sends a completion message with Claude's answer when a session ends

Features

Permission approval from Telegram

Every dangerous operation (file writes, bash commands, web fetches) gets sent to Telegram with context — tool name, command preview, project name. Tap to approve or deny.

Smart auto-approval

Safe, read-only operations are auto-approved without bothering you:

• Tools: Read, Glob, Grep, LS, Diff
• Bash: ls, cat, pwd, git status, git log, git diff, npm test, npm run build, head, tail, grep, find, docker ps, and more

Dangerous patterns always require approval:

• rm, mv, sudo, chmod, wget
• curl -X, pip install, npm install, brew install
• Any bash with pipes, redirects, or command chaining

Allow All (per session)

Tap Allow All to auto-approve everything for the current Claude session. A Revoke button appears so you can turn it off anytime. Resets on server restart.

Telegram chat (two-way)

Send messages from Telegram directly into Claude Code via tmux injection:

# Start Claude inside tmux
tmux new -s claude
claude   # run Claude Code here

# Configure target (in another terminal)
export TMUX_TARGET="claude:0.0"
claude-tg-approver-and-chat start

Then in Telegram, just type a message or use /ask <your question>. The server injects it into the tmux pane. Safety check: won't inject into bare shell prompts.

Session completion notifications

When Claude finishes a task, you get a Telegram message with:

• Claude's last answer (truncated)
• Suggested next step
• "What would you like to tackle next?"

CLI commands

| Command | Description | |---------|-------------| | claude-tg-approver-and-chat setup | Interactive setup wizard | | claude-tg-approver-and-chat setup-tmux | Setup tmux for Telegram ↔ Claude chat | | claude-tg-approver-and-chat start | Start approval server (foreground) | | claude-tg-approver-and-chat start-bg | Start approval server (background) | | claude-tg-approver-and-chat stop | Stop the approval server | | claude-tg-approver-and-chat status | Check if server is running | | claude-tg-approver-and-chat inbox | View queued Telegram messages | | claude-tg-approver-and-chat install-hooks | Install/update Claude Code hooks |

Background mode (works when installed globally):

claude-tg-approver-and-chat start-bg    # Start in background
claude-tg-approver-and-chat stop        # Stop background server

Telegram bot commands

| Command | Description | |---------|-------------| | /help | Show usage info | | /status | Bridge status and counters | | /inbox | View queued messages | | /ask <message> | Send message to Claude (same as plain text) |

Configuration

Config is loaded from (in priority order):

1. Environment variables
2. ~/.claude-tg-approver-and-chat.json
3. Defaults

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | TELEGRAM_BOT_TOKEN | required | Bot token from @BotFather | | TELEGRAM_CHAT_ID | required | Your Telegram user/chat ID | | PORT | 9876 | Server port | | APPROVE_TIMEOUT_MS | 300000 | Timeout before falling back to terminal (5 min) | | AUTO_APPROVE_READONLY | true | Auto-approve safe read-only operations | | TELEGRAM_TEXT_INPUT_ENABLED | true | Enable Telegram-to-Claude chat | | TMUX_TARGET | — | tmux pane for text injection (e.g. claude:0.0) | | TELEGRAM_INBOUND_PREFIX | Telegram: | Prefix for injected messages |

Hook-side (set in shell environment):

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_APPROVE_URL | http://localhost:9876 | Server URL for hooks | | CLAUDE_APPROVE_TIMEOUT | 300 | Hook timeout in seconds |

API endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /approve | Permission request handoff (hook → Telegram → decision) | | POST | /notify | Forward notification to Telegram | | GET | /health | Server health + pending request count | | GET | /stats | Aggregate counters | | GET | /log | Recent auto-approved operations | | GET | /inbox | Queued Telegram inbound messages | | POST | /inbox/pull | Pop one queued message |

Security

• Localhost only — server binds to 127.0.0.1, not exposed to the network
• Chat ID validation — Telegram button presses and messages are verified against your configured chat ID
• Fail-open design — if the server is down or times out, Claude Code falls back to the normal in-terminal permission prompt (your workflow is never blocked)
• No secrets in code — bot token and chat ID are loaded from env vars or ~/.claude-tg-approver-and-chat.json

Changelog

0.1.6

• Add start-bg CLI command - run the server in background from anywhere (works with global install)
• Update README with background mode docs

0.1.5

• Add update check on start
• Add setup-tmux command

License

MIT