# q00/ouroboros architecture

> Architecture diagram of the GitHub repository q00/ouroboros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/q00/ouroboros
- Repository: https://github.com/q00/ouroboros

## Overview

#### Purpose and Entry Points
Ouroboros is a local-first Python “Agent OS” for turning AI-assisted work into specification-first, replayable workflows: interview → immutable Seed → execution → evaluation → evolution. Primary terminal entry points are `src/ouroboros/__main__.py` and `src/ouroboros/cli/main.py`; agent-host entry points are packaged skills and the MCP server/tool surface.

#### Command, Skill, and MCP Boundary
The CLI command modules dispatch user operations such as setup, interview/auto, run, status, resume, cancellation, and TUI launch. Skills expose `ooo <command>` inside supported agent runtimes. MCP is the integration boundary for hosts: server adapters register tools, job management supports detached work, and bridge components connect MCP servers.
- `src/ouroboros/cli/commands/auto.py`
- `src/ouroboros/mcp/server/adapter.py`
- `src/ouroboros/mcp/tools/registry.py`

#### Specification Acquisition and Auto Pipeline
The “Big Bang” and Auto subsystems turn an initial idea or existing repository context into a qualified Seed. They conduct/question-classify interviews, infer task domain/profile, detect gaps and ambiguity, maintain provenance and ledgers, apply safe defaults, and produce handoff material. This is the gate before execution rather than an execution engine itself.
- `src/ouroboros/bigbang/interview.py`
- `src/ouroboros/auto/pipeline.py`
- `src/ouroboros/auto/ledger.py`

#### Core Contracts, Control, and Lineage
`core` defines the stable domain boundary: Seed and Seed-contract types, control contracts/directives, execution preferences, project identity, lineage, human-in-the-loop state, and workspace/worktree primitives. The conductor and AC tree represent controlled decomposition and progression; other layers should consume these contracts rather than recreate workflow state.
- `src/ouroboros/core/seed.py`
- `src/ouroboros/core/control_contract.py`
- `src/ouroboros/core/conductor.py`

#### Orchestration and Runtime Dispatch
The orchestrator converts a Seed/workflow into staged, bounded agent execution. It coordinates decomposition, dependency analysis, context packing, routing/escalation, parallel execution, execution authority, evidence, cancellation, and lifecycle state. Runtime factories select concrete workers according to backend capabilities and configured policy, preserving one workflow contract across heterogeneous agent engines.
- `src/ouroboros/orchestrator/coordinator.py`
- `src/ouroboros/orchestrator/runner.py`
- `src/ouroboros/orchestrator/runtime_factory.py`

#### Provider and Runtime Integrations
The project supports CLI/API-backed agent runtimes including Claude Code, Codex, OpenCode, Hermes, Gemini, Goose, Kiro, Copilot, Pi, Zcode, and GJC-related bridges. Provider adapters normalize model responses and tool use; orchestrator runtime implementations own process/session-specific execution. LiteLLM is an optional multi-provider path, while Copilot model discovery uses GitHub authentication/API.
- `src/ouroboros/providers/factory.py`
- `src/ouroboros/providers/litellm_adapter.py`
- `src/ouroboros/orchestrator/codex_cli_runtime.py`

#### Verification, Evolution, and Durable Observability
Execution results pass a staged evaluation pipeline: mechanical checks, semantic review, and consensus/adversarial checks, with collected verification artifacts. Evolution consumes outcomes to reflect, project directives, rewind, or continue until convergence/watchdog limits. Events, checkpoints, and persistence provide replayable lineage; the event store uses SQL schema/migrations, and TUI/dashboard readers visualize state without being execution authorities.
- `src/ouroboros/evaluation/pipeline.py`
- `src/ouroboros/evolution/loop.py`
- `src/ouroboros/persistence/event_store.py`

#### Extensibility and User Surfaces
Plugins package user-level agents, skills, manifests, scoped hooks, audit/ledger adapters, trust checks, and a firewall around tool calls. Terminal observability is provided by the Python Textual-oriented TUI, with a separate Rust TUI crate and optional web dashboard daemon also present. Plugin artifacts are a controlled extension boundary, not direct access to core execution internals.
- `src/ouroboros/plugin/firewall.py`
- `src/ouroboros/plugin/manifest.py`
- `src/ouroboros/tui/app.py`

Main entry points: [`src/ouroboros/orchestrator/coordinator.py`](https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/coordinator.py) (Execution coordinator), [`src/ouroboros/cli/commands/auto.py`](https://github.com/q00/ouroboros/blob/main/src/ouroboros/cli/commands/auto.py) (CLI commands), [`src/ouroboros/auto/pipeline.py`](https://github.com/q00/ouroboros/blob/main/src/ouroboros/auto/pipeline.py) (Auto pipeline), [`src/ouroboros/core/seed.py`](https://github.com/q00/ouroboros/blob/main/src/ouroboros/core/seed.py) (Seed contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; Integration"]
  node_cli["CLI commands<br/>command surface<br/>[auto.py]"]
  node_skills["Packaged skills<br/>agent-host surface"]
  node_mcp{{"MCP server adapters<br/>integration boundary<br/>[adapter.py]"}}
  node_mcp_tools["MCP tool registry<br/>[registry.py]"]
  node_plugins{{"Plugin firewall<br/>extension boundary<br/>[firewall.py]"}}
  node_tui["Terminal TUI<br/>observability surface<br/>[app.py]"]
end

subgraph group_spec["Specification"]
  node_bigbang["Interview acquisition<br/>specification intake<br/>[interview.py]"]
  node_auto["Auto pipeline<br/>specification pipeline<br/>[pipeline.py]"]
  node_ledger[("Provenance ledger<br/>specification state<br/>[ledger.py]")]
end

subgraph group_execution["Core Execution"]
  node_seed["Seed contracts<br/>core domain contracts<br/>[seed.py]"]
  node_control["Control &amp; conductor<br/>workflow control<br/>[conductor.py]"]
  node_orchestrator["Execution coordinator<br/>orchestration<br/>[coordinator.py]"]
  node_runtime_factory["Runtime factory<br/>runtime dispatch<br/>[runtime_factory.py]"]
  node_runtimes["Agent runtimes<br/>process/session execution"]
  node_providers["Provider adapters<br/>model integration<br/>[factory.py]"]
end

subgraph group_assurance["Assurance &amp; State"]
  node_evaluation["Evaluation pipeline<br/>verification<br/>[pipeline.py]"]
  node_evolution["Evolution loop<br/>outcome control<br/>[loop.py]"]
  node_event_store[("Event store<br/>durable lineage<br/>[event_store.py]")]
end

node_cli -->|"starts interview"| node_bigbang
node_cli -->|"starts auto intake"| node_auto
node_cli -->|"runs workflow"| node_orchestrator
node_skills -->|"invokes commands"| node_cli
node_mcp -->|"registers"| node_mcp_tools
node_mcp_tools -->|"host operations"| node_orchestrator
node_bigbang -->|"interview context"| node_auto
node_auto -->|"records provenance"| node_ledger
node_auto -->|"produces qualified Seed"| node_seed
node_ledger -.->|"supports handoff"| node_seed
node_seed -->|"governs progression"| node_control
node_seed -->|"execution contract"| node_orchestrator
node_control -->|"directives and decomposition"| node_orchestrator
node_orchestrator -->|"dispatches work"| node_runtime_factory
node_runtime_factory -->|"selects implementation"| node_runtimes
node_runtimes -->|"uses model adapters"| node_providers
node_orchestrator -->|"submits results"| node_evaluation
node_evaluation -->|"verification outcomes"| node_evolution
node_evolution -->|"rewind or continue"| node_control
node_orchestrator -->|"records events and checkpoints"| node_event_store
node_evaluation -->|"stores evidence"| node_event_store
node_tui -.->|"reads state"| node_event_store
node_plugins -->|"controlled tool extensions"| node_mcp_tools
node_plugins -.->|"scoped extensions"| node_orchestrator

click node_cli "https://github.com/q00/ouroboros/blob/main/src/ouroboros/cli/commands/auto.py"
click node_mcp "https://github.com/q00/ouroboros/blob/main/src/ouroboros/mcp/server/adapter.py"
click node_mcp_tools "https://github.com/q00/ouroboros/blob/main/src/ouroboros/mcp/tools/registry.py"
click node_bigbang "https://github.com/q00/ouroboros/blob/main/src/ouroboros/bigbang/interview.py"
click node_auto "https://github.com/q00/ouroboros/blob/main/src/ouroboros/auto/pipeline.py"
click node_ledger "https://github.com/q00/ouroboros/blob/main/src/ouroboros/auto/ledger.py"
click node_seed "https://github.com/q00/ouroboros/blob/main/src/ouroboros/core/seed.py"
click node_control "https://github.com/q00/ouroboros/blob/main/src/ouroboros/core/conductor.py"
click node_orchestrator "https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/coordinator.py"
click node_runtime_factory "https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/runtime_factory.py"
click node_runtimes "https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/codex_cli_runtime.py"
click node_providers "https://github.com/q00/ouroboros/blob/main/src/ouroboros/providers/factory.py"
click node_evaluation "https://github.com/q00/ouroboros/blob/main/src/ouroboros/evaluation/pipeline.py"
click node_evolution "https://github.com/q00/ouroboros/blob/main/src/ouroboros/evolution/loop.py"
click node_event_store "https://github.com/q00/ouroboros/blob/main/src/ouroboros/persistence/event_store.py"
click node_plugins "https://github.com/q00/ouroboros/blob/main/src/ouroboros/plugin/firewall.py"
click node_tui "https://github.com/q00/ouroboros/blob/main/src/ouroboros/tui/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_skills,node_mcp,node_mcp_tools,node_plugins,node_tui toneBlue
class node_bigbang,node_auto,node_ledger toneAmber
class node_seed,node_control,node_orchestrator,node_runtime_factory,node_runtimes,node_providers toneMint
class node_evaluation,node_evolution,node_event_store toneRose
```

## Components

### Entry & Integration

- [CLI commands](https://github.com/q00/ouroboros/blob/main/src/ouroboros/cli/commands/auto.py): command surface · Dispatches setup, interview, run, status, resume, cancellation, and TUI actions. · `src/ouroboros/cli/commands/auto.py`
- **Packaged skills**: agent-host surface · Expose ooo commands inside supported agent runtimes.
- [MCP server adapters](https://github.com/q00/ouroboros/blob/main/src/ouroboros/mcp/server/adapter.py): integration boundary · Registers host-facing tools and supports bridged MCP servers. · `src/ouroboros/mcp/server/adapter.py`
- [MCP tool registry](https://github.com/q00/ouroboros/blob/main/src/ouroboros/mcp/tools/registry.py): tool registry · `src/ouroboros/mcp/tools/registry.py`
- [Plugin firewall](https://github.com/q00/ouroboros/blob/main/src/ouroboros/plugin/firewall.py): extension boundary · Controls plugin manifests, hooks, trust checks, and tool-call access. · `src/ouroboros/plugin/firewall.py`
- [Terminal TUI](https://github.com/q00/ouroboros/blob/main/src/ouroboros/tui/app.py): observability surface · Visualizes workflow state without execution authority. · `src/ouroboros/tui/app.py`

### Specification

- [Interview acquisition](https://github.com/q00/ouroboros/blob/main/src/ouroboros/bigbang/interview.py): specification intake · Conducts and classifies interviews to establish an initial specification. · `src/ouroboros/bigbang/interview.py`
- [Auto pipeline](https://github.com/q00/ouroboros/blob/main/src/ouroboros/auto/pipeline.py): specification pipeline · Qualifies ideas or repository context, detects gaps, and prepares handoff material. · `src/ouroboros/auto/pipeline.py`
- [Provenance ledger](https://github.com/q00/ouroboros/blob/main/src/ouroboros/auto/ledger.py): specification state · Records acquisition provenance, defaults, and ambiguity decisions. · `src/ouroboros/auto/ledger.py`

### Core Execution

- [Seed contracts](https://github.com/q00/ouroboros/blob/main/src/ouroboros/core/seed.py): core domain contracts · Immutable Seed and workflow contracts are the stable boundary between phases. · `src/ouroboros/core/seed.py`
- [Control & conductor](https://github.com/q00/ouroboros/blob/main/src/ouroboros/core/conductor.py): workflow control · Owns directives, decomposition, progression, and human-in-the-loop control state. · `src/ouroboros/core/conductor.py`
- [Execution coordinator](https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/coordinator.py): orchestration · Stages bounded agent execution with routing, context, authority, cancellation, and evidence. · `src/ouroboros/orchestrator/coordinator.py`
- [Runtime factory](https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/runtime_factory.py): runtime dispatch · Selects workers by backend capability and configured policy. · `src/ouroboros/orchestrator/runtime_factory.py`
- [Agent runtimes](https://github.com/q00/ouroboros/blob/main/src/ouroboros/orchestrator/codex_cli_runtime.py): process/session execution · Concrete CLI and API runtime implementations execute assigned work. · `src/ouroboros/orchestrator/codex_cli_runtime.py`
- [Provider adapters](https://github.com/q00/ouroboros/blob/main/src/ouroboros/providers/factory.py): model integration · Normalize heterogeneous model responses and tool use, including optional LiteLLM. · `src/ouroboros/providers/factory.py`

### Assurance & State

- [Evaluation pipeline](https://github.com/q00/ouroboros/blob/main/src/ouroboros/evaluation/pipeline.py): verification · Runs mechanical, semantic, and consensus or adversarial checks. · `src/ouroboros/evaluation/pipeline.py`
- [Evolution loop](https://github.com/q00/ouroboros/blob/main/src/ouroboros/evolution/loop.py): outcome control · Reflects on outcomes and directs rewind or continuation until convergence limits. · `src/ouroboros/evolution/loop.py`
- [Event store](https://github.com/q00/ouroboros/blob/main/src/ouroboros/persistence/event_store.py): durable lineage · Persists replayable events, checkpoints, and execution lineage. · `src/ouroboros/persistence/event_store.py`

## Connections

- CLI commands → Interview acquisition: starts interview
- CLI commands → Auto pipeline: starts auto intake
- CLI commands → Execution coordinator: runs workflow
- Packaged skills → CLI commands: invokes commands
- MCP server adapters → MCP tool registry: registers
- MCP tool registry → Execution coordinator: host operations
- Interview acquisition → Auto pipeline: interview context
- Auto pipeline → Provenance ledger: records provenance
- Auto pipeline → Seed contracts: produces qualified Seed
- Provenance ledger → Seed contracts: supports handoff
- Seed contracts → Control & conductor: governs progression
- Seed contracts → Execution coordinator: execution contract
- Control & conductor → Execution coordinator: directives and decomposition
- Execution coordinator → Runtime factory: dispatches work
- Runtime factory → Agent runtimes: selects implementation
- Agent runtimes → Provider adapters: uses model adapters
- Execution coordinator → Evaluation pipeline: submits results
- Evaluation pipeline → Evolution loop: verification outcomes
- Evolution loop → Control & conductor: rewind or continue
- Execution coordinator → Event store: records events and checkpoints
- Evaluation pipeline → Event store: stores evidence
- Terminal TUI → Event store: reads state
- Plugin firewall → MCP tool registry: controlled tool extensions
- Plugin firewall → Execution coordinator: scoped extensions