Architecture
axon owns the loop. cortex owns the product on top. Layers point one direction.
cortex — the product
main.goflags · wiring · mode dispatch
configresolve model · prompt · MCP
uiterminal · transcript · commands
config & theme are leaves · ui owns the terminal · main only wires
the only seam
axon — the runtime ↗ docs
loopstreaming chat · tool dispatch
sessionappend-only · byte-for-byte undo
prunersecondary-LLM context parking
tools7 built-ins · MCP auto-discovery
The two boundary rules
1
internal/config imports nothing else from this module.It is a leaf. If a value there needs a type from a higher layer, it belongs in that layer.2
internal/ui/event.go is the only file that touches both axon and Bubble Tea.axon calls its event handler synchronously on the turn goroutine; Bubble Tea owns the terminal from its own. Nothing else may cross that line.What main.go wires
main.go is wiring and nothing else. Every decision it makes is delegated: configuration to internal/config, presentation to internal/ui, and the loop itself to axon.
⚓
Parse flags
interactive · non-interactive · version
→
⚙️
Load config
resolve model & pruner vs axon Settings
→
📡
Tap models
trace wiretap on main + pruner
→
▶
Run loop
build axon Options · attach handler · go
Why the system prompt must not list tools
The tool catalog is appended by axon, natively, to every request. If a custom system_prompt also enumerates the tools, the model sees the catalog twice — and you pay for those duplicated tokens on every single call. This is exactly the kind of thing the trace log was built to catch: a ~2,100-token duplication that was invisible in the event stream and obvious in the wire log.
Why the transcript isn't an alternate screen
alternate screen
Vanishes on exit. The session is gone the moment cortex stops — nothing to scroll, search or copy.
committed scrollback
Stays in your terminal's own scrollback. A finished session is scrollable, searchable and copyable — even after cortex exits. Only work in flight redraws.
📖
Deeper into axon: the loop, session, pruner and tools are all axon's. Readaxon's architecture,context management, andthe built-in tools for the layer cortex builds on.