bridgebot

Turn Claude Code, Codex, or Gemini CLI into Telegram chat bots. Each bot keeps its own real workspace and session — code, run commands, handle files, and pick up where you left off.

Requirements

• Node.js 22.5+ (built-in node:sqlite used; Node 24 recommended)
• One or more of: claude CLI, codex CLI, gemini CLI installed and on $PATH
• A Telegram bot token from @BotFather

Setup

# 1. Clone and install
git clone <repo>
cd bridgebot
npm install
npm run build

# 2. Scaffold config files
node dist/index.js init
#  → creates bridgebot.config.yaml and .env in the current directory

# 3. Edit .env — add your tokens
TELEGRAM_BOT_TOKEN=123456789:ABCdef...
ANTHROPIC_API_KEY=sk-ant-...   # for claude backend
OPENAI_API_KEY=sk-...          # for codex backend
GEMINI_API_KEY=AIza...         # for gemini backend

# 4. Edit bridgebot.config.yaml
#    - Add your Telegram user ID to access.owners
#    - Add your chat IDs to each bot's allowed_chats
#    - Set workspace paths

# 5. Start
node dist/index.js start

Find your Telegram user ID

Message @userinfobot — it replies with your ID.

Make it a global command

npm link        # or: npm install -g .
bridgebot start

Management commands

| Command | Description | |---|---| | bridgebot start | Start the bot (foreground). Ctrl+C stops cleanly. | | bridgebot start -c path/to/config.yaml | Use a specific config file. | | bridgebot status | Show configured bots and workspaces. | | bridgebot status --bot claude | Show one bot. | | bridgebot logs | Print last 50 lines of the log file. | | bridgebot logs -f | Follow logs live (like tail -f). | | bridgebot logs -n 200 | Print last 200 lines. | | bridgebot watch --bot claude | Show Claude session list for the workspace. | | bridgebot init | Scaffold .env and bridgebot.config.yaml. |

Log files are written to ./logs/ (or $BRIDGEBOT_LOG_DIR) and rotated daily, kept 14 days.

Run with PM2 (recommended for production)

npm install -g pm2
pm2 start "node dist/index.js start" --name bridgebot
pm2 logs bridgebot
pm2 restart bridgebot
pm2 save && pm2 startup

Chat commands (from Telegram)

These work in any allowed chat or topic.

| Command | Who | Description | |---|---|---| | /help | everyone | Show command list | | /status | everyone | Session info, queue depth, active loops | | /session | everyone | Current session ID, turn count, workspace | | /queue | everyone | List queued requests | | /cancel | everyone | Clear the pending queue (running request finishes) | | /clear | everyone | Forget session — next message starts fresh | | /loop <seconds> <prompt> | admins+ | Repeat a prompt on a schedule | | /loops | everyone | List active loops for this chat | | /stoploop [id] | admins+ | Stop a loop by short ID, or all loops | | /bash <command> | owners only | Run a shell command in the bot workspace | | /streaming on\|off | everyone | Toggle live streaming edits | | /mention on\|off | admins+ | Require @mention in groups |

Config reference

access:
  owners: [123456789]    # full access including /bash
  admins: [987654321]    # /loop, /stoploop, /mention

settings:                # global defaults, overridable per-bot
  streaming: true
  mention_required: false
  max_response_length: 3800
  queue_timeout: 300
  loop_max_iterations: 20
  bash_timeout: 60
  edit_interval_ms: 1200

bots:
  - name: claude
    backend: claude        # claude | codex | gemini
    workspace: ./workspaces/claude

    allowed_chats:
      - type: private
        user_ids: [123456789]
      - type: group
        chat_id: -1001234567890          # whole group
      - type: group
        chat_id: -1009876543210
        topic_ids: [5, 12]              # specific forum topics only

    settings:              # overrides global for this bot
      streaming: true

Multi-backend setup

Run one Telegram bot token that routes to different backends by chat:

bots:
  - name: claude
    backend: claude
    workspace: ./workspaces/claude
    allowed_chats:
      - type: group
        chat_id: -100111
        topic_ids: [1]      # topic 1 → Claude

  - name: gemini
    backend: gemini
    workspace: ./workspaces/gemini
    allowed_chats:
      - type: group
        chat_id: -100111
        topic_ids: [2]      # topic 2 → Gemini

Or run two separate bridgebot start processes with different configs (and different bot tokens).

How sessions work

Each (bot, chat, topic) combination gets its own persistent session stored in bridgebot.db.

• Claude: uses --resume <session-id> to continue across restarts. Session ID is extracted from stream-json output and stored.
• Codex: uses --last to continue within the workspace directory.
• Gemini: session is workspace-scoped (Gemini CLI manages it internally).

Use /clear to drop the stored session and start fresh. The workspace files are not deleted — only the session pointer is reset.

Streaming

When streaming: true, the bot sends a placeholder message and edits it as tokens arrive. Edits are throttled to edit_interval_ms (default 1200ms) to stay within Telegram's 20 edits/second rate limit.

Disable with /streaming off (per-chat, resets on restart) or in config.

Groups and topics

In a forum/supergroup with topics, set topic_ids in allowed_chats to restrict the bot to specific topics. Leave topic_ids out to allow the whole group.

In groups with mention_required: true, the bot only responds when @mentioned. Enable per-chat with /mention on.

Environment variables

| Variable | Default | Description | |---|---|---| | TELEGRAM_BOT_TOKEN | — | Required | | BRIDGEBOT_CONFIG | ./bridgebot.config.yaml | Config file path | | BRIDGEBOT_LOG_LEVEL | info | debug / info / warn / error | | BRIDGEBOT_LOG_DIR | ./logs | Log directory | | BRIDGEBOT_DB_PATH | ./bridgebot.db | SQLite database path | | ANTHROPIC_API_KEY | — | For claude backend | | OPENAI_API_KEY | — | For codex backend | | GEMINI_API_KEY | — | For gemini backend |