Ouroboros

Ouroboros helps your AI coding agent build the right thing. It asks you questions until the goal is clear, writes the answer down as a spec with checkable acceptance criteria, hands that spec to the coding agent you already use, and then checks the result against the spec.

Install

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

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

When installation finishes, the Ouroboros console opens in your browser and walks you through connecting your agent tools. Reopen it any time with ouroboros gui.

The installer finds the agent tools you already have and connects Ouroboros to them. Native Windows is experimental, and Codex CLI needs WSL 2; see platform support.

Other ways to install. These don't open the console for you; run ouroboros gui once the ouroboros command is installed.

# Claude Code plugin only (then run /ouroboros:setup inside Claude Code)
claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

# pip / uv / pipx (Python 3.12+)
pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli

# Homebrew (macOS / Linux)
brew tap q00/tap && brew install ouroboros-ai && ouroboros setup

Every install path, profile and host is in Getting Started. ouroboros uninstall removes Ouroboros's configuration, MCP registrations and data directory (~/.ouroboros/). It leaves the Python package and the Claude Code plugin installed; finish with the steps in UNINSTALL.md.

First steps

Describe what you want in plain words. Four good places to start:

• Console Chat: type a goal and pick Interview (it asks until the goal is clear) or Auto (it fills the gaps itself), then hand the spec to your agents and watch the run.
• ooo interview "a todo CLI with due dates" in your agent: questions until the goal is clear, then a spec (a Seed).
• ooo auto "a todo CLI with due dates": asks only what is missing, writes the spec, runs it, and checks it.
• ooo run: builds an existing Seed and checks every acceptance criterion.

In Claude Code, run /ouroboros:setup once and finish its questions, then send your first ooo command as a separate message. From a plain terminal, ouroboros init start "..." and ouroboros auto "..." do the same without an agent host. The full command list is in Getting Started.

Ouroboros runs coding agents that can change files and run commands in your project. Read permission scope before using it on a project you don't trust.

Works with

Claude Code · Codex CLI · GitHub Copilot CLI · OpenCode · Hermes · Gemini CLI · Kiro CLI · Pi · OMP · Zcode · Goose · GJC · Antigravity CLI · Grok Build CLI · DeepSeek Harness

The installer connects the ones you have; the console's Connect page installs and connects the rest. Want to see it first? Watch the interview run on seven different hosts.

Learn more

• Getting Started: every install path, host-by-host setup, your first workflow, and all commands.
• Console guide: what each console page does, the shared MCP server, and starting the console at login.
• How Ouroboros works: the loop, the agents, the ambiguity gate, the Agent OS stack, architecture, and philosophy.
• CLI reference · Configuration · Platform support · All docs
• Interactive guide

Contributing

git clone https://github.com/Q00/ouroboros
cd ouroboros
uv sync --python 3.13 --all-groups
uv 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, consider sponsoring: it funds maintenance, new runtime integrations, and sponsor-only deep-dive content.

Activity

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

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.

---