telegram-claude-codex: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

bun install          # install dependencies
bun run src/index.ts # start bot
bun --watch run src/index.ts  # dev mode (auto-reload on changes)
bun test             # run tests
bun run typecheck    # tsc --noEmit
bun run lint         # check lint/format (ultracite/biome)
bun run fix          # auto-fix lint/format issues
bun run backup       # snapshot .data/bot.db into .data/backups/

Architecture

Telegram bot that bridges coding-agent CLIs (Claude Code + OpenAI Codex) with Telegram. Runs the active provider (SDK in-process for Claude, spawned CLI for Codex), normalizes its output to a provider-agnostic event model, and renders it into the chat. The active provider is swappable at runtime via /provider.

Two things shape the whole layout: every conversation is a route — user + chat + forum topic — so topics run in parallel with their own session, project, queue and compose draft; and output is quiet by default — a typing indicator, then one message with the answer, unless /verbose is on. All durable state is SQLite (.data/bot.db).

Module Overview (src/)

• index.ts — Entry point. Opens/migrates .data/bot.db and runs the one-time legacy JSON import before any update is served; boots AppConfig + BotService through the Effect runtime (env validation fails fast); warns (non-blocking) on codex login status and on the BotFather flags getMe exposes read-only (privacy mode, join-groups); registers the command list in four scopes; starts polling. Shutdown: stop all runs → runtime.dispose() (stops the bot) → closeDb().
• bot.ts — createBot(token, allowedUserId, projectsDir): grammy instance, access-control middleware, reply-keyboard-button → command rewriting, then the register*() groups from handlers/. Registration order matters (topic-title bookkeeping → compose interceptor → commands → text → uploads) and is documented in place.
• state.ts — Thin wrapper over the settings table: loadPersistedState() plus setters for active project/provider and per-provider model/effort. BotState is derived from loadBotState, so the two can't drift.
• telegram.ts — streamToTelegram({ctx, events, policy, route, …}): typing ticker (the only progress signal under the quiet policy), 1.5s deferred-edit flush, dispatchEvent per event, finalizeStream. Re-exports splitText / sendRichMarkdown / StreamResult.
• config.ts / runtime.ts / logger.ts / telemetry.ts / observability.ts — Effect layers: env config (AppConfig), the ManagedRuntime all Promise-land code bridges through, console logging, optional OTLP forwarding, and the one-wide-event-per-run ledger.
• transcribe.ts — Voice message transcription via Groq Whisper (whisper-large-v3-turbo).