ouroboros

Purpose

Ouroboros is an Agent OS for AI programming, a local-first runtime layer whose goal is to turn uncertain agent work into replayable, observable, policy-constrained execution contracts. Its core idea is that most AI programming failures occur at the input end rather than the output end, and the bottleneck is not AI capability but human clarity. Therefore, it replaces casual prompt engineering with a structured "specification-first" workflow (interview, crystallize, execute, evaluate, evolve).

Main Capabilities

• Socratic interview: through questioning, vague ideas are converged into clear specifications. The project quantifies the degree of unclarity using "ambiguity," with a threshold of ambiguity no higher than 0.2; above that value, Seed generation is blocked and must be bypassed through an explicit force-pass option, which the CLI displays alongside continue and cancel.
• Execution contracts: every action is bound to a Seed, recorded in a ledger, and replayable, regardless of which LLM executes it.
• Evolution loop: the output of evaluation feeds back as input for the next generation. The project describes the convergence condition as ontology similarity no lower than 0.95.
• Ralph persistent loop: continuously runs the evolution loop across session boundaries until convergence; each step is stateless, the full lineage is reconstructed by EventStore, and it can continue after a machine restart.
• Tiered evaluation and a budgeted evolution loop.
• Drift measurement: weighted by goal (50%), constraints (30%), and ontology (20%), with a threshold no higher than 0.3.
• PAL routing: Frugal (1x) → Standard (10x) → Frontier (30x), automatically escalating on failure and de-escalating on success.
• Brownfield: automatically detects configuration files across multiple language ecosystems.
• Evolution for up to 30 generations, converging when ontology similarity is no lower than 0.95.
• Stagnation detection: identifies patterns such as spinning, oscillation, no drift, and diminishing returns.
• Agent OS runtime covers capability discovery, policy, instructions, event logs, and agent processes.
• The runtime backend is a pluggable abstraction layer (orchestrator.runtime_backend configuration), so the same workflow specification can run on different execution engines.
• Number of agents: 9 are highlighted below, plus 12 specialized agents, for a total of 21, all loaded on demand rather than preloaded.

Architectural Composition

The project is divided into three layers, with three repositories forming the same technology stack:

• Kernel (ouroboros): hold a contract, and every action becomes a Seed-bound, ledger-recorded, replayable event.
• Plugins (ouroboros-plugins): declare scoped capabilities on that contract, keeping domain workflows (reviewing PRs, handling Linear tickets, executing releases) auditable and policy-constrained rather than one-off prompts.
• Ourocode: a terminal shell that presents MCP state, interview questions, and wonderTool decisions as first-class TUI elements.

You can use ouroboros alone with any supported CLI, layer on plugins for domain workflows, or install ourocode for a unified terminal cockpit.

How to Use

After installation, you need to run a configuration command once in a coding agent, then run the first workflow command to start the Socratic interview. Within an agent session, use the ooo command; in the terminal, you can use the ouroboros CLI. Some skills (evaluate, evolve, unstuck, ralph, publish, maintain) are provided through agent skills, runtime rules, or MCP tools rather than direct ouroboros subcommands. Claude Code retains commands such as /resume, /run, /status, /help, and /config, and the safe direct skill forms are /ouroboros:ouroboros-run, /ouroboros:ouroboros-status, /ouroboros:ouroboros-help, and /ouroboros:ouroboros-config, while ooo run, ooo status, ooo help, and ooo config remain supported.

Installation supports a single command that automatically detects the environment. The Windows installer installs Git and uv via winget when they are missing, lets uv download its bundled Python, then installs ouroboros-ai and connects to the detected host; native Windows is still experimental, and Codex CLI requires WSL 2.

Supported runtimes include Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi CLI, OMP CLI, Zcode, Goose, GJC, Antigravity CLI, and Grok Build CLI. The installer detects available runtimes and registers the MCP server where the host supports it; you can also explicitly select a runtime via the setup command after installation. Copilot discovers its subscription catalog in real time through the GitHub Copilot models API; Kiro's settings selector queries the model list through the authenticated CLI, so account and enterprise allowlist changes require no hardcoded model table.

Python requirements: core and non-LiteLLM installations support Python 3.12-3.14; installations including LiteLLM ([litellm], [all], source --extra all) support Python 3.12-3.13, and current examples recommend Python 3.13. The recommended standalone installation is ouroboros-ai[mcp,tui], followed by explicitly selecting an MCP v2-compatible runtime. pip install 'ouroboros-ai[mcp]' is only suitable for embedding MCP client/server libraries in an already isolated Python environment; host registration requires an isolated launcher (uvx --isolated --python '>=3.12' or pipx), otherwise setup exits without changing the runtime configuration. Installing as an MCP server requires version 0.51.1 or later; earlier versions may fail to start when an existing environment shadows the [mcp] configuration. Homebrew is available through a self-hosted tap (not yet in homebrew-core) and installs the same package as PyPI.

DeepSeek support has two directions: first, use --llm-backend dsh (or the environment variable OUROBOROS_LLM_BACKEND=dsh) to point the interview/Seed/QA pipeline at DeepSeek's own models, with the underlying driver being the DeepSeek Harness ACP server; second, after installing the dsh-ouroboros plugin, enter ooo interview / ooo auto directly in the DeepSeek Harness chat, and the same MCP tools run natively.

Use Cases

Suitable for developers who want to turn vague ideas into validated, runnable codebases, especially when they needScenarios that span multiple AI coding runtimes, require replayable and auditable execution records, or need to bring domain workflows under policy constraints.

Limitations and notes

• The interview will prevent a Seed from being generated when the ambiguity level is higher than 0.2, unless it is explicitly forced through; the project describes this as "a debatable default, not a lock."
• It only works with the runtime and platform combinations listed above; native Windows is experimental, and Codex CLI requires WSL 2.
• There are the above limitations on versions and Python versions.
• Compatibility note: ouroboros-ai[dashboard] is still accepted as a compatibility alias/no-op, but does not install the dashboard runtime payload; [all] includes this no-op alias only for compatibility.
• The project is not affiliated with any cryptocurrency, token, memecoin, or trading community, does not issue, endorse, or hold any tokens; any token claiming to be associated with this project is unauthorized.
• There is also an unrelated open-source project with the same name (Anton Razzhigaev's self-modifying, autonomous-memory agent); the two share no code and are unrelated; this project locks the spec before execution rather than rewriting its own architecture.
• Specific pricing, fees, and other information for each platform and runtime are not yet provided.