ouroboros

<!-- mcp-name: io.github.Q00/ouroboros --> <p align="right"> <strong>English</strong> | <a href="./README.ko.md">한국어</a> | <a href="./README.zh-CN.md">简体中文</a> </p> <p align="center"> <br/> ◯ ─────────── ◯ <br/><br/> <img src="./docs/images/ouroboros.png" width="420" alt="Ouroboros"> <br/><br/> <strong>O U R O B O R O S</strong> <br/><br/> ◯ ─────────── ◯ <br/> </p> <p align="center"> <strong>It gets smarter on its own. We just hold the line.</strong> <br/> _{Skip the prompt engineering. The agent runs, fails, and gets smarter every generation. The grading command and expected result never make it into the success contract we hand it.} <br/> _{The <strong>Agent OS</strong> for replayable AI coding workflows} </p> <p align="center"> <a href="https://github.com/Q00/ouroboros"><img src="https://img.shields.io/github/stars/Q00/ouroboros?color=yellow&logo=github&label=stars" alt="GitHub stars"></a> <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a> <a href="https://github.com/Q00/ouroboros/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/Q00/ouroboros/test.yml?branch=main" alt="Tests"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a> <a href="https://github.com/sponsors/Q00"><img src="https://img.shields.io/github/sponsors/Q00?logo=githubsponsors&color=EA4AAA&label=sponsors" alt="GitHub Sponsors"></a> </p> <p align="center"> <a href="https://trendshift.io/repositories/26008?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-26008" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26008" alt="Q00%2Fouroboros | Trendshift" width="250" height="55"/></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> · <a href="#why-ouroboros">Why</a> · <a href="#what-you-get">Results</a> · <a href="#the-loop">How It Works</a> · <a href="#commands">Commands</a> · <a href="#from-wonder-to-ontology">Philosophy</a> · <a href="https://ouroboros.page/learn/en/">Guide</a> </p>

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

# Windows (PowerShell) — no Python needed; installs Git and uv for you
irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

<p align="center">_{One command installs it. Then run <code>ooo setup</code> once inside your coding agent — details in <a href="#quick-start">Quick Start</a>.}</p> <p align="center">_{<b>Separate runs, separate hosts. Different tasks on purpose — the engine is what is shared, not the prompt</b>}</p> <table align="center"> <tr> <td align="center" width="33%"><img src="./docs/images/ooo-interview.gif" width="300" alt="Terminal recording of the ouroboros CLI interview reporting an ambiguity score"><br>_{<b>Terminal CLI</b> — a task-management CLI: <code>ouroboros init start</code> asking about ordering and scope, then reporting an ambiguity score}</td> <td align="center" width="33%"><img src="./docs/images/host-codex.gif" width="300" alt="Screen recording of the ChatGPT app calling Ouroboros as an integration"><br>_{<b>ChatGPT (Codex)</b> — called as an integration, on a video-publishing harness: the interview, its advisory lanes, and the ambiguity ledger}</td> <td align="center" width="33%"><img src="./docs/images/host-claude.gif" width="300" alt="Screen recording of Claude Code running six Ouroboros interview advisory lanes in parallel"><br>_{<b>Claude Code</b> — a YouTube automation task, with the six advisory lanes running in parallel before the interview submits}</td> </tr> <tr> <td align="center" width="33%"><img src="./docs/images/host-hermes.gif" width="300" alt="Screen recording of a Discord bot running the Ouroboros interview and reporting a final ambiguity of 0.15"><br>_{<b>Hermes (Discord)</b> — a kart-racing game, run as a chat bot, ending at <code>Final ambiguity: 0.15</code>}</td> <td align="center" width="33%"><img src="./docs/images/host-dsh.gif" width="300" alt="Screen recording of DeepSeek Harness calling the Ouroboros interview tool and submitting advisory fan-out results"><br>_{<b>DeepSeek Harness</b> — an OSS-trend outreach script, driven from a dsh chat: <code>mcp__ouroboros__ouroboros_interview</code> turn by turn, fan-out results submitted between rounds}</td> <td align="center" width="33%"><img src="./docs/images/host-kiro.gif" width="300" alt="10x screen recording of Kiro CLI running an Ouroboros interview"><br>_{<b>Kiro</b> — the Kiro CLI running the Ouroboros interview flow, turning a vague request into a structured, testable Seed}</td> </tr> </table>

Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, OMP, Zcode, Goose, GJC, Antigravity, and Grok.

Ouroboros is an Agent OS for AI coding: a local-first runtime layer that turns non-deterministic agent work into a replayable, observable, policy-bound execution contract. It replaces ad-hoc prompting with a structured specification-first workflow: interview, crystallize, execute, evaluate, evolve.

---

The Ouroboros Agent OS Stack

Like any OS, Ouroboros is split into a stable OS layer of primitives, an application layer of domain workflows, and a shell that humans actually sit in front of. Three repos, one stack:

| Layer | Repo | Role | What it gives you | | :--- | :--- | :--- | :--- | | Shell (terminal client) | Ouro-labs/ourocode | Native terminal UI for running ooo workflows across Claude / Codex / Gemini CLIs in one session | TUI, wonderTool decision pickers, MCP pane state, command discovery | | Apps (domain workflows) | Ouro-labs/ouroboros-plugins | UserLevel plugin contract — composes core primitives into installable domain programs (PR ops, Jira sync, incidents, releases) | Plugin manifest, scoped permissions, audit/provenance, reference plugins | | OS (this repo) | Q00/ouroboros | Agent OS core — Seed, Ledger, Runtime, MCP, safety boundaries | ooo commands, spec-first workflow engine, multi-runtime adapter |

How they connect:

  ourocode  ──►  ooo / ouroboros-plugins  ──►  ouroboros core (Seed · Ledger · MCP · Runtime)
   shell             user-level apps                        kernel

• The kernel (ouroboros) owns the contract: every action becomes a Seed-bound, ledger-recorded, replayable event — regardless of which LLM executes it.
• Plugins (ouroboros-plugins) declare scoped capabilities against that contract, so domain workflows (review a PR, triage a Linear ticket, run a release) stay auditable and policy-bound instead of being one-off prompts.
• Ourocode is the terminal shell: it surfaces MCP state, interview questions, and wonderTool decisions as first-class TUI elements, so you can drive the OS without leaving the keyboard or switching between CLIs.

Use ouroboros alone with any supported CLI, layer plugins on for domain workflows, or install ourocode when you want a unified terminal cockpit.

Disclaimer. The Ouroboros project and community are not affiliated with any cryptocurrency, token, memecoin, or trading community — including, but not limited to, any "ouroboros" tickers on pump.fun or other launchpads. This is an open-source developer tool. We do not issue, endorse, or hold any coins. Any token claiming association with this project is unauthorized.

Naming note. A separate, unaffiliated open-source project also uses the name "Ouroboros" — Anton Razzhigaev's self-modifying, autonomous-memory agent at github.com/razzant/ouroboros. No shared code, no relationship. This project locks a specification before executing rather than rewriting its own architecture; if you're looking for the latter, that's the other one.

---

Why Ouroboros?

Most AI coding fails at the input, not the output. The bottleneck is not AI capability -- it is human clarity.

| Problem | What Happens | Ouroboros Fix | | :------------ | :------------------------------- | :-------------------------------------------- | | Vague prompts | AI guesses, you rework | Socratic interview exposes hidden assumptions | | No spec | Architecture drifts mid-build | Immutable seed spec locks intent before code | | Manual QA | "Looks good" is not verification | 3-stage automated evaluation gate |

---

Quick Start

Install — one command, everything auto-detected:

# macOS / Linux / WSL 2
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash

# Windows (PowerShell 5.1+ or pwsh 7+) — nothing to install first
irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

The Windows installer installs Git and uv through winget when they are missing, lets uv download its own Python, then installs ouroboros-ai and wires the host it finds. Native Windows is experimental and Codex CLI needs WSL 2; see platform support.

First command — open your AI coding agent and run these in order:

> ooo setup
> ooo interview "I want to build a task management CLI"

ooo setup is a one-time configuration step. ooo interview is the first workflow command and starts the Socratic interview. After setup, Codex follows its currently selected model and Claude Code starts with its recommended model settings. Choose Directly configure models only when you want to pin a stage to a specific model; it opens the local settings screen in your browser. You can return to those settings any time with ooo config.

Or from a plain terminal, without an agent host:

$ ouroboros init start --orchestrator "I want to build a task management CLI tool"

<p align="center"> _{That recording is this exact command. It is at the top of this page so you can see the tool before installing it.} </p> <p align="center"> <img src="./docs/images/ooo-setup-refresh.gif" width="760" alt="Terminal recording of ouroboros setup refresh installing Codex rules and skills, Hermes skills, the OpenCode plugin and instruction guide, and the Pi and GJC bridges, ending with the line Refreshed runtime artifacts: codex, hermes, opencode, pi, gjc"> </p> <p align="center"> _{<code>ouroboros setup refresh</code> on one machine. It installs into the hosts that machine actually has, each in the shape that host expects: rules and skills for Codex, skills for Hermes, a plugin and an <code>AGENTS.md</code> for OpenCode, bridges for Pi and GJC. Your machine will show whichever of the thirteen you have installed.} </p>

Works with 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. For explicit selection, run ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi|omp|zcode|goose|gjc|antigravity|grok> after installation. Copilot live-discovers its subscription catalog via the GitHub Copilot models API; Kiro's settings picker queries the authenticated CLI with kiro-cli chat --listmodels -f json, so account and enterprise allow-list changes appear without a hardcoded model table.

DeepSeek support. Ouroboros speaks DeepSeek two ways. Point the interview/Seed/QA pipeline at DeepSeek's own models with `-