octo-agent Architecture Deep Dive: Five-Layer Core Stack & Full-System Dependency Map
octo-agent’s codebase has grown to 480+ Go files, six IM bridges, and an embedded Svelte 5 workbench. This post uses an interactive panorama diagram to show how the whole system hangs together.
Design Philosophy: Strictly Unidirectional Dependencies
The single most important architectural discipline in octo-agent is strictly unidirectional dependency. The five-layer stack:
cmd/ → app/ → agent/ ← (provider/, tools/)internal/agent/ is a leaf package in the dependency tree — it imports nothing from upper layers (no provider, tools, server, channel, or web). All protocol details, tool implementations, and UI rendering are “pushed upward.”
This means you can:
- Swap LLM backends (anthropic → openai → deepseek) without touching a single line of agent code.
- Add a new tool (terminal, browser, skill, workflow, MCP…) without modifying the agent loop.
- Change the rendering surface (T1 UI, Web, IM, Headless) without affecting core logic.
This one rule is the main reason octo-agent has been able to scale.