Q00/ouroboros: an Agent OS that keeps the grading command out of the agent's contract

The prompt-engineering problem ouroboros is aimed at

Most coding-agent workflows put the task and its acceptance criteria in the same message. The agent can read the test command, so it can write code that satisfies the command rather than the requirement. The README states the design intent plainly: "The grading command and expected result never make it into the success contract we hand it." Ouroboros splits the two. A human-facing interview extracts the requirement, that requirement is frozen as a Seed, and the executing agent receives the Seed without the verify command or the expected output. The target user is a developer who already drives Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro, Copilot or a similar runtime and is tired of re-explaining scope in every session. It is not a model, not a hosted service, and not a replacement for the agent itself. It is a local runtime layer that sits between the human and whichever CLI does the work.

Interview, Seed, Ledger, Runtime: the four primitives in the stack

The README describes three repositories in one stack. This repository, Q00/ouroboros, is the kernel and owns Seed, Ledger, Runtime, MCP and the safety boundaries. Ouro-labs/ourocode is the shell, a native terminal UI for running ooo workflows across Claude, Codex and Gemini CLIs in one session. Ouro-labs/ouroboros-plugins is the application layer, a plugin contract that composes core primitives into installable domain programs such as PR operations, Jira sync, incidents and releases. The flow through the kernel is interview, crystallize, execute, evaluate, evolve. The interview is interactive and reports an ambiguity score; the README screenshots show a Discord-hosted run ending at "Final ambiguity: 0.15" and a terminal session asking about ordering and scope. The crystallize step writes the Seed. The Ledger records every action as a Seed-bound, replayable event, which is what makes the workflow observable after the fact rather than only during the session. The runtime adapter is the piece that lets the same Seed drive different CLIs. The README calls the engine the shared part and the prompt the per-task part: "Separate runs, separate hosts. Different tasks on purpose -- the engine is what is shared, not the prompt."

Installing ouroboros and running ooo setup in one runtime

The README gives a one-line installer for macOS, Linux and WSL 2, and a separate PowerShell path for Windows that the README says needs no Python and installs Git and uv for you.

curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme-hero bash

On Windows the equivalent is:

irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

After installation the README says to run ooo setup once inside your coding agent. The environment file lists the knobs that matter for a first run. Copy .env.example to .env or to ~/.ouroboros/.env, then uncomment one provider key and set the runtime backend:

ANTHROPIC_API_KEY=sk-ant-...
OUROBOROS_RUNTIME=claude
OUROBOROS_LLM_BACKEND=claude

The .env.example file documents OUROBOROS_RUNTIME as accepting claude (the default), codex, opencode, hermes, gemini, kiro or copilot. OUROBOROS_LLM_BACKEND takes the same set and controls the LLM-only flows for interview, seed and eval. Two optional variables are worth knowing before the first run: OUROBOROS_CLI_PATH points at a custom Claude CLI wrapper, which the file suggests for instrumented CLIs used in OTEL tracing, and OUROBOROS_WEB_SEARCH_TOOL names the MCP web-search tool the interview should prefer, with mcp__tavily__search given as an example. The repository also carries .mcp.json and .mcp.codex.json, and the README's MCP name is io.github.Q00/ouroboros, so the interview can be driven from a host that speaks MCP rather than from the terminal. The README's DeepSeek Harness example shows the tool being called turn by turn as mcp__ouroboros__ouroboros_interview.

What the interview does not resolve for you

The ambiguity score is a number, not a gate. Nothing in the README says the workflow refuses to proceed above a threshold, and the screenshots show scores of 0.15 and an unspecified terminal value rather than a pass or fail. If your requirement is genuinely ambiguous, the interview surfaces that; it does not make the decision. The second limitation is environmental. The runtime adapters shell out to CLIs that must already be installed and authenticated. The .env.example file documents OUROBOROS_KIRO_CLI_PATH and OUROBOROS_COPILOT_CLI_PATH as overrides for when PATH lookup fails, and it notes that winget and scoop installs on Windows can land the binary outside the default PATH. That is a real setup cost multiplied by the number of runtimes you want to use. Third, the project is honest about its stage: pyproject.toml carries the classifier Development Status :: 4 - Beta, and the dependencies section shows unusual care in one place, with the python-dotenv ceiling deliberately tighter than the surrounding major-version bounds because that library parses .env, which the comment calls a documented trust boundary. That comment is a signal about how the maintainers think, not a guarantee of interface stability. If you need a frozen API to build against, this is the wrong moment.

How ouroboros differs from a plain agent loop or a test-first harness

A plain agent loop and ouroboros both iterate, but they iterate on different objects. A typical loop re-prompts the model with the failure text until the tests pass. Ouroboros iterates on the Seed and the evaluation contract, and the README describes the loop as budgeted, which means the number of generations is a parameter rather than an open-ended retry. The closest comparison in the wider tooling world is a test-first or spec-first harness that generates code against a failing test. The difference is where the acceptance criteria live. In a test-first harness the test file is in the repository and the agent can read it, which is exactly the leak ouroboros is designed to prevent. Ouroboros keeps the verify command and expected output out of the worker's contract and records the run in the Ledger instead. That is a stronger isolation property and a weaker one at the same time: the agent cannot game the check, but it also cannot read the check to understand intent, so the Seed has to carry enough context on its own. The examples directory, with files such as examples/dummy_seed.yaml and examples/coordinator_test_seed.yaml, is where that context is written down.

Maintenance, licensing and the cost of upgrading

The repository is not archived and the last push was on 2026-09-10. The release cadence is tight: v0.54.1 on 2026-09-08, v0.54.2 on 2026-09-09 and v0.54.3 on 2026-09-10. Three patch releases in three days suggests active iteration on a beta line, and it also means the version you pin today will be several patches behind within a week. pyproject.toml requires Python 3.12 or newer, so the upgrade cost starts with your interpreter. Dependencies are bounded ranges rather than exact pins, with uv.lock provided for reproducible installs, and the file states that a test enforces upper bounds on runtime and optional dependencies. The licence is MIT, which permits commercial use and modification with the copyright notice retained; the repository also carries SECURITY.md, CODE_OF_CONDUCT.md and CONTRIBUTING.md, and a TELEMETRY.md and UNINSTALL.md at the top level, so read TELEMETRY.md before deploying this on a machine that touches proprietary source. The .env file is treated as a trust boundary in the code comments, which is worth remembering if you commit configuration.

Editorial conclusion

Adopt ouroboros if you already run a coding agent on real repositories and want the acceptance criteria pinned in a file rather than retyped in each prompt. Do not adopt it if you need a stable API: pyproject.toml declares Development Status 4 - Beta, and the last push was on 2026-09-10. Before committing, read the Seed schema in src/ and the runtime adapter table in .env.example, then run ooo setup in one runtime and confirm the interview writes a Seed you can edit by hand.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. Q00/ouroboros on GitHub
4. README
5. Releases