Ouroboros puts an interview between a vague request and a coding agent

The interview sits between the request and the prompt

Ouroboros describes itself as an interview-gated, staged-evaluation, budgeted evolution loop, and the interview constrains everything after it. A task does not reach a coding agent as a prompt. The terminal path runs `ouroboros init start`, which asks about ordering and scope and then reports an ambiguity score. On the DeepSeek Harness the interview arrives as `mcp__ouroboros__ouroboros_interview`, one turn at a time, with fan-out results submitted between rounds. On Claude Code, six advisory lanes run in parallel before the interview submits. The Hermes chat-bot demo, running a kart-racing game as a Discord bot, ends on the line `Final ambiguity: 0.15`. That score is the gate the loop waits on.

The grading command is kept out of the worker's contract

The packaging metadata states that Ouroboros pins an acceptance spec and omits any verify command or expected output from the worker's contract. The tagline repeats the same decision: the grading command and expected result never make it into the success contract handed to the agent. This is the sharpest idea in the repository and also the hardest to check from outside it. A worker that never sees the test command cannot pass by memorising an assertion, and the spec has to be satisfiable by reading alone. The grading still happens inside Ouroboros: the project describes a staged evaluation loop, and .env.example names an LLM backend for the interview, seed and eval flows. It is only kept out of the contract the worker sees.

One installer, then `ooo setup` inside the agent

Installation is a single shell pipeline, and the macOS, Linux and WSL 2 path fetches the script from main and passes OUROBOROS_INSTALL_REF=readme-hero to it:

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

Windows goes through PowerShell instead, and that variant notes that no Python is needed because it installs Git and uv for you:

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

After the installer finishes, the first thing you run is not a command of your own. You run `ooo setup` once inside your coding agent. Both variants assume a working network path to `raw.githubusercontent.com`, the POSIX line assumes curl and a shell that accepts a piped script, and the Windows line assumes PowerShell rather than cmd. The package itself declares `requires-python` of 3.12 or newer.

OUROBOROS_RUNTIME picks the CLI, OUROBOROS_LLM_BACKEND picks the interview model

The `.env.example` file is the configuration template, and it splits two decisions that the CLI name collapses into one. `OUROBOROS_RUNTIME` selects the agent runtime backend and defaults to `claude`, with `codex`, `opencode`, `hermes`, `gemini`, `kiro` and `copilot` listed as the other accepted values. `OUROBOROS_LLM_BACKEND` is the LLM-only backend for the interview, seed and eval flows and takes the same set of values, so you can grade with one model and execute with another. Provider keys sit above them: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY` and `OPENROUTER_API_KEY`, all commented out. Three path overrides let you point at a wrapper instead of a PATH lookup: `OUROBOROS_CLI_PATH` with tilde expansion for instrumented CLIs, `OUROBOROS_KIRO_CLI_PATH` for kiro-cli, and `OUROBOROS_COPILOT_CLI_PATH`, written for winget and scoop installs that land the binary outside the default PATH. `OUROBOROS_WEB_SEARCH_TOOL` takes an MCP tool name, with `mcp__tavily__search`, `mcp__brave__search` and `WebFetch` offered as examples. What this file cannot do is reach every host the project advertises. The project claims 14 runtimes, but only seven have a documented value here; the rest get no key, no flag and no documented path in this file. Copy the file to `.env` or `~/.ouroboros/.env` before editing it.

Three repositories share one kernel, and two of them live elsewhere

Ouroboros calls itself an Agent OS, and this repository carries its own agent wiring at the root: `.claude-plugin/`, `.codex-plugin/`, `.agents/`, `.claude/` and `.codex/`, plus `.mcp.json` and `.mcp.codex.json`, alongside `src/`, `crates/`, `integrations/`, `skills/` and `tools/`.

A Seed is the unit of work, and `examples/` holds test fixtures for it

The README calls Ouroboros the Agent OS for replayable AI coding workflows, and the Kiro demo describes the interview turning a vague request into a structured, testable Seed, so the Seed is the place to look when a run surprises you. The repository ships several shapes in `examples/`: `dummy_seed.yaml`, `subac_test_seed.yaml`, `parallel_subac_test_seed.yaml`, `coordinator_test_seed.yaml`, and a `task_manager/` directory that matches the terminal demo running `ouroboros init start` for task management. Three of the four YAML files carry `test` in the filename, which says they are fixtures for the test suite rather than templates to copy, and that is the weak point here. The on-disk seed contract can be inferred from those fixtures and from the `.ouroboros/` state directory. Plan on reading the YAML directly.

`.env` is parsed as a trust boundary, and the repo ships a denylist for it

The dependency list carries a comment that explains a policy rather than a pin: the ceiling is deliberately tighter than the major-version bounds around it, because this code parses `.env`, described as a documented trust boundary, so only patch releases flow without review. The pointer is `UNTRUSTED_ENV_DENYLIST` in `config/untrusted_env.py`. The bounds listed above the comment are ordinary ranges: `aiosqlite>=0.20.0,<1.0.0`, `anyio>=4.0.0,<5.0.0`, `click>=8.1.0,<9.0.0`, `jsonschema>=4.21.0,<5.0.0`, `pydantic>=2.0.0,<3.0.0` and `prompt-toolkit>=3.0.0,<4.0.0`. A named test, `test_runtime_and_optional_dependencies_have_upper_bounds`, reserves `==` for the optional extras so the core runtime stays on ranges. At the repository root, `TELEMETRY.md` and `UNINSTALL.md` sit beside `SECURITY.md`, which tells you the project expects questions about data collection and removal to be answerable somewhere. That is a file to read first, not a detail to assume.

The ambiguity gate cannot settle a decision nobody has made

Two limits decide whether Ouroboros fits your work. The first is that an ambiguity score measures how clear the request is, not how valuable the answer will be. When the open question is a product decision rather than a spec detail, the interview cannot resolve it, and the score only records that a human has not decided yet. Ouroboros spends its first stage finding that out, which is cheaper than a wrong build but not free. Nothing in the loop upgrades a decision nobody has made. The second limit is maturity. The package declares `Development Status :: 4 - Beta`, the version numbers move quickly, and the last three tags are v0.59.7 on 2026-10-23, v0.59.8 on 2026-10-23 and v0.59.9 on 2026-10-25, with the last push on 2026-11-01. Underneath that moving surface the repository is unusually well equipped for scrutiny, with `CHANGELOG.md`, `HANDOFF.md`, `backlog.md`, `llms.txt`, `llms-full.txt`, `AGENTS.md`, `CLAUDE.md`, `Code-Review-Claude.md`, `Code-Review-Codex.md`, `tests/`, `hooks/` and a `.pre-commit-config.yaml`. Whether a pre-1.0 tag train is a risk or simply a moving target depends on your own tolerance for pinned upgrades.

Editorial conclusion

Use Ouroboros when your team keeps losing work to under-specified agent tasks and you accept that the loop withholds the verify command from the worker on purpose. Skip it if you need a settled 1.0 command surface, if you cannot run Python 3.12 or newer, or if your runtime is one of the seven hosts with no documented configuration key. Before committing, read TELEMETRY.md, decide whether the seed fixtures in `examples/` are enough for your own seeds, and confirm the `ooo` commands you need exist in the version you pin.

Frequently asked questions

Official sources

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