Ouroboros Agent OS
A specification-first runtime that turns AI coding requests into replayable, verified workflows.
- Source repo
- Q00/ouroboros
- Stars
- ★ 6.3k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeClaude API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Codex CLI user who wants to clarify constraints and acceptance criteria before implementing a task-management CLI.
- Not a fit if
- Teams wanting a single hosted code-generation service instead of configuring their own runtime
- Users who need MCP 1.x and the Claude Agent SDK in one unisolated environment
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Ouroboros is a local-first runtime and CLI for AI coding workflows built around Interview, Seed, Execute, Evaluate, and Evolve. It turns interview answers into an immutable Seed specification and records execution lineage and checkpoints through event sourcing for replay and recovery. The repository provides ooo session skills, the ouroboros CLI, MCP client/server integration, and runtime adapters for several coding environments. Its execution path uses Double Diamond decomposition, while verification runs Mechanical, Semantic, and Multi-Model Consensus stages. It fits teams that want clearer requirements, acceptance gates, and traceable work inside existing coding CLIs; it is not presented as a standalone hosted code-generation product.
A user can start a Socratic requirements interview with ooo interview "..." in an agent session or ouroboros init start in a terminal. The system crystallizes answers into a Seed and uses Ambiguity <= 0.2 as the documented threshold before Seed generation; ouroboros run seed.yaml then executes the workflow. Its documented modules include bigbang, execution, evaluation, evolution, persistence, orchestrator, and mcp; persistence uses SQLAlchemy and aiosqlite for events and checkpoints. ooo evaluate runs Mechanical, Semantic, and Multi-Model Consensus verification, while ooo evolve feeds evaluation back into another iteration and ooo ralph continues across sessions until ontology similarity reaches 0.95. ouroboros setup --runtime <...> configures supported runtimes including Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, and Zcode, and registers an MCP server where the host supports it.
- A Codex CLI user who wants to clarify constraints and acceptance criteria before implementing a task-management CLI.
- A Claude Code team that needs immutable Seed specifications and replayable execution records for features prone to scope drift.
- An engineer changing an established repository who needs brownfield exploration and configuration-file detection before planning work.
- A delivery-focused development team that wants Mechanical, Semantic, and Multi-Model Consensus checks after
ouroboros run seed.yaml. - A GitHub Copilot CLI user who needs live model discovery and MCP registration through
ouroboros setup --runtime copilot. - A developer running a long-lived refinement process across sessions with
ooo ralphand EventStore-backed lineage recovery.
How do you install or deploy this agent?
For the base package: pip install ouroboros-ai. For MCP support: pipx install 'ouroboros-ai[mcp]', then run ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi|zcode>; host registration requires an available uvx or pipx. The documented installer is curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash. Python 3.12+ is required; LiteLLM-bearing profiles support Python 3.12–3.13 only. Before first Copilot CLI setup, run gh auth login for live model discovery.
How do you use this agent?
After ouroboros setup, enter ooo in a supported coding-agent session. For example, run ooo interview "I want to build a task management CLI"; terminal users can use ouroboros init start followed by ouroboros run seed.yaml. Inspect work with ouroboros status executions, reconnect with ouroboros resume, and stop work with ouroboros cancel execution [<id>|--all]. Use ooo config when a pipeline stage needs a pinned model rather than the runtime’s current default.
What are this agent's strengths and limitations?
- Connects interviewing, immutable Seed specifications, execution, and a documented three-stage evaluation path instead of supplying a one-off prompt workflow.
- Event sourcing and checkpoints support lineage reconstruction, session recovery, and the cross-session
ooo ralphloop. - Offers one workflow contract across several coding CLIs, with MCP integration and selectable runtime backends.
- Documents numerical gates for implementation readiness (Ambiguity <= 0.2) and evolutionary convergence (ontology similarity >= 0.95).
- Its operating model depends on a supported coding CLI, model backend, or MCP host; it is not a self-sufficient application without external runtimes.
- MCP 2 and the current Claude Agent SDK require incompatible major versions of
mcp, so[mcp]and[claude]are intentionally separate profiles. - MCP host registration needs
uvxorpipx; setup exits without changing runtime configuration if neither launcher is available. - LiteLLM-bearing profiles are limited to Python 3.12–3.13, and
[all]excludes MCP 2.
How does this agent compare with similar options?
Against direct use of AI coding tools, Ouroboros emphasizes pre-implementation interviewing and Seed gates, followed by automated three-stage verification. It can be used on its own with supported CLIs or combined with Q00/ouroboros-plugins domain workflows and the Q00/ourocode terminal shell.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Ouroboros Agent OS This agent | 53 · Major gaps | CLIFree + model costs | ★ 6.3k | today | Python | Codex · Claude Code |
| CCCC Coordination Console | 61 · Some gaps | CLIFree + model costs | ★ 1.3k | 1d ago | Rust | Codex · Claude Code |
| Swarm | 60 · Some gaps | Agent plugin / skillFree | ★ 749 | 5mo ago | TypeScript | Claude Code |
| Unlazy Completion Discipline | 86 · Good | Agent plugin / skillFree | ★ 4.3k | 2mo ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README mentions installation script modifies config and registers MCP server, but does not specify least privilege principle; first use asks user, but does not state all external actions require confirmation; data flow description incomplete, does not specify what data is sent where; mentions API keys should be managed via environment variables, but does not specify handling; dependencies have version ceilings and exact pins, but no vulnerability scan evidence; installation script modifies system config, but no rollback mechanism; no source attribution. Deductions: least privilege, user confirmation, data flow transparency, sensitive data handling, external effects, rollback, source attribution all lack specific implementation details.
Evidence shows: README and pyproject.toml descriptions are consistent, but no runtime consistency tests; dependencies have version ranges, but no availability guarantees; error handling description incomplete, no failure message examples. Deductions: self-consistency, dependency availability, failure messages all lack specific evidence.
Evidence shows: README describes multiple use cases and runtime support, but does not specify target audience; capability boundaries incomplete, does not specify unsupported features; trigger commands clear, but not all trigger conditions; environment fit incomplete, does not specify all supported environments. Deductions: audience and scenarios, capability boundaries, trigger precision, environment fit all lack specific details.
Evidence shows: README structure clear, but no complete information architecture; installation notes detailed, but not for all platforms; naming stable, but no naming convention doc; examples provided, but no FAQ; known limitations not explicit; license MIT, but no copyright notice; no version changelog; maintenance responsibility not explicit. Deductions: information architecture, install notes, naming stability, examples and FAQ, known limitations, versioning changelog, maintenance responsibility all lack specific evidence.
Evidence shows: README describes output format, but no actual output examples; value proposition provided, but no actual effectiveness data; no cost-benefit analysis. Deductions: output usability, marginal value, cost benefit all lack specific evidence.
Evidence shows: README claims not backed by specific evidence; no cross-validation; no separation of facts and inferences. Deductions: claim traceability, cross-source corroboration, fact-inference separation all lack specific evidence.
- The installation script modifies system configuration and registers MCP servers; users should review the script before executing.
- Dependency pinning is strict, but no vulnerability scanning evidence is provided; users should verify dependency security themselves.
- Performance claims in README (e.g., Ambiguity thresholds) lack actual test data; users should rely on them with caution.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * fix(verification): defer execution-scoped assertions to runtime checks by @lee3Q in https://github.com/Q00/ouroboros/pull/2758 * test(providers): defer optional httpx imports behind the LiteLLM check by @zittenyetten in https://github.com/Q00/ouroboros/pull/2752 * test(providers): tolerate process exit during liveness checks and cleanup by @zittenyetten in https://github.com/Q00/ouroboros/pull/2753 * refactor(orchestrator): assemble public runs through one builder by @lee3Q in https://github.com/Q00/ouroboros/pull/2748 …View on GitHub ↗ -
Release notes excerpt
What's Changed * fix(artifacts): refuse project store writes that resolve outside the project by @Q00 in https://github.com/Q00/ouroboros/pull/2744 * fix(interview): offer the start turn's findings to later web lanes by @Q00 in https://github.com/Q00/ouroboros/pull/2743 * fix(mcp): accept prose in lateral attempts and interview excerpts by @zittenyetten in https://github.com/Q00/ouroboros/pull/2730 * fix(update): report installed Codex plugin version drift by @zittenyetten in https://github.com/Q00/ouroboros/pull/2537 …View on GitHub ↗ -
Release notes excerpt
What's Changed * fix(auto): run one worker attempt for a Seed whose criteria have no known source by @Q00 in https://github.com/Q00/ouroboros/pull/2737 * fix(context-pack): report each manifest by file and declared fields by @Q00 in https://github.com/Q00/ouroboros/pull/2739 * chore(deps-dev): bump types-pyyaml from 6.0.12.20260815 to 6.0.12.20260906 by @dependabot[bot] in https://github.com/Q00/ouroboros/pull/2551 * chore(release): prepare v0.59.7 by @Q00 in https://github.com/Q00/ouroboros/pull/2740 Full Changelog: https://github.com/Q00/ouroboros/compare/v0.59.6...v0.59.7View on GitHub ↗
FAQ
Does it replace Codex CLI or Claude Code?
Is evaluation entirely free?
Can interrupted work be resumed?
ouroboros resume, status commands, and cancellation commands.Can it be used directly with the Claude API?
ouroboros-ai[claude], but it does not register the MCP server because its configured Claude backend is unavailable inside the isolated process.