Skip to main content
Octo is built on LangGraph — a framework for building stateful, multi-agent applications.

​
System Diagram

                        ┌──────────────────────┐
Console (Rich) ←──────→│                      │←───→ Project Workers (claude -p)
                        │    Supervisor        │←───→ Standard Agents (AGENT.md)
Telegram Bot   ←──────→│  (create_supervisor) │←───→ Deep Research Agents
                        │                      │
Heartbeat      ────────→│    asyncio.Lock      │←───→ MCP Tools (.mcp.json)
Cron Scheduler ────────→│                      │←───→ Built-in Tools
                        └──────────────────────┘
All transports share the same conversation thread and graph lock.

​
Key Components

​
Supervisor

The central agent built with create_supervisor from langgraph-supervisor. It:
  • Receives all user messages
  • Routes to the appropriate worker agent
  • Manages task plans, memory, and state
  • Has access to supervisor-only tools (todos, memory, file sending, scheduling)

​
Workers

Three types of worker agents:
Created for each registered project. They wrap claude -p (Claude Code CLI) for full codebase access. The supervisor delegates project-specific coding tasks to these workers.
Built with create_agent from LangGraph. Each gets:
  • Built-in tools (Read, Grep, Glob, Edit, Bash) filtered by tools: in AGENT.md
  • MCP tools from all connected servers
  • ToolErrorMiddleware for graceful error handling
  • SummarizationMiddleware for context compression
Built with create_deep_agent from the deepagents library. They get:
  • Persistent filesystem workspace at .octo/workspace/<date>/
  • TodoList middleware for planning
  • Summarization middleware
  • Sub-agent spawning capability

​
Transports

TransportDescription
Rich ConsolePrimary CLI interface with styled output, spinner, tool panels
Telegram BotBidirectional bot with voice, files, and rich formatting
HeartbeatPeriodic timer that invokes the graph on a schedule
Cron SchedulerJob-based scheduler with at/every/cron expressions
All transports share an asyncio.Lock to prevent concurrent graph invocations.

​
State Persistence

  • Conversation — SQLite via langgraph-checkpoint-sqlite (.octo/octo.db)
  • Sessions — .octo/sessions.json (metadata for resume)
  • Task plans — .octo/plans/plan_<datetime>.json
  • Memory — .octo/memory/ (daily) + MEMORY.md (long-term)
  • Cron jobs — .octo/cron.json

​
File Map

octo/
├── cli.py           # Click CLI + async chat loop (entry point)
├── graph.py         # Supervisor graph assembly + tools
├── models.py        # Model factory (5 providers)
├── config.py        # .env loading, constants
├── context.py       # System prompt composition
├── middleware.py     # Tool errors, truncation, summarization
├── heartbeat.py     # Heartbeat + cron scheduler
├── telegram.py      # Telegram bot transport
├── sessions.py      # Session registry
├── callbacks.py     # LangChain callback handler (UI)
├── ui.py            # Rich console (banners, input, help)
├── voice.py         # ElevenLabs TTS + Whisper STT
├── abort.py         # ESC-to-abort terminal listener
├── retry.py         # Auto-retry with exponential backoff
├── tools/           # Built-in tools (filesystem, shell, claude_code)
├── loaders/         # Agent, MCP, and skill loaders
├── wizard/          # Setup wizard + health check
└── oauth/           # Browser-based OAuth for MCP

​
Request Flow

1

User sends message

Via Rich console, Telegram, or proactive trigger (heartbeat/cron).
2

Graph lock acquired

The asyncio.Lock ensures only one invocation at a time.
3

Supervisor receives message

System prompt includes: persona, STATE.md, memory, agent descriptions.
4

Supervisor routes to worker

Based on agent descriptions and conversation context. Or handles directly.
5

Worker executes

Uses tools (MCP + built-in), generates response. Middleware handles errors and context.
6

Response returned

Rendered via Rich console and/or sent to Telegram. State checkpointed to SQLite.