tgbot 0.0.2

Telegram to Codex CLI bridge.

tgbot

Telegram ↔ Codex CLI bridge written in Dart.

Activate the command:

dart pub global activate tgbot

Start the bot bridge (uses tgbot.yaml by default):

tgbot

Start with a custom config path:

tgbot /absolute/path/to/tgbot.yaml

Command format:

tgbot [config-path]

Features

• Accept Telegram messages only from each bot's allowed user ID.
• Load bot settings from YAML.
• Forward chat prompts to Codex CLI with working directory scoped per bot.
• Send Codex text output back to Telegram.
• Support Telegram bot sending files and images to the authorized user when requested through normal chat.
• Support /start command for quick usage help.
• Support /new command to create a fresh session context.

YAML Config

Create tgbot.yaml (or pass a custom path as the first CLI arg).

Example:

defaults:
  codex_cmd: codex
  codex_args: []
  codex_allow_dirs: []
  additional_system_prompt: ""
  project_path: .
  poll_timeout_sec: 30
  codex_timeout_sec: 300

bots:
  - name: primary
    telegram_bot_token: your_telegram_bot_token
    allowed_user_id: 123456789
    project_path: /absolute/path/to/project
    additional_system_prompt: |
      Keep responses concise and production-focused.

Top-level fields:

• defaults (optional): shared defaults for all bots.
• bots (required): list of bot entries.

Bot keys:

• name (optional): display name used in logs.
• telegram_bot_token (required): bot token.
• allowed_user_id (required): Telegram user ID that can use this bot.
• codex_cmd (optional, default codex): Codex CLI executable.
• codex_args (optional): extra args before built-in exec; string or list.
• codex_allow_dirs (optional): appended as --add-dir; string (comma-separated) or list; supports ~ expansion.
• telegram_commands (optional): additional commands registered via Telegram setMyCommands; list of {command, description}.
  • When a user sends /command some text, some text is passed to Codex as command args.
  • If description contains {args}, args are injected there.
  • Otherwise args are appended after the description.
• additional_system_prompt (optional): extra system instructions appended for this bot before each user request.
• project_path (optional, default current working directory).
• poll_timeout_sec (optional, default 30).
• codex_timeout_sec (optional, default 120).

Use tgbot.yaml.example as a template. System commands /start and /new are always registered. If telegram_commands is provided, those entries are appended (deduplicated by command).

Supported Input

• /start: Show usage help.
• /new: Start a new session (clear conversation/session context for the chat).
• Any other text message: treat as a prompt to Codex in the current session.

Session Behavior

• Keep a session ID (or memory context) per authorized chat.
• /new creates a new session ID and discards previous context for that chat.
• Return a confirmation message like: Started a new session.

Architecture (Suggested)

• bin/tgbot.dart: app bootstrap.
• lib/config.dart: YAML loading + validation.
• lib/telegram/telegram_client.dart: Telegram Bot API calls.
• lib/telegram/update_router.dart: authorization + routing.
• lib/codex/codex_runner.dart: run Codex CLI process.
• lib/session/session_store.dart: per-chat session lifecycle (/new).

Main Runtime Flow

1. Load and validate YAML config.
2. Start one long-polling loop per bot.
3. Ignore unauthorized users.
4. Parse incoming text.
5. Route:
   • /start → show usage help.
   • /new → reset session state.
   • otherwise → run Codex with the current chat session.
6. Send result back with:
   • sendMessage for text responses.
   • sendPhoto for image artifacts.
   • sendDocument for other file artifacts.

File/Image Delivery

• The user does not need separate /sendfile or /sendimage bot commands.
• File/image delivery should be triggered from normal chat interactions and Codex output metadata.
• Bridge prompt contract: Codex is instructed to emit a marker line when artifact delivery is needed:
  • TG_ARTIFACT: {"kind":"image|file","path":"...","caption":"..."}
• Restrict file access to within project_path.
• Validate existence and size before upload.
• Use multipart uploads:
  • sendPhoto for images
  • sendDocument for generic files

Error Handling

• Handle Codex timeout and process errors.
• Handle Telegram rate limits (429) with retry delay.
• Chunk long text messages to Telegram limits.
• Never log bot token.