Ouroboros
Ouroboros is an Agent OS for AI coding 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. It is for developers using AI coding agents like Claude Code, Codex CLI, and others who want to move from vague prompts to verified codebases.
✨ Key features
- Socratic interview to expose hidden assumptions
- Immutable seed spec locks intent before code
- 3-stage automated evaluation gate
- Multi-runtime adapter for 13+ AI coding CLIs
- Local-first runtime with ledger and MCP support
- Replayable, observable execution contract
🎯 Use cases
- Turn a vague idea into a structured, testable task
- Run AI coding workflows across multiple agent CLIs
- Automate video publishing with advisory lanes
- Build a task management CLI with verified output
- Create a kart-racing game as a chat bot
📦 Installation
🧰 Requirements: Requires Python 3.12-3.14 (or 3.13 for LiteLLM), a supported AI coding CLI (e.g., Claude Code, Codex), and optionally Git and uv on Windows.
# 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
Or via pip/uv/pipx:
pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli
🚀 Usage
# Inside your AI coding agent (e.g., Claude Code, Codex)
ooo setup
ooo interview "I want to build a task management CLI"
Or from a plain terminal:
ouroboros init start --orchestrator "I want to build a task management CLI tool"
⚠️ Good to know
Native Windows is experimental and Codex CLI needs WSL 2; LiteLLM installs support Python 3.12-3.13 only.
❓ FAQ
What is Ouroboros?
Ouroboros is an Agent OS for AI coding that provides a structured workflow (interview, crystallize, execute, evaluate, evolve) to turn vague ideas into verified codebases.
Which AI coding agents does it support?
It supports 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.
How do I install it?
Use the one-line install script for macOS/Linux/WSL or PowerShell for Windows, or install via pip/uv/pipx with the ouroboros-ai package.
What is the first command to run?
Run 'ooo setup' once to configure, then 'ooo interview' to start the Socratic interview for your task.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.