Dispatcher is the command layer of Cortex. Send a Telegram message from your phone, and it classifies, routes, and executes tasks through CLI-based AI agents — Claude Code, Aider, or any agent that speaks stdin/stdout.
Dispatcher bridges the gap between your phone and your AI coding agents. Messages flow down, results flow back — with intelligent routing at every step.
Dispatcher is designed to be invisible — it just works. Send a message, get a result. The intelligence is in the details.
Every incoming message is classified as task, status,
or cancel. Status keywords like "status" check running sessions.
Cancel keywords like "stop" or "cancel" terminate them. Everything else is a task.
Configure keyword-to-project mappings in YAML. Say "fix the webapp login" and
Dispatcher detects "webapp", sets the working directory to ~/projects/webapp,
and spawns the agent there. No manual context switching.
Phase 1: instant 1-turn response ("On it. Detected project X."). Phase 2: full multi-turn execution with up to 50 turns. You get immediate feedback while the real work happens in the background.
Short replies under 30 characters sent within 5 minutes are automatically linked to the most recent session. "also add tests" becomes a continuation, not a new task. Configurable threshold and time window.
Run up to 3 parallel agent sessions simultaneously. "Refactor the API" and "update the docs" can execute in parallel on different projects. Each session is tracked independently with its own process ID.
Bot responses are threaded back to your original message in Telegram. When you have 3 concurrent tasks, you always know which result belongs to which request. Clean, organized conversation history.
Typing indicators every 4 seconds so you know the agent is alive. Status updates every 3 minutes for long-running tasks. Never left wondering "is it still working?" All intervals are configurable.
One command to install as an always-on daemon: dispatcher install.
Starts on boot, auto-restarts on crash, runs in the background.
dispatcher uninstall to remove. Also supports foreground mode for debugging.
The core execution algorithm. Designed to give you instant feedback while the real work happens asynchronously.
Classify message — task, status, or cancel
Detect project — keyword matching against configured projects
Quick response — 1-turn agent call for instant acknowledgment
Send to Telegram — "On it (myapp). Spawning full session."
Spawn agent process — full CLI session with project context
Multi-turn execution — up to 50 turns of autonomous work
Progress updates — typing indicators (4s) + status (3min)
Deliver result — threaded reply with full summary to Telegram
Why two phases? Because waiting 5 minutes for "I heard you" is painful. Phase 1 confirms receipt in seconds. Phase 2 does the real work. You can keep walking, keep meeting, keep living — the result arrives when it's ready.
Everything is configured through a single YAML file. Every value can be overridden with environment variables for deployment flexibility.
Dispatcher ships with a minimal, opinionated CLI built on Click. Each command does one thing well.
config.yaml.
Run once, forget forever.
-n N for last N lines, -f for live follow mode
(like tail -f). Streams structured logs with timestamps, levels, and context.
Each module has a single responsibility. The dependency graph is acyclic. Easy to understand, easy to extend, easy to test.
The brain. Main asyncio event loop, message classification (task/status/cancel), project routing via keyword matching, and the Fire-and-Refine orchestration. Entry point for all message processing.
YAML configuration loader with environment variable overrides. Handles default values, path expansion, and validation. All configuration flows through this module.
Telegram Bot API client built on stdlib urllib only. Zero external
dependencies. Long polling, message sending, reply threading, typing indicators,
and auto-reconnect on network failures.
Agent subprocess manager. Spawns CLI processes (Claude Code, Aider, etc.), captures stdout/stderr, enforces timeouts, and manages concurrent session limits. Graceful termination on cancel.
Session tracking and smart follow-up detection. Tracks active sessions by ID, links short replies (<30 chars) within a 5-minute window to the most recent session. Manages session lifecycle: create, update, complete.
Persistent user preferences stored as markdown. Remembers project preferences, common patterns, and user-specific context across sessions. Loaded into agent prompts for personalized execution.
Click-based command-line interface. Six commands: init, start, install, uninstall, status, logs. Handles LaunchAgent plist generation, log streaming, and interactive setup wizard with validation.
From zero to "controlling Claude from your phone" in under 5 minutes. All you need is a Telegram bot token.