ouroboros

Needs codex on your PATH and uvx on the host (the plugin’s MCP descriptor launches the server with it). Install uv with pipx install uv, pip install --user uv, or brew install uv.

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

Start a new Codex session, then run these commands in order:

ooo setup
ooo interview "Build a task management CLI"

ooo setup is the one-time runtime preparation. Once ready, Ouroboros follows Codex’s current default model; choose Directly configure models only when you want to pin a specific model for a pipeline stage.

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.

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. Model-ID mapping is catalog-gated: the prior direct and OpenRouter Opus 5 pins resolve to claude-opus-5 when that ID is present; current Anthropic API pins convert only their trailing numeric separator and only when the discovered catalog contains the exact candidate. Unknown IDs remain unchanged so Copilot reports an explicit unavailable-model error instead of silently selecting a different model. Leave role models unset so setup writes a discovered ID, or set a Copilot-valid ID explicitly. See the Copilot runtime guide.

See the GitHub Copilot CLI runtime guide for full details.

For experimental live task activity, keep runtime_backend: copilot and opt into the ACP transport:

ouroboros config set orchestrator.copilot_transport acp

The default remains cli (copilot -p). ACP streams assistant text and tool progress through the existing event store; authentication is still owned by Copilot, and no TCP listener or display is required.

Claude Code plugin only (no Python package or global Python to install; the host needs uv, which provides both uvx for the MCP server and the skills’ Python >= 3.12 fallback):

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[mcp,tui]' && ouroboros setup --runtime claude-cli  # recommended MCP v2 default
pip install 'ouroboros-ai[claude]'      # Claude Agent SDK profile (MCP 1.x, isolated)
pip install 'ouroboros-ai[claude-cli]'  # dependency-free Claude CLI worker
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 v2 server/client without the GUI
pip install 'ouroboros-ai[tui]'         # settings GUI only
pip install 'ouroboros-ai[all]'         # MCP 1.x app bundle; excludes MCP 2 by design
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.

The recommended standalone installation is ouroboros-ai[mcp,tui] followed by an explicit MCP v2-compatible runtime selection. The example uses --runtime claude-cli; substitute another compatible runtime such as codex, opencode, hermes, gemini, goose, kiro, copilot, pi, or gjc. Use [claude] and [claude-sdk] only in isolated MCP 1.x environments.

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 --isolated --python '>=3.12' or pipx. Use pipx install 'ouroboros-ai[mcp]' or uv tool install 'ouroboros-ai[mcp]' before ouroboros setup --runtime <claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc>; 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.

Homebrew (macOS/Linux):

brew tap q00/tap
brew install ouroboros-ai
ouroboros setup                         # configure runtime

Self-hosted tap, not yet in homebrew-core. Installs the same package published to PyPI.

See runtime guides: Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Zcode · Pi JSON mode · OMP (Oh My Pi) · Goose · GJC · Antigravity CLI · Grok Build CLI · Megacode harness

ouroboros uninstall

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

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

Use ooo <cmd> inside your AI coding agent session, or ouroboros init start, ouroboros run seed.yaml, etc. from the terminal.

The serpent completed one loop. Each loop, it knows more than the last.

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

Key internals:

• PAL Router – Frugal (1x) -> Standard (10x) -> Frontier (30x) with escalation on retry (no automatic downgrade)
• Drift – Goal (50%) + Constraint (30%) + Ontology (20%) weighted measurement, threshold <= 0.3
• Brownfield – Auto-detects config files across multiple language ecosystems
• Evolution – Up to 30 generations, convergence at ontology similarity >= 0.95
• Stagnation – Detects spinning, oscillation, no-drift, and diminishing returns patterns
• Agent OS runtime – Replayable execution contract across capability discovery, policy, directives, event journal, and agent processes
• Runtime backends – Pluggable abstraction layer (orchestrator.runtime_backend config) with first-class support for every canonical backend returned by runtime_backend_choices(), including GJC, Antigravity, Grok, and Zcode; same workflow spec, different execution engines

See Architecture for the full design document.

Wonder -> “How should I live?” -> “What IS ‘live’?” -> Ontology – Socrates

Every great question leads to a deeper question – and that deeper question is always ontological: not “how do I do this?” but “what IS this, really?”

   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?"

This is not abstraction for its own sake. When you answer “What IS a task?” – deletable or archivable? solo or team? – you eliminate an entire class of rework. The ontological question is the most practical question.

Ouroboros embeds this into its architecture through the Double Diamond:

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

The first diamond is Socratic: diverge into questions, converge into ontological clarity. The second diamond is pragmatic: diverge into design options, converge into verified delivery. Each diamond requires the one before it – you cannot design what you have not understood.

The Interview does not end when you feel ready – it ends when the math says you are ready. Ouroboros quantifies ambiguity as the inverse of weighted clarity:

Ambiguity = 1 - Sum(clarity_i * weight_i)

Each dimension is scored 0.0-1.0 by the LLM (temperature 0.1 for reproducibility), then weighted:

Threshold: Ambiguity <= 0.2. A score above that blocks Seed generation. Passing force explicitly is what gets past it, and the CLI puts that choice on screen next to continue and cancel. The gate is a default worth arguing with, not a lock.

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

Why 0.2? Because at 80% weighted clarity, the remaining unknowns are small enough that code-level decisions can resolve them. Above that threshold, you are still guessing at architecture.

The evolutionary loop does not run forever. It stops when consecutive generations produce ontologically identical schemas. Similarity is measured as a weighted comparison of schema fields:

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

Threshold: Similarity >= 0.95 – the loop converges and stops evolving.

But raw similarity is not the only signal. The system also detects pathological patterns:

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

Two mathematical gates, one philosophy: do not build until you are clear (Ambiguity <= 0.2), do not stop evolving until you are stable (Similarity >= 0.95).