Skip to content
Agent Tree Knowledge Hub
Subscribe

Telegram Bot Architecture

Status: Production (always-on daemon)

Overview

Section titled “Overview”

The Telegram bot is the primary interface for interacting with the agent system. It runs as an always-on daemon on the local machine, using Claude Code’s --channels flag to bridge Telegram messages to Claude sessions.

Architecture

Section titled “Architecture”
Telegram (user's phone)
  │
  ▼ (Bot API)
  │
Claude Code Telegram Plugin
  │
  ▼
Claude Code Session (tmux)
  │ Reads: CLAUDE.md, SOUL.md, task logs, state files
  │ Has access to: all MCP tools, filesystem, terminal
  │
  ▼
Agent System (full local machine access)

Session Lifecycle

Section titled “Session Lifecycle”
  1. Daemon starts Claude Code with --channels flag in tmux session
  2. Sessions rotate every 4 hours to prevent context bloat
  3. On session start: reads CLAUDE.md, SOUL.md, task logs, health.json, queue/
  4. Persistent state goes to files, NOT conversation memory
  5. On session end: graceful handoff, state preserved in filesystem

Daemon Configuration

Section titled “Daemon Configuration”
  • KeepAlive: true (unconditional restart)
  • ANTHROPIC_API_KEY must NOT be set (channels require claude.ai auth)
  • Sleep fully disabled on host machine

Reply Context Patch

Section titled “Reply Context Patch”

The Telegram plugin was patched to add context when users reply to messages:

  • reply_context — original message text being replied to
  • reply_from — who sent the original message
  • reply_to_msg_id — message ID of the original

This enables conversational threading in the Telegram interface.

Outage Post-Mortem

Section titled “Outage Post-Mortem”

Root Cause

Section titled “Root Cause”

During daemon script iteration, old startup scripts exported ANTHROPIC_API_KEY, which causes claude --channels to fail. The daemon crash-looped for 56 hours with no alerting.

Fixes Applied

Section titled “Fixes Applied”
  1. Removed ANTHROPIC_API_KEY from daemon script
  2. Changed KeepAlive from conditional to unconditional
  3. Built watchdog (runs every 15 min, checks launchd + PID + tmux)
  4. Built telegram-notify.sh reusable alerting helper
  5. Auto-restart on power failure

Notify Helper

Section titled “Notify Helper”

Reusable script for any cron job to send Telegram alerts:

Terminal window
telegram-notify.sh "Your message here"

Rate-limited to prevent spam. Used by: watchdog, deadline watcher, grade alerts, cost tracker, morning briefing.