Name: ouroboros
Author: q00

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

Ouroboros

O U R O B O R O S

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

Stop prompting. Start specifying.
_{Agent OS for replayable, specification-first AI coding workflows}

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

Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, and Hermes.

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.

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

Build — open your AI coding agent and go:

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

Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, and Kiro CLI. The installer detects Claude Code, Codex CLI, and Hermes CLI automatically and registers the MCP server. For OpenCode, Kiro, or GitHub Copilot CLI, run ouroboros setup --runtime <opencode|kiro|copilot> 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.

Kiro CLI quick start

pip install 'ouroboros-ai[claude]'
ouroboros setup            # detects Kiro CLI and registers MCP server

Set runtime in .env:

OUROBOROS_RUNTIME=kiro

Then use ooo commands inside a Kiro CLI session.

GitHub Copilot CLI quick start

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.

Other install methods

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]        # + Claude Code deps
pip install ouroboros-ai[litellm]       # + LiteLLM multi-provider
pip install ouroboros-ai[mcp]           # + MCP server/client support
pip install ouroboros-ai[tui]           # + Textual terminal UI
pip install ouroboros-ai[all]           # everything (claude + litellm + mcp + tui + dashboard)
ouroboros setup                         # configure runtime

Help us improve

ouroboros

Component Overview

Component Details

Commands (13)

Skills (20)

Hooks (1)

MCP Servers (1)

README

Why Ouroboros?

Quick Start

Similar Plugins

tandemkit

Help us improve

helloagents

cwf

babysitter

flow

oac