Ouroboros: An Agent OS That Refuses to Hand the Agent Its Own Grading Key

The Problem Ouroboros Picks: Agents That Grade Their Own Homework

Most agent failures are not model failures. They are specification failures. A developer types a paragraph, the agent produces something plausible, and the mismatch only surfaces at review. The README frames the fix in one line: the agent runs, fails, and gets smarter every generation, while the grading command and expected result never make it into the success contract handed to it. That is the core design claim. The agent is told what done looks like at the level of observable behaviour, not at the level of the test that will judge it. Whoever wrote the task holds the acceptance criteria separately. This is aimed at developers running long, multi-step coding workflows through a CLI agent, where a wrong assumption early compounds across many tool calls. It is not aimed at autocomplete, and it is not aimed at a single file edit. The target user is someone who already has a host agent installed and wants the loop around it to be structured rather than improvised.

Interview, Crystallize, Execute, Evaluate, Evolve: The Five-Stage Loop

The README names the workflow stages directly: interview, crystallize, execute, evaluate, evolve. The interview is the gate. The repository's terminal recording shows `ouroboros init start` asking about ordering and scope, then reporting an ambiguity score. The Discord bot example ends at `Final ambiguity: 0.15`, which tells you the score is a number the interview drives down rather than a boolean pass. The Claude Code recording describes six advisory lanes running in parallel before the interview submits, and the DeepSeek Harness example shows fan-out results submitted between rounds through `mcp__ouroboros__ouroboros_interview`. So the interview is not a fixed questionnaire. It is a loop with a numeric stopping condition, and hosts can fan out sub-questions in parallel and feed answers back. Crystallize turns the settled answers into what the project calls a Seed. Execute runs against that Seed. Evaluate checks the result. Evolve feeds the outcome back so the next generation starts from a better position. The README describes the kernel as owning the contract: every action becomes a Seed-bound, ledger-recorded, replayable event, regardless of which LLM executes it. That is the architectural bet. The model is swappable; the Seed and the ledger are not.

Three Repos, One Stack: Shell, Apps, Kernel

Ouroboros is not a single repository pretending to be a platform. The README lays out three layers. The kernel is `Q00/ouroboros`, the repo under review, holding Seed, Ledger, Runtime, MCP and the safety boundaries. The application layer is `Ouro-labs/ouroboros-plugins`, which the README describes as a user-level plugin contract that composes core primitives into installable domain programs for things like PR operations, Jira sync, incidents and releases, with a plugin manifest, scoped permissions and audit provenance. The shell is `Ouro-labs/ourocode`, a native terminal UI for running `ooo` workflows across Claude, Codex and Gemini CLIs in one session, with decision pickers, an MCP pane and command discovery. The data flow is drawn as shell to apps to kernel. This split has a practical consequence worth stating plainly: installing this repository gives you the kernel and the `ooo` command surface, not the terminal UI and not the domain plugins. If you want the TUI, that is a separate install from a separate organisation. The README does not describe a versioning contract between the three layers, so how tightly a kernel upgrade is coupled to a plugin release is not something the supplied material answers.

Getting It Running: One Installer, One Setup Command, Then the Interview

The install path is a single command per platform. On macOS, Linux or WSL 2, the README gives `curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme-hero bash`. On Windows PowerShell, `irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex`, and the README notes that this path needs no Python because it installs Git and uv for you. The `OUROBOROS_INSTALL_REF` variable in the shell example is set to `readme-hero`, which suggests the installer accepts a ref to pin which revision it pulls. After installation, the README says to run `ooo setup` once inside your coding agent. Then the workflow commands begin, with `ouroboros init start` shown in the terminal recording and `ooo` as the command prefix throughout. The package is published on PyPI as `ouroboros-ai`, so a Python-level install is available alongside the shell installer. Two things the README does not spell out: which Python version the core requires, and what `ooo setup` writes or where. Both are worth checking against the repository before you roll this onto a shared machine.

Fourteen Runtimes and an MCP Server: What the Adapter Layer Actually Buys

The README lists Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, OMP, Zcode, Goose, GJC, Antigravity and Grok. That is fourteen hosts, and the MCP server is the mechanism that makes one workflow engine reach all of them. The DeepSeek Harness recording shows the tool being called as `mcp__ouroboros__ouroboros_interview`, turn by turn, which is the standard MCP tool-naming shape. The pitch in the README is explicit that the engine is what is shared, not the prompt: separate runs, separate hosts, different tasks on purpose. That is the right framing, because the value of a fourteen-host adapter is portability of the contract, not portability of any particular prompt. The honest caveat is that adapter breadth and adapter depth are different things. The recordings cover Claude Code, Codex, Hermes, DeepSeek Harness and Kiro. The other nine are named but not demonstrated in the supplied material, and the README does not describe how much of the loop each host supports. Treat the list as a compatibility claim to test per host, not as fourteen equally verified integrations.

Where the Design Bites: Ambiguity Scores, Interview Overhead, and a Missing Grading Contract

The interview gate is the most opinionated choice here and the most likely to annoy you. A numeric ambiguity threshold means the loop keeps asking until the score drops, and the README does not state what the default threshold is or how the score is computed. A task you could have described adequately in two sentences now costs a round of questions, and on a trivial edit that overhead exceeds the work. The second limitation is structural. Withholding the grading command and expected result from the success contract is a good idea for preventing the agent from optimising against the test. It also means the agent has less information to self-correct with, so the evaluate stage carries more weight and a poorly written Seed produces a confidently wrong result that passes the interview. Nothing in the supplied material describes what happens when the interview cannot converge, whether you can force-submit below the threshold, or how the ledger handles a run that was abandoned mid-interview. Those are the failure modes to probe. Finally, the safety boundaries are named in the stack table but not described in the README excerpt, so the scope of what the runtime will refuse to do is unverified here.

Against Plain Agent Sessions and Against Eval Harnesses

The obvious alternative is the thing you are already doing: open Claude Code or Codex CLI and type the task. That approach has no interview, no Seed, no ledger, and no replay. It is faster for anything you can specify in one message, and it is the correct choice for exploratory work where you do not yet know what done means. Ouroboros trades that speed for a recorded contract, and the trade only pays off when the task is long enough that a mid-run correction is expensive. A second alternative is a dedicated LLM evaluation framework, and the difference in approach is sharper. An eval harness scores a model or a prompt against a fixed dataset, offline, with the dataset and the scoring function both in the harness author's hands. Ouroboros scores a live agent run against a per-task Seed, online, with the grading command deliberately held outside the agent's view. One gives you comparable numbers across model versions. The other gives you a replayable record of a single piece of work. If your question is which model is better at a task class, an eval harness answers it and Ouroboros does not. If your question is whether last Tuesday's run can be reproduced and audited, the reverse holds.

Release Cadence, Licence, and What Upgrading Costs You

The release history shows 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 at version 0.54.x tells you the project is pre-1.0 and moving quickly, and that patch-level upgrades arrive often enough to matter. The practical cost is not the upgrade command, which is the same installer or a PyPI install; it is the Seed and ledger format. The README does not state a compatibility guarantee for stored Seeds or ledger entries across versions, and nothing in the supplied material describes a migration path. If you build workflows that depend on replaying old runs, pin your version and test an upgrade against a recorded Seed before rolling it out. The licence is MIT, which permits commercial and closed-source use and requires preserving the copyright notice and licence text in distributions. That is a permissive baseline, but if you ship Ouroboros inside a product, read the actual LICENSE file rather than this summary; nothing here is legal advice. Note also that the shell and plugin repositories are separate projects under a different organisation, and their licences are not stated in the material provided.

Editorial conclusion

Adopt Ouroboros if you already run Claude Code, Codex CLI, Gemini CLI or one of the other listed hosts and you keep re-explaining the same task to a fresh agent session. Skip it if your tasks are one-shot edits where an interview round costs more than the work. Before committing, verify three things: that `ooo setup` completes against your host, that the Seed the interview produces actually encodes your acceptance criteria, and that the Node.js and Python prerequisites the installer bootstraps are versions you can support on your machines.

Official sources

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