telegram

agents-comm-bus Telegram Plugin

Bidirectional Telegram messaging for Claude Code and Codex through a shared per-user agents-comm-bus daemon. Agent host plugins stay thin: they expose MCP tools and hooks, while Telegram polling, account ownership, conversations, queries, transcripts, and audit logs live under ~/.agents-comm-bus/.

Release Status

universal-overhaul is not marketplace-release ready until the production install gate added in 0a20bf3 passes as a hard test. AGE-23 owns the packaging work that makes staged marketplace artifacts self-contained. Until that lands, source/dev mode can work, but fresh marketplace installs are expected to fail the production marketplace install (release gate) tests.

Use docs/architecture/release-readiness.md as the checklist before publishing this branch as main or updating marketplace repositories.

What It Provides

• Send Telegram messages and attachments from Claude Code or Codex.
• Receive Telegram messages into the active agent session.
• Route permission and question prompts through Telegram inline buttons.
• Share one per-user daemon across multiple agents and Telegram bot accounts.
• Keep routing keyed by concrete bot IDs, not human labels.
• Persist state in SQLite plus JSONL transcript/audit files under ~/.agents-comm-bus/.

Requirements

• Node.js 22 or newer. The daemon uses node:sqlite.
• A Telegram bot token from @BotFather.
• Your Telegram numeric user ID, if you want allowlist restrictions.
• One Telegram bot per registered agent/project account. Telegram rejects multiple getUpdates consumers for the same bot token.

Marketplace Installation

The intended end-user path is marketplace installation, then explicit account registration. The plugin should not require users to clone this repository or run source install scripts.

Claude Code

1. Add the marketplace.

   /plugin marketplace add https://github.com/remingtonspaz/claude-code-telegram
   

2. Install the Telegram plugin.

   /plugin install telegram-integration:telegram
   

3. Restart Claude Code so the MCP server and hooks are loaded.

4. Register the Telegram bot account from a terminal. The agents-comm command is installed by the daemon's central install at ~/.agents-comm-bus/bin (it appears after the first session/hook runs). Add that directory to PATH once so the command resolves from any shell — no npm install/npm link needed:

   [Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.agents-comm-bus\bin", "User")
   

   Then register the account (open a new shell so PATH is refreshed):

   agents-comm account-add `
     --project "<absolute project path>" `
     --agent claude `
     --account-label main `
     --bot-token "<telegram bot token>"
   

5. Message the bot once from Telegram so Telegram allows the bot to reply.

6. In Claude Code, check /mcp and confirm the telegram MCP server is connected.

Codex

Install the Codex Telegram plugin through the Codex plugin flow for the staged artifact, then register the account with --agent codex:

agents-comm account-add `
  --project "<absolute project path>" `
  --agent codex `
  --account-label main `
  --bot-token "<telegram bot token>"

Codex session startup currently needs the project-local hook configuration that points at the staged Codex MCP shim. Keep the global Codex MCP config path-only; session URL, thread ID, and daemon session ID are discovered at runtime.

Account Management

Account registration is explicit. The daemon stores the bot token in a daemon-owned file and stores only a credentials_ref in SQLite. Legacy env: registrations are migrated once to daemon-owned file refs when the token is still available from the old env var or project-local Telegram config. New registrations should use --bot-token.

Common commands:

# List registrations.
agents-comm account-list

# Register a bot.
agents-comm account-add `
  --project "<absolute project path>" `
  --agent claude `
  --account-label main `
  --bot-token "<telegram bot token>"

# Rotate the token for the same bot, or intentionally replace the bot.
agents-comm account-update-token `
  --bot-id "<current bot id>" `
  --bot-token "<new telegram bot token>"

# Relabel a registered account.
agents-comm account-relabel `
  --bot-id "<bot id>" `
  --new-account-label "<new label>"

# Remove a registered account.
agents-comm account-remove `
  --bot-id "<bot id>"

Labels are display aliases. Side-effecting commands should prefer --bot-id; label targeting is accepted only when it resolves to exactly one account.

Allowlist

By default, Telegram authorization depends on the adapter configuration and daemon records. Manage allowlist rows with: