Ouroboros

English | 한국어 | 简体中文

◯ ─────────── ◯

[Ouroboros]

O U R O B O R O S

◯ ─────────── ◯

It gets smarter on its own. We just hold the line.
_{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.
The Agent OS for replayable AI coding workflows}

[GitHub stars] [PyPI] [Tests] [License] [GitHub Sponsors]

[Q00%2Fouroboros | Trendshift]

Quick Start · Why · Results · How It Works · Commands · Philosophy · Guide

# macOS / Linux / WSL 2curl -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 youirm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

_{One command installs it. Then run ooo setup once inside your coding agent — details in Quick Start.}

Demo videos for each runtime.

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:

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.

Quick Start

Install — one command, everything auto-detected:

# macOS / Linux / WSL 2curl -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 firstirm 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"

_{That recording is this exact command. It is at the top of this page so you can see the tool before installing it.}

[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]

_{ouroboros setup refresh 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 AGENTS.md for OpenCode, bridges for Pi and GJC. Your machine will show whichever of the thirteen you have installed.}

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 --llm-backend dsh (ouroboros mcp serve --runtime claude-cli --llm-backend dsh, or OUROBOROS_LLM_BACKEND=dsh) — this drives DeepSeek Harness's ACP server under the hood. Or go the other way: install the dsh-ouroboros plugin (dsh plugin --profile <your-profile> add "github:Q00/ouroboros#main&path:integrations/dsh-plugin") and type ooo interview / ooo auto directly in the DeepSeek Harness chat — the same ouroboros_interview / ouroboros_auto tools run natively inside it, Socratic questions and all. Both directions, including what the dsh backend needs beyond the one variable, are in the DeepSeek Harness guide.

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

ooo setupooo interview "Build a task management CLI"

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)

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

ouroboros config set orchestrator.copilot_transport acp

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

pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli  # recommended MCP v2 defaultpip install 'ouroboros-ai[claude]'      # Claude Agent SDK profile (MCP 1.x, isolated)pip install 'ouroboros-ai[claude-cli]'  # dependency-free Claude CLI workerpip install 'ouroboros-ai[claude-sdk]'  # explicit alias for the Claude SDK profilepip install 'ouroboros-ai[litellm]'     # + LiteLLM multi-provider; Python 3.12-3.13pip install 'ouroboros-ai[mcp]'         # MCP v2 server/client without the GUIpip install 'ouroboros-ai[tui]'         # settings GUI onlypip install 'ouroboros-ai[all]'         # MCP 1.x app bundle; excludes MCP 2 by designouroboros setup                         # configure runtime

brew tap q00/tapbrew install ouroboros-aiouroboros setup                         # configure runtime

ouroboros uninstall

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

Installing as an MCP server: use 0.51.1 or later. Earlier versions can fail at startup with Failed to reconnect to plugin:ouroboros:ouroboros: -32000 when an existing environment shadows the [mcp] profile (#2012). This matters if you install through a downstream package rather than PyPI, since those can lag.

_{Most people find out they were unclear about three files into the review.
If that feels familiar, star Q00/ouroboros on GitHub so the next person it could save can find it.}

What You Get

After one loop of the Ouroboros cycle, a vague idea becomes a verified codebase:

interview  ->  Socratic questioning exposed 12 hidden assumptionsseed       ->  Crystallized answers into an immutable spec (Ambiguity: 0.15)run        ->  Fanned acceptance criteria out to agents in dependency orderevaluate   ->  3-stage verification: Mechanical -> Semantic -> Consensus

How It Compares

AI coding tools are powerful -- but they solve the wrong problem when the input is unclear.

The Loop

The ouroboros -- a serpent devouring its own tail -- is not decoration. It IS the architecture:

    Interview -> Seed -> Execute -> Evaluate        ^                           |        +---- Evolutionary Loop ----+

Each cycle does not repeat -- it evolves. The output of evaluation feeds back as input for the next generation, until the system truly knows what it is building.

"This is where the Ouroboros eats its tail: the output of evaluation becomes the input for the next generation's seed specification." -- reflect.py

Convergence is reached when ontology similarity >= 0.95 -- when the system has questioned itself into clarity.

Ralph: The Loop That Never Stops

ooo ralph runs the evolutionary loop persistently -- across session boundaries -- until convergence is reached. Each step is stateless: the EventStore reconstructs the full lineage, so even if your machine restarts, the serpent picks up where it left off.

Ralph Cycle 1: evolve_step(lineage, seed) -> Gen 1 -> action=CONTINUERalph Cycle 2: evolve_step(lineage)       -> Gen 2 -> action=CONTINUERalph Cycle 3: evolve_step(lineage)       -> Gen 3 -> action=CONVERGED                                                +-- Ralph stops.                                                    The ontology has stabilized.

Commands

Inside AI coding agent sessions, use ooo <cmd> skills. From the terminal, use the ouroboros CLI.

ooo idk adjusts interview wording in the active conversation without answering the pending question or lowering requirements rigor. It works with the Claude skill relay and intercepted interviews on Codex, Copilot, Gemini, OpenCode, Hermes, Pi, OMP, GJC, and Kiro. Calibration is not saved: run ooo idk again after reopening a saved session. See the calibration contract.

Not all skills have direct CLI equivalents. Some (evaluate, evolve, unstuck, ralph, publish) are available through agent skills, runtime rules, or MCP tools rather than a direct ouroboros <subcommand> shell command. /resume is reserved for Claude Code's built-in session picker; use ooo resume-session for Ouroboros in-flight sessions. Claude Code also reserves /run, /status, /help, and /config. The safe direct skill forms are /ouroboros:ouroboros-run, /ouroboros:ouroboros-status, /ouroboros:ouroboros-help, and /ouroboros:ouroboros-config; the familiar ooo run, ooo status, ooo help, and ooo config phrases remain supported.

See the CLI reference for full details.

The Nine Minds

Nine highlighted agents below, with 12 more specialized agents available (21 total). All loaded on-demand, never preloaded:

Under the Hood

src/ouroboros/+-- bigbang/        Interview, ambiguity scoring, brownfield explorer+-- router/         Skill dispatch (`ooo <skill>` -> MCP tool); PAL tier routing is in orchestrator/+-- execution/      (deprecated — logic moved to orchestrator/ and mcp/tools/)+-- evaluation/     Mechanical -> Semantic -> Multi-Model Consensus+-- evolution/      Wonder / Reflect cycle, convergence detection+-- resilience/     4-pattern stagnation detection, 5 lateral personas+-- observability/  3-component drift measurement, auto-retrospective+-- persistence/    Event sourcing (SQLAlchemy + aiosqlite), checkpoints+-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, OMP, GJC, Goose, Antigravity, Grok, Zcode)+-- core/           Types, errors, seed, ontology, security+-- providers/      LiteLLM adapter (100+ models)+-- mcp/            MCP client/server integration+-- plugin/         Plugin system (skill/agent auto-discovery)+-- tui/            Terminal UI dashboard+-- cli/            Typer-based CLI

From Wonder to Ontology

   Wonder                          Ontology"What do I want?"    ->    "What IS the thing I want?""Build a task CLI"   ->    "What IS a task? What IS priority?""Fix the auth bug"   ->    "Is this the root cause, or a symptom?"

    * Wonder          * Design   /  (diverge)      /  (diverge)  /    explore      /    create /                 /* ------------ * ------------ * \                 \  \    define       \    deliver   \  (converge)     \  (converge)    * Ontology        * Evaluation

Ambiguity = 1 - Sum(clarity_i * weight_i)

Example (Greenfield):
  Goal: 0.9 * 0.4  = 0.36  Constraint: 0.8 * 0.3  = 0.24  Success: 0.7 * 0.3  = 0.21                        ------  Clarity             = 0.81  Ambiguity = 1 - 0.81 = 0.19  <= 0.2 -> Ready for Seed

Similarity = 0.5 * name_overlap + 0.3 * type_match + 0.2 * exact_match

Gen 1: {Task, Priority, Status}Gen 2: {Task, Priority, Status, DueDate}     -> similarity 0.78 -> CONTINUEGen 3: {Task, Priority, Status, DueDate}     -> similarity 1.00 -> CONVERGED

Contributing

git clone https://github.com/Q00/ouroboroscd ouroborosuv sync --python 3.13 --all-groupsuv run --python 3.13 --no-sync pytest

Issues · Discussions · Contributing Guide

Sponsors

Ouroboros is MIT-licensed and built in the open. If it saves you rework — or you want the loop to keep evolving — consider sponsoring. Sponsorship directly funds maintenance, new runtime integrations, and sponsor-only deep-dive content.

[Sponsor Q00 on GitHub]

Every sponsor keeps the serpent evolving. Thank you.

Activity

These numbers are generated from GitHub data and refreshed automatically; caching may delay updates.

[Contributors] [Commit activity] [Closed pull requests] [Last commit]

"The beginning is the end, and the end is the beginning."

The serpent does not repeat -- it evolves.

MIT License