Skip to content

fleet-telegram — Telegram Fleet Command Center

Status: SPEC ONLY — queued as Track B backlog item 12 (2026-07-08). Not started. Origin: Andrew request, inspired by https://www.reddit.com/r/AI_Agents/comments/1q63wkc/telegram_is_one_of_the_best_interfaces_for/ Owner track: B (tools/infra). Build offloadable to Codex (gpt-5.5 high) per fleet-dispatch precedent; agy for review seats.

One-liner

C# MCP-integrated agent system giving Andrew a Telegram command center over every AI session on every house machine — monitor, command (text + voice), receive screenshots/recordings, browse files and the board — secure, extensible to new AIs and harnesses, with caveman compression and the usage governor applied to all traffic.

Requirements (from Andrew, verbatim intent)

  1. Per-AI, per-machine Telegram presence: Claude Code, Codex, agy/Gemini, eventually Grok/SuperGrok, plus Odysseus, OpenClaw, Cursor. Keep up with what each session is doing, per harness per AI.
  2. Two-way: Andrew can send commands to any agent/session remotely, so work continues while he is away from the computers.
  3. C#. Secure.
  4. Send screenshots AND screen recordings on demand or proactively.
  5. Browse codebase/file system and the WW board from Telegram.
  6. Large project; must extend cleanly to new AI models and harnesses.
  7. Voice commands (Wispr AI dictation on phone → text, and/or Telegram voice notes → local transcription).
  8. Inbound commands run through caveman compression + usage-governor gating before execution.
  9. Can push design/frontend screenshots and videos (WW Angular dev server captures).
  10. Build work itself may be offloaded to Codex/agy per governor tier.

Architecture sketch (for Track B + council to refine)

Topology decision (COUNCIL THIS FIRST)

  • Option A — bot-per-AI-per-machine (literal reading): BotFather sprawl (~5 AIs × 4 PCs = 20 bots), but hard isolation and per-bot mute.
  • Option B (recommended) — one gateway bot per machine + one Telegram forum supergroup ("Fleet HQ") with a topic per agent/session. Topics give per-AI channels Andrew can mute/follow individually; far fewer tokens/bots to manage; message threading maps to sessions naturally.
  • Hybrid: one bot per machine, topic per (AI × session).

Components (.NET 10, Core/Cli split, house standards)

  • FleetTelegram.Core — domain: session registry, adapter interfaces, command pipeline, media pipeline, security.
  • FleetTelegram.Gateway — per-machine Windows service/scheduled task: Telegram long-polling (no inbound ports needed — works before SSH mesh item 2 lands), runs adapters, executes commands locally.
  • FleetTelegram.Mcp — stdio MCP server registered user-scope (claude mcp add fleet-telegram) so any Claude session can proactively push: "notify Andrew", "send this screenshot", "post board update". Complements Pavlok (Telegram = first-line notify; Pavlok skill stays escalation for sleep/critical).

Adapter seams (extensibility requirement)

  • ISessionSource — tails/summarizes sessions per harness:
  • Claude Code: transcript JSONL under ~/.claude/projects/** + claude-mem observation feed (already caveman-compressed, 86% savings — ideal Telegram digest source; don't re-summarize with paid tokens).
  • Codex: codex exec logs / session dirs.
  • agy/Gemini: agy output logs.
  • Grok/Odysseus/OpenClaw/Cursor: stub adapters, added later behind same interface.
  • IAgentCommander — sends work to a harness: claude CLI headless, codex exec, agy CLI (< NUL stdin-close gotcha), pwsh.
  • IMachineTransport — local exec now; fleet-dispatch OneDrive queue (Track B item 11, HMAC-signed) as cross-machine substrate; SSH mesh once item 2 unblocks. DO NOT rebuild dispatch — reuse fleet-dispatch.

Command pipeline (requirement 8)

Telegram update → sender-ID allowlist check → voice? transcribe locally (reuse audio-loop-mcp Whisper.net code — already shipped, andrewjonesdev-tools/audio-loop-mcp) → caveman-compress prompt → usage-governor gate (read ~/.claude/usage-governor/state.json; YELLOW+ = downgrade target model / route to Codex-agy; RED = Claude denied unless critical; fail-open on missing state like fleet-dispatch) → dispatch via IAgentCommander/IMachineTransport → replies caveman-compressed back to Telegram.

Media pipeline (requirements 4, 9)

  • Screenshots: Windows.Graphics.Capture / GDI fallback.
  • Recordings: ffmpeg or Windows.Graphics.Capture encoder; respect Telegram bot 50MB upload cap (chunk or downscale).
  • Frontend/design captures: Playwright (WW already bundles it) against dev server — screenshots + trace videos of flows.
  • Scrub policy: never capture vault windows/.kdbx dialogs; secret-grep media captions; captures are user-initiated or session-initiated, never scheduled blanket recording.

File & board browsing (requirement 5)

  • Read-only commands: /ls <path>, /cat <path> (size-capped, syntax-highlighted via HTML parse mode), path allowlist rooted at C:\Users\fives\source\repos + OneDrive PC-Bootstrap. Writes go through an agent command, never direct — governor + review gates stay in the loop.
  • Board: render docs/BOARD.md + live artifact URL (see board-live-status-updates memory) as pinned Fleet HQ message, refreshed on flips.

Security (requirement 3 — non-negotiables)

  • Telegram user-ID allowlist = Andrew only; drop all else silently, log attempts.
  • Bot tokens in per-machine secret store (DPAPI user-scope or ~/.claude key file, user-only ACL) — NEVER OneDrive, never repo (archive-not-delete scrub rules apply).
  • Cross-machine commands ride fleet-dispatch HMAC signing; no new crypto.
  • Long-polling only (no webhook = no inbound firewall holes on house PCs).
  • Command rate limit + per-command audit log; critical flag required to bypass governor RED.
  • Dangerous commands (delete, push, reboot-adjacent) → explicit Telegram confirm button; NEVER reboot machines (standing memory).

Gates (house standard)

xunit + Bogus mocked units (mock Telegram client, IClock, adapters), ≥80% Core coverage, Stryker mutation, /council-code-review per commit, two-track docs (architecture.md + plain.md) + Mermaid (pipeline sequence + adapter surfaces), board entry, private repo andrewjonesdev-tools/fleet-telegram, SHA-pinned Actions on home-ci.

Dependencies / sequencing

  • Rides on: fleet-dispatch (item 11, Codex building now) for cross-machine exec; audio-loop-mcp (shipped) for Whisper transcription; home-bootstrap kit (item 10 pattern) to install gateway on each PC; SSH mesh (item 2) optional accelerator, not blocker (long-polling works day one).
  • Phase 1: main PC only — gateway + Claude Code adapter + text commands + screenshots + governor/caveman pipeline. Immediate value.
  • Phase 2: Codex + agy adapters, voice notes, recordings, board/file browsing.
  • Phase 3: all house PCs via bootstrap, fleet-dispatch transport, remaining harness adapters (Grok Thu, Odysseus, OpenClaw, Cursor).

Open questions for Track B / council

  1. Topology A vs B (bots vs forum topics) — recommend B.
  2. Digest cadence: push every observation vs batched per-session digest every N minutes (governor-tier-scaled)?
  3. Recording tech: ffmpeg dependency vs pure Windows.Graphics.Capture?
  4. Does FleetTelegram.Gateway subsume claude-session-watchdog's paging role eventually (Telegram before Pavlok), or stay separate? (watchdog memory says push awaits approval)