Telegram AI Supervisor Guide

This repository documents a local, file-based workflow for using Telegram as an input and reply channel for AI-assisted work across multiple repositories.

The core idea:

Telegram group
  -> local Telegram bridge
  -> repo-specific inbox JSON files
  -> lightweight supervisor / worker
  -> fresh Claude or Codex session in one target repo
  -> repo-specific outbox JSON reply
  -> Telegram bridge sends the answer

The goal is not to keep an AI session running forever. Instead, a small local supervisor handles polling, routing, batching, locks, logs, and status. Claude, Codex, or another runner starts only when there is real work.

Why This Pattern

• One Telegram bot can route messages to several independent work repositories.
• Each repository keeps its own instructions, inbox, outbox, logs, and state.
• Every AI run is isolated: one repo, one small batch, one fresh session.
• Durable context lives in files such as AGENTS.md, notes, logs, and status files.
• Telegram is just transport. The supervisor orchestrates. The target repo owns the actual work.

What Is Included

• Architecture
• Setup Guide
• Operations Guide
• Security Notes
• No-AI Transcription Repo Pattern
• Example config:
  • repos.example.json
  • target repo AGENTS.md
  • transcription repo AGENTS.md
  • launchd examples

Repository Layout Per Target Repo

Each target repo gets the same Telegram job folders:

my-repo/
  AGENTS.md
  inbox/
    telegram/
      new/
      processing/
      processed/
        YYYY-MM/
      error/
  outbox/
    telegram/
      pending/
      sent/
        YYYY-MM/
      error/
  logs/
  state/

Event Format

Inbox events are JSON files:

{
  "event_id": "telegram-2026-06-24-0001",
  "event_version": 1,
  "source": "telegram",
  "status": "new",
  "date_seen": "2026-06-24T08:00:00+02:00",
  "repo": "example-repo",
  "chat": {
    "chat_id": -1000000000000,
    "title": "Example Group",
    "type": "group"
  },
  "message": {
    "message_id": 123,
    "from": {
      "name": "Example User",
      "username": "example"
    },
    "text": "Please summarize the current task list.",
    "links": []
  },
  "media": []
}

Outbox replies are JSON files:

{
  "event_id": "telegram-2026-06-24-0001-reply",
  "target": "telegram",
  "status": "pending",
  "chat_id": -1000000000000,
  "reply_to_message_id": 123,
  "parse_mode": "HTML",
  "body": "<b>Done</b>\\nHere is the short summary."
}

Runner Model

The worker can support several runner modes:

• claude: run Claude Code in the target repo.
• codex: run Codex in the target repo.
• multi: try Claude first and fall back to Codex on quota/rate-limit errors.
• transcribe: no AI session; transcribe audio and append to a Markdown file.

Important Safety Defaults

• Do not store bot tokens, chat IDs, API tokens, or private paths in public repos.
• Keep .env local and ignored.
• Do not run multiple Telegram pollers with the same bot token. Telegram getUpdates allows only one active poller.
• Keep generated logs, inbox payloads, sent replies, and media out of public examples.
• Let the supervisor commit/push only after successful processing and only when the target repo was clean before the run.

License

MIT