claude-telegram-bot: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents working in this repository.

Commands

bun run start      # Run the bot
bun run dev        # Run with auto-reload (--watch)
bun run typecheck  # Run TypeScript type checking
bun test           # Run unit tests (colocated *.test.ts)
bun install        # Install dependencies

Managed worktrees run ./workspace-setup.sh init; after a plain git worktree add, run it yourself. Every checkout shares the .env bot token, so stop any other running instance before bun run dev (Telegram rejects concurrent polling with a 409).

Architecture

This is a Telegram bot (~3,300 lines TypeScript) that lets you control Claude Code from your phone via text, voice, photos, and documents. Built with Bun and grammY.

Message Flow

Telegram message → Handler → Auth check → Rate limit → Claude session → Streaming response → Audit log

Key Modules

• src/index.ts - Entry point, registers handlers, starts polling
• src/config.ts - Environment parsing, MCP loading, safety prompts
• src/session.ts - ClaudeSession class wrapping the Agent SDK query() API with streaming, session persistence (/tmp/claude-telegram-session.json), and defense-in-depth safety checks. Takes an optional sessionKey (default "default") used to scope saved history per forum topic.
• src/security.ts - RateLimiter (token bucket), path validation, command safety checks
• src/formatting.ts - Markdown→HTML conversion for Telegram, tool status emoji formatting
• src/utils.ts - Audit logging, voice transcription (OpenAI), typing indicators
• src/types.ts - Shared TypeScript types

Handlers (src/handlers/)

Each message type has a dedicated async handler:

• commands.ts - /start, /new, /stop, /status, /resume, /restart, /retry
• text.ts - Text messages with intent filtering
• voice.ts - Voice→text via OpenAI, then same flow as text
• audio.ts - Audio file transcription via OpenAI (mp3, m4a, ogg, wav, etc.), also handles audio sent as documents
• photo.ts - Image analysis with media group buffering (1s timeout for albums)
• document.ts - PDF extraction (pdftotext CLI), text files, archives, routes audio files to audio.ts
• video.ts - Video messages and video notes
• callback.ts - Inline keyboard button handling for ask_user MCP
• streaming.ts - Shared StreamingState and status callback factory