q00/ouroboros

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