Developer and ArchitectureExplanation
Why five layers
Model, Runtime, Harness, Agent, Self-Improving. Why the boundaries fall where they do.
On this page
Karpathy's LLM-OS analogy puts the LLM where a computer puts its CPU. GEODE layers the analogy like an operating system, and the current answer is five. Each layer owns exactly one thing.
These five layers describe architecture, not the RSI roadmap's L1–L5. A layer named Self-Improving does not establish L5 autonomy.
The five layers
| Layer | OS analogue | Owns | Representative code |
|---|---|---|---|
| Model | Kernel / CPU | The LLM itself: provider routing and inference | core/llm/providers/, core/llm/router/ |
| Runtime | Syscalls + drivers | Tools, MCP, memory, skills: every path the LLM uses to touch the outside | core/tools/, core/mcp/, core/memory/ |
| Harness | Shell + init | CLI, serve, hooks, gateway, lanes: every path users and messengers use to reach the system | core/cli/, core/server/, core/hooks/, core/orchestration/ |
| Agent | Execution loop | while(tool_use): the always-running execution unit and sub-agents | core/agent/loop/, core/agent/sub_agent.py |
| Self-Improving | Package manager + update channel | Mutates the scaffold the agent runs on, selects via audits, preserves lineage | evolve/scaffold_search/ |
Why the fifth layer became explicit
Until the S-5 structure sprint (v0.99.163), GEODE described itself as four layers, and the self-improving code had no place in the diagram. A code census said otherwise: roughly half of the self-improving modules mapped to none of the four layers. The diagram had fallen out of sync with the code.
The boundary's justification is dependency direction. The self-improving layer invokes the Agent layer as its measurement subject (the audit subprocess runs the same AgenticLoop), but the Agent layer knows nothing about the self-improving layer. Injection happens through exactly one narrow interface: the GEODE_WRAPPER_OVERRIDE environment variable and an SoT file, consumed by core/agent/system_prompt.py. One-way dependency plus a narrow interface identifies a distinct upper layer.
The boundary is also enforced by change cost. By the program.md contract, the self-improving agent must not modify the four measurement modules (measure.py, fitness.py, gate.py, ledger.py): changing the measurement gear changes the yardstick used on the system under test. That invariant is only declarable because the layer is separate.
Why the count settles at five
- Three layers (Model + Runtime + Agent) leave no room for hooks, gateway, serve, or lanes.
- Four layers hide the self-improving code; the census above falsified that shape.
- Six layers (say, splitting Runtime into Tools and Memory) cost more than they buy: tool results become context, so the two move together.
Evidence the boundaries are real
If a boundary is more than decoration, swap experiments must pass. Switching models (/model) touches only the Model layer. Adding a messenger adds one poller in the Harness. A rejected scaffold mutation triggers a revert in the Self-Improving layer that restores the SoT without touching code in the layers below. All three are single-layer changes in the current tree.
Next
- The five-layer stack. What each layer contains.
- Architecture deep-dive. Data flows across the layers.
- The outer loop. What the fifth layer actually does.
Moved from the GEODE repository’s documentation site. Source commit de077a4 · View the source on GitHub