ClaudeText

Bridge between Claude Code permission prompts and Telegram. When Claude Code needs permission to run a tool (Bash, Write, Edit, etc.), ClaudeText sends a notification to Telegram with Approve/Deny buttons instead of requiring terminal interaction.

Features

• Remote approval — Approve or deny Claude Code tool calls from your phone via Telegram
• All tools — Hooks Bash, Write, Edit, and any future permission-requiring tools
• Text replies — Reply with custom text that gets passed back to Claude Code
• Fallback to terminal — If you don't respond on Telegram within the timeout, the prompt falls through to the terminal
• Menu bar app — Native macOS status bar icon with enable/disable toggle and timeout settings
• Auto-deny on hard timeout — Configurable hard timeout auto-denies if neither Telegram nor terminal responds

Setup

1. Create a Telegram bot

Message @BotFather on Telegram, run /newbot, and copy the token.

2. Install and configure

npm install
npm run build
claudetext setup <YOUR_BOT_TOKEN>

3. Start the daemon

claudetext start

Or run in the background:

nohup claudetext start >> ~/.claudetext/daemon.log 2>&1 &

4. Connect Telegram

Send /start to your bot on Telegram to register your chat ID.

5. Add the Claude Code hook

Run claudetext hook-config to see the configuration, then add it to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/claudetext/hook.sh",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

Architecture

Claude Code ──PreToolUse hook──▶ hook.sh ──HTTP POST──▶ daemon ──▶ Telegram bot
                                                          │
                                                     menu bar app

• Daemon (src/daemon.ts): Express server on 127.0.0.1:19280 + Telegraf bot (long polling)
• Hook script (hook.sh): Invoked by Claude Code, curls the daemon, returns the decision
• Menu bar (src/menubar/ClaudeTextMenu.swift): Native macOS NSStatusItem for enable/disable and settings
• Config: ~/.claudetext/config.json

CLI Commands

Command	Description
claudetext setup <TOKEN>	Configure Telegram bot token
claudetext start	Start the daemon
claudetext status	Check if daemon is running
claudetext hook-config	Print Claude Code hook configuration
claudetext help	Show help

Configuration

Stored in ~/.claudetext/config.json:

Field	Default	Description
enabled	true	When false, all hooks fall through to terminal
fallback_timeout_seconds	30	Seconds before falling through to terminal
timeout_seconds	300	Hard timeout before auto-deny
port	19280	Daemon HTTP port

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/config	GET	Current config (token redacted)
/config	PUT	Update enabled or fallback_timeout_seconds
/hook	POST	Permission request (blocks until response)
/shutdown	POST	Graceful shutdown

License

This project is licensed for non-commercial use only. See LICENSE for details.