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="520" alt="Ouroboros"> <br/><br/> <strong>O U R O B O R O S</strong> <br/><br/> ◯ ─────────── ◯ <br/> </p> <p align="center"> <strong>Stop prompting. Start specifying.</strong> <br/> _{The <strong>Agent OS</strong> for replayable, specification-first AI coding workflows} </p> <p align="center"> <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> </p>

Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, 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) | Q00/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) | Q00/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.

---

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:

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

First use — open your AI coding agent and type:

> ooo

If a one-time setup is needed, Ouroboros asks before it makes changes. 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.

Build — then go:

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

Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi 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|zcode|goose|gjc|antigravity|grok> after installation. The Copilot CLI runtime live-discovers its model catalog via the GitHub Copilot models API and lets you pick a default during setup.

<details> <summary><strong>Codex plugin quick start</strong></summary>

codex plugin marketplace add Q00/ouroboros
codex plugin add ouroboros@ouroboros

Start a new Codex session, then enter ooo. On first use, Ouroboros offers to prepare the runtime before it changes anything. Once ready, it follows Codex's current default model; choose Directly configure models only when you want to pin a specific model for a pipeline stage.

</details> <details> <summary><strong>Kiro CLI quick start</strong></summary>

pipx install 'ouroboros-ai[mcp]'       # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime kiro         # detects Kiro CLI, registers MCP server, and
                                        # writes OUROBOROS_RUNTIME=kiro into
                                        # ~/.kiro/settings/mcp.json (the trusted,
                                        # setup-managed location -- a project .env
                                        # is untrusted input and this key is ignored there)

Then use ooo commands inside a Kiro CLI session.

</details> <details> <summary><strong>GitHub Copilot CLI quick start</strong></summary>

gh auth login                                # one-time GitHub auth (used for live model discovery)
pipx install 'ouroboros-ai[mcp]'             # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot            # discovers models live, picks a default,
                                             # registers MCP server in ~/.copilot/mcp-config.json

Restart your Copilot CLI session, then use ooo commands inside it. Hyphenated Anthropic model IDs (claude-opus-4-6) used elsewhere in your config are auto-mapped to the dotted Copilot form (claude-opus-4.6) at runtime, so existing configs keep working when you switch backends.

See the GitHub Copilot CLI runtime guide for full details.

</details> <details> <summary><strong>Other install methods</strong></summary>

Claude Code plugin only (no system package):

claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

Then run ooo setup inside a Claude Code session.

pip / uv / pipx:

pip install ouroboros-ai                # base
pip install 'ouroboros-ai[claude]'        # + default Claude Agent SDK profile (MCP 1.x)
pip install 'ouroboros-ai[claude-cli]'    # + dependency-free Claude CLI worker profile
pip install 'ouroboros-ai[claude-sdk]'    # + explicit alias for the Claude SDK profile
pip install 'ouroboros-ai[litellm]'       # + LiteLLM multi-provider; Python 3.12-3.13
pip install 'ouroboros-ai[mcp]'           # + MCP server/client support
pip install 'ouroboros-ai[tui]'           # + Textual terminal UI
pip install 'ouroboros-ai[all]'           # MCP 1.x app bundle; excludes the MCP 2 server
ouroboros setup                         # configure runtime

Core and non-LiteLLM installs support Python 3.12-3.14. LiteLLM-bearing installs ([litellm], [all], and source --extra all) support Python 3.12-3.13; use Python 3.13 for current examples. See Platform Support.

[claude] preserves the in-process Agent SDK and its MCP 1.x dependency graph; [claude-sdk] is its explicit alias. The MCP 2 server runs from a separate [mcp] environment and selects the [claude-cli] subprocess worker when Claude is the host. Never install [mcp,claude], [mcp,claude-sdk], or [all,mcp] in one interpreter. See the package compatibility and migration matrix.

pip install 'ouroboros-ai[mcp]' is valid for embedding the MCP client/server library in an already isolated Python environment, but host registration requires uvx or pipx. Use pipx install 'ouroboros-ai[mcp]' or uv tool install 'ouroboros-ai[mcp]' before ouroboros setup --runtime <kiro|copilot|hermes>; setup exits without changing runtime configuration when neither isolated launcher is available.

Legacy compatibility: ouroboros-ai[dashboard] is still accepted as a compatibility alias/no-op; it does not install dashboard runtime payload. ouroboros-ai[all] includes that no-op alias only for compatibility.

See runtime guides: Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Zcode · Pi JSON mode · Goose · GJC · Antigravity CLI · Grok Build CLI

</details> <details> <summary><strong>Uninstall</strong></summary>

ouroboros uninstall

Removes all configuration, MCP registration, and data. See UNINSTALL.md for details.

</details>

Python >= 3.12 required. LiteLLM-bearing profiles support Python 3.12-3.13. See Platform Support and pyproject.toml.

---

What You Get

After one loop of the Ouroboros cycle, a vague idea be