Ouroboros
03

3. Components

Ouroboros splits into a command entry point, a management engine, a work spec, an execution layer, a record store, and an evaluator.

Ouroboros 0.50.4upstream 456a134verified 2026-07-16 against docs and code
Diagram: the user reaches Core through the ooo command; Core produces a Seed and hands it to the runtime; records accumulate in EventStore and Ledger
Work flows user → ooo command → Core → runtime. Records land in the EventStore and the Ledger.

3.1 What each component does

ComponentRole
YouProvide the idea, answer questions, approve the Seed and the result.
ooo commandThe entry point for Ouroboros features inside a Claude Code session, e.g. ooo interview, ooo run.
CoreThe engine that runs the Interview, generates Seeds, manages execution order, and calls evaluation. Talks to the runtime over MCP (Model Context Protocol).
SeedA YAML work spec holding goal, constraints, completion criteria, and data structure. It does not change during a run.
runtimeThe AI coding tool that actually touches files and code. Claude Code is the default; Codex CLI, OpenCode, and others are supported.
EventStoreA local SQLite database storing every execution event. Used to recover interrupted sessions.
LedgerA record of the assumptions and exclusions confirmed while questioning and writing the Seed.
EvaluatorVerifies results in three stages: run the tests, compare against the completion criteria, and cross-check with multiple models when needed.

3.2 Data flow

  1. You enter an idea through the ooo command.
  2. Core asks about missing decisions in the Interview and turns the answers into a Seed.
  3. Core hands the Seed to the runtime, and the runtime writes the code.
  4. The Evaluator compares the result against the Seed's completion criteria.
  5. Every step's events go to the EventStore; decision grounds go to the Ledger.

Because Core and the runtime are separate, the same Seed can be used with a different runtime.

3.3 Storage locations

Ouroboros stores its data under ~/.ouroboros/ in your home folder.

File / folderContent
config.yamlMain configuration, including the runtime choice
seeds/Generated Seed YAML files
ouroboros.dbEventStore (SQLite)
logs/ouroboros.logLogs
data/, worktrees/Auto-session state and isolated work folders

Depending on your choices, the project folder may gain a CLAUDE.md command summary and a .ouroboros/ configuration.