Skip to content

getting-started.md

Latest commit

 

History

History
594 lines (432 loc) · 24.2 KB

getting-started.md

File metadata and controls

594 lines (432 loc) · 24.2 KB
Raw

Getting Started with Ouroboros

Single source of truth for onboarding. All install and first-run instructions live here. Runtime-specific configuration lives in runtime guides. Architecture concepts live in architecture.md.

Transform a vague idea into a verified, working codebase -- with any AI coding agent.

Quick Start

Recommended: Claude Code (ooo)

You do not install Ouroboros with pip or install a global Python on this path. The host needs uv: its uvx command launches the plugin's MCP server (.claude-plugin/.mcp.json), and its uv command is the skills' final Python >= 3.12 fallback. Install uv with pipx install uv, pip install --user uv, or brew install uv.

The welcome, setup, and seed skills prefer a compatible python3, then a compatible python, and otherwise run with uv run --no-project --quiet --python '>=3.12' python. Older global interpreters are rejected instead of entering the first-run flow.

Then run the install commands in your terminal. Start Claude Code and follow the two commands below in order:

1. Install the plugin (in your terminal):

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

2. First command (inside a Claude Code session -- start one with claude):

ooo setup
ooo interview "Build a task management CLI"

ooo setup is a one-time runtime configuration. ooo interview is the first useful command: it starts the Socratic interview and returns a session that can be continued into Seed generation and execution.

For a one-command pipeline after setup, use:

ooo auto "Build a task management CLI"

ooo auto runs bounded Socratic interview rounds, generates an A-grade Seed, repairs B/C Seeds when possible, and starts execution only after the A-grade gate passes. It returns an auto_session_id so interrupted or blocked runs can be resumed.

Prefer the manual path when you want to answer every question yourself:

ooo interview "Build a task management CLI"
ooo run

ooo commands are Claude Code skills. They only work inside an active Claude Code session. ooo setup registers the MCP server globally (one-time) and optionally configures your project. After setup, choose Start now to use the recommended model settings, or Directly configure models to select a model for each pipeline stage. You can reopen those settings any time with ooo config.

Alternative: Standalone CLI (ouroboros)

Use this path if you prefer a standalone terminal workflow, or are using a non-Claude runtime (e.g., Codex CLI, OpenCode).

Requires Python >= 3.12.

# Install
pip install ouroboros-ai

# Set up the runtime once
ouroboros setup

# Start your first interview
ouroboros init start "Build a task management CLI"

After the interview produces a Seed, run it with:

ouroboros run ~/.ouroboros/seeds/seed_abc123.yaml

Codex first use

For the Codex plugin, add the marketplace and install Ouroboros. This needs codex on your PATH and uvx on the host — the plugin's MCP descriptor launches the server with it (.mcp.codex.json). Install uv with pipx install uv, pip install --user uv, or brew install uv; you do not need to install Python yourself.

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

Start a new Codex session and run these commands in order:

ooo setup
ooo interview "Build a task management CLI"

ooo setup is the one-time runtime preparation. Once prepared, Codex uses its current default model automatically. Choose Directly configure models only when you want to choose or pin a model for a pipeline stage; in Codex this opens the local settings UI in your browser at a temporary localhost address.

For a standalone Codex CLI installation without the plugin, prepare the integration once:

ouroboros setup --runtime codex
ouroboros init start "Build a task management CLI"

Note: The standalone CLI interview is invoked via ouroboros init start "your context" (not ooo interview, which is Claude Code-specific). The interview flow is identical across both tools. Power users can also author seed YAML files directly — see the Seed Authoring Guide.

Tip: ouroboros run requires a path to a seed YAML file as a positional argument (e.g., ouroboros run ~/.ouroboros/seeds/seed_<id>.yaml).

Auto mode: one-command A-grade pipeline

Use auto mode when you want the agentic pipeline to handle interview, Seed generation, quality gating, and execution handoff from one goal:

ooo auto "Build a local-first habit tracker CLI"

Useful variants:

ooo auto "Build a local-first habit tracker CLI" --skip-run
ooo auto --resume auto_abc123

When using the shell CLI directly, add --show-ledger to print the assumptions and non-goals captured during convergence:

ouroboros auto "Build a local-first habit tracker CLI" --show-ledger

Auto mode is hang-resistant by design: interview and repair loops are bounded, slow tool calls transition the auto session to blocked or failed, and execution handoff returns job/session IDs instead of waiting forever for completion. If auto mode stops, resume with the command printed by the surface you used: ooo auto --resume <auto_session_id> inside Claude Code, or ouroboros auto --resume <auto_session_id> from the standalone shell CLI.

Installation Details

Option 1: Claude Code Plugin (Recommended)

Requires uv on the host. Its uvx command launches the plugin's MCP server (.claude-plugin/.mcp.json), and its uv command provides Python >= 3.12 to bundled skills when no compatible global interpreter is available. Install uv with pipx install uv, pip install --user uv, or brew install uv.

# Terminal
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros

Then inside a Claude Code session:

ooo setup
ooo help        # verify installation

No pip install of Ouroboros and no API key configuration is needed -- Claude Code handles the runtime. uv is the only host prerequisite: it provides uvx for the MCP server and can provision Python >= 3.12 for shipped skill snippets. A compatible global python3 or python is only an optional fast path; when it is absent or too old, the skills use the uv-managed interpreter.

Option 2: pip Install

# Recommended standalone MCP v2 profile
pip install 'ouroboros-ai[mcp,tui]'
ouroboros setup --runtime claude-cli  # or another MCP v2-compatible runtime

# Alternative profiles
pip install 'ouroboros-ai[claude]'      # Claude Agent SDK (MCP 1.x, isolated)
pip install 'ouroboros-ai[claude-cli]'  # Claude CLI worker only
pip install 'ouroboros-ai[claude-sdk]'  # explicit alias for the SDK profile
pip install 'ouroboros-ai[litellm]'     # + LiteLLM; Python 3.12-3.13
pip install 'ouroboros-ai[mcp]'         # MCP v2 without the GUI
pip install 'ouroboros-ai[tui]'         # settings GUI only
pip install 'ouroboros-ai[all]'         # MCP 1.x app bundle; excludes MCP 2
ouroboros --version

Which profile do I need? The recommended standalone profile is ouroboros-ai[mcp,tui]. Select an MCP v2-compatible runtime explicitly, for example ouroboros setup --runtime claude-cli; use [claude] or [claude-sdk] only in an isolated MCP 1.x environment for the Agent SDK. Never combine the SDK profiles with [mcp] in one interpreter. For multi-model support via LiteLLM, use ouroboros-ai[litellm] or just grab everything with ouroboros-ai[all] from Python 3.12 or 3.13; examples prefer Python 3.13. Core and non-LiteLLM installs support Python 3.12-3.14. See the Python profile matrix. Legacy note: ouroboros-ai[dashboard] is still accepted as a compatibility alias/no-op and does not install dashboard runtime payload; [all] includes that no-op alias only for compatibility.

One-liner alternative (auto-detects your runtime and installs matching extras):

curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=docs-getting-started bash

Option 3: From Source (Contributors)

git clone https://github.com/Q00/ouroboros
cd ouroboros
uv sync                              # base dependencies only
uv sync --python 3.13 --extra all     # include the MCP 1.x app bundle and LiteLLM
uv run ouroboros --version            # verify CLI

Source checkouts use the repository .python-version, which currently defaults to stable Python 3.14. Core and non-LiteLLM source environments support Python 3.12-3.14. LiteLLM-bearing source environments, including --extra all, support Python 3.12-3.13; examples prefer Python 3.13 without making it the minimum. Do not use --all-extras: that asks uv to select the intentionally conflicting MCP 1.x application and MCP 2 server profiles together.

uv sync --python 3.13                  # base dependencies on the preferred current interpreter
uv sync --python 3.13 --extra all      # include co-installable backends/extras, including LiteLLM
uv run --python 3.13 ouroboros --version
uv run --python 3.13 pytest tests/unit/ -q

See CONTRIBUTING.md for the full contributor setup (linting, testing, pre-commit hooks).

Windows users

Two paths. Pick by the host you use:

Native Windows (PowerShell) — experimental. Nothing needs to be installed first: the script installs Git and uv through winget when they are missing, uv downloads its own Python, and the plugin's MCP server runs through uvx.

irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

Options go through environment variables, same names as install.sh (OUROBOROS_INSTALL_RUNTIME, OUROBOROS_INSTALL_RECONFIGURE, OUROBOROS_INSTALL_PRE), or bind the script and pass parameters:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1))) -Runtime claude -Reconfigure

Open a new PowerShell window afterwards so the PATH change applies. Use Windows Terminal for ouroboros config (the TUI needs ANSI support; cmd.exe is not supported). The PowerShell installer emits no installer telemetry events; the ouroboros setup it runs follows the normal controls. Limits are listed in platform support; in short, Claude Code works and Codex CLI does not.

WSL 2 — supported. Run the Linux install command from inside the WSL distribution. This is the path for Codex CLI and for every feature in the support matrix. Windows 11 Home can run WSL 2; if wsl --install or distro installation fails, see Windows WSL 2 troubleshooting.

Prerequisites

Path Requirements
All runner sessions Git >= 2.36.0 on PATH. Project identity requires the unambiguous worktree list --porcelain -z topology grammar even for a non-Git local workspace; an older or unrepresentable Git version is a non-retryable configuration error.
Claude Code (ooo) Claude Code with plugin support
Standalone CLI (ouroboros) Python >= 3.12, API key (Anthropic or OpenAI)
Codex CLI backend Python >= 3.12, npm install -g @openai/codex, and a signed-in Codex CLI account with access to a Codex-supported model
OpenCode backend Python >= 3.12, opencode on PATH, provider configured in OpenCode
Kiro CLI backend Python >= 3.12, kiro-cli on PATH (signed in to Kiro), plus pipx install 'ouroboros-ai[mcp]' or uv tool install 'ouroboros-ai[mcp]'. Then ouroboros setup --runtime kiro registers the isolated Ouroboros MCP server in ~/.kiro/settings/mcp.json
GitHub Copilot CLI backend Python >= 3.12, copilot on PATH, gh on PATH (gh auth login), plus pipx install 'ouroboros-ai[mcp]' or uv tool install 'ouroboros-ai[mcp]'. Then ouroboros setup --runtime copilot live-discovers available models, picks a default, and registers the Ouroboros MCP server in ~/.copilot/mcp-config.json
Pi CLI backend Python >= 3.12, pi on PATH or orchestrator.pi_cli_path configured. Use runtime_backend: pi for workflow execution. Use llm.backend: pi only when authoring/evaluation flows can accept Pi's adapter-level JSON extraction and schema validation rather than native --output-schema enforcement
OMP CLI backend Python >= 3.12, omp on PATH or orchestrator.omp_cli_path configured. Use runtime_backend: omp for workflow execution; OMP resumes sessions with its native --resume flag and picks its own configured model (roles smol/slow/plan) unless an explicit --model override is passed. ouroboros setup --runtime omp also installs the interactive ooo bridge into ~/.omp/agent/extensions/

Configuration

API Keys

# Claude-backed flows
export ANTHROPIC_API_KEY="your-anthropic-key"

# Codex-backed flows when using API-key authentication
export OPENAI_API_KEY="your-openai-key"

Codex CLI can also use its normal account sign-in, so OPENAI_API_KEY is not required unless you choose API-key authentication. Claude Code plugin users: your Claude Code session provides credentials automatically. No export needed.

Configuration File

ouroboros setup creates ~/.ouroboros/config.yaml with sensible defaults. To edit manually:

orchestrator:
  runtime_backend: claude   # default SDK runtime on MCP 1.x

llm:
  backend: claude_code      # claude_code | codex | litellm | copilot | opencode | gemini | goose | kiro | pi | omp

logging:
  level: info

runtime_controls:
  mcp_tool_timeout_seconds: 0                     # no fixed adapter wall-clock cap
  generation_idle_timeout_seconds: 7200           # 2h with no activity
  generation_no_progress_timeout_seconds: 14400  # 4h without material progress

For Codex CLI, leave the model on Codex's default unless you intentionally need a pin. ouroboros config --web and ouroboros config offer Use Codex default model for that choice; choose Enter another model ID… when you want to pin a stage to a model that is not listed. Ouroboros applies the task's reasoning effort per invocation. The equivalent ~/.ouroboros/config.yaml model pins look like this:

# ~/.ouroboros/config.yaml
orchestrator:
  runtime_backend: codex
  codex_cli_path: /usr/local/bin/codex

llm:
  backend: codex
  qa_model: gpt-5.4

clarification:
  default_model: gpt-5.4

execution:
  default_model: gpt-5.4  # omit, or choose Use Codex default model in config --web

evaluation:
  semantic_model: gpt-5.4

consensus:
  advocate_model: gpt-5.4
  devil_model: gpt-5.4
  judge_model: gpt-5.4

ouroboros setup --runtime codex uses ~/.codex/config.toml only for the Codex MCP/env hookup and installs managed Ouroboros rules/skills into ~/.codex/. Setup-managed stdio entries include startup_timeout_sec = 180 for cold starts. Existing URL/custom Ouroboros MCP entries and user-selected non-default timeouts are preserved by default; run ouroboros codex refresh when you only need to refresh ~/.codex/rules/ouroboros*.md and ~/.codex/skills/ouroboros-*.

Environment Variables

# Override the runtime backend (highest priority)
export OUROBOROS_AGENT_RUNTIME=codex

Resolution order: OUROBOROS_AGENT_RUNTIME env var > config.yaml > auto-detection during ouroboros setup.

For the full list of configuration keys, see Configuration Reference.

Your First Workflow

This tutorial walks through a complete workflow. Examples use ooo skills (Claude Code); CLI equivalents are shown in callouts for terminal-based workflows.

Step 1: Interview

Inside a Claude Code session:

ooo interview "I want to build a personal finance tracker"

CLI note: You can also run interviews from the terminal with ouroboros init start --llm-backend <backend> "your idea" (where <backend> is claude_code, codex, opencode, or litellm). For in-agent ooo interview usage: Claude Code works out-of-the-box; Codex CLI and OpenCode require ouroboros setup --runtime <codex|opencode> first to register the MCP server.

The Socratic Interviewer asks clarifying questions:

  • "What platforms do you want to track?" (Bank accounts, credit cards, investments)
  • "Do you need budgeting features?" (Yes, with category tracking)
  • "Mobile app or web-based?" (Desktop-only with web export)
  • "Data storage preference?" (SQLite, local file)

Answer until the ambiguity score drops below 0.2, and the interview auto-generates a seed spec. If you would rather stop before that, the CLI offers to force generation at whatever score you are on:

# Auto-generated seed (example)
goal: "Build a personal finance tracker with SQLite storage"
constraints:
  - "Desktop application only"
  - "Category-based budgeting"
  - "Export to CSV/Excel"
acceptance_criteria:
  - "Track income and expenses"
  - "Categorize transactions automatically"
  - "Generate monthly reports"
  - "Set and monitor budgets"
metadata:
  ambiguity_score: 0.15
  seed_id: "seed_abc123"

Step 2: Execute

ooo run

CLI equivalent: ouroboros run ~/.ouroboros/seeds/seed_abc123.yaml (requires the seed file path as a positional argument)

Ouroboros decomposes the seed into tasks via the Double Diamond (Discover -> Define -> Design -> Deliver) and executes them through your configured runtime backend.

Step 3: Monitor

Open a second terminal to watch progress in the TUI dashboard:

ouroboros monitor

The dashboard shows:

  • Double Diamond phase progress
  • Acceptance criteria tree with live status
  • Cost, drift, and agent activity

See TUI Usage Guide for keyboard shortcuts and screen details.

Step 4: Review

ooo run (or ouroboros run) prints a session summary with the QA verdict when complete, then continues into formal evaluation and, when the evaluation is not approved, a bounded Ralph loop. ouroboros run waits for both and prints their results; pass --no-auto-evaluate to stop after the run.

Useful follow-ups:

ooo evaluate          # Re-run 3-stage evaluation
ooo status            # Check drift and session state
ooo evolve            # Start evolutionary refinement loop

CLI equivalent: ouroboros run seed.yaml --resume <session_id> to resume, ouroboros run seed.yaml --debug for verbose output.

Common Workflows

New Project from Scratch

ooo interview "Build a REST API for a blog"
ooo run

Bug Fix

ooo interview "User registration fails with email validation"
ooo run

Feature Enhancement

ooo interview "Add real-time notifications to the chat app"
ooo run

Terminal users: Run interviews from the terminal with ouroboros init start --llm-backend <backend> "your idea", then execute with ouroboros run workflow <seed_file>. (Separate from in-agent ooo usage; terminal flows don't require MCP registration.)

Choosing a Runtime Backend

Ouroboros delegates code execution to a pluggable runtime backend. Three ship out of the box:

Claude Code Codex CLI OpenCode
Best for Claude Code users; subscription billing OpenAI ecosystem; pay-per-token billing Multi-provider flexibility; open-source tooling
Install pip install 'ouroboros-ai[claude]' (SDK/MCP 1.x); plugin MCP server uses isolated [mcp]/MCP 2 pip install ouroboros-ai + npm install -g @openai/codex pip install ouroboros-ai + opencode on PATH
Skill shortcuts ooo inside Claude Code ooo after ouroboros setup --runtime codex installs managed Codex skills ooo after ouroboros setup --runtime opencode
Config value claude (SDK default); claude_mcp only for explicit CLI worker codex opencode

All three backends run the same core workflow engine (seed execution, TUI). However, user-facing commands still differ: Claude Code has native in-session ooo workflows, while Codex CLI and OpenCode rely on ouroboros setup --runtime <backend> to configure the integration. The ouroboros CLI remains the most universal terminal path, and some advanced operations are still MCP/Claude-only.

For backend-specific configuration:

Troubleshooting

Claude Code skill not recognized

# Check skill is installed
claude plugin list

# Reinstall if needed
claude plugin install ouroboros@ouroboros --force

Python / CLI issues

python --version            # Must be >= 3.12 and should be a stable release
pip install --force-reinstall ouroboros-ai
ouroboros --version

For source checkouts, uv run ... follows .python-version and may choose Python 3.14. Use Python 3.13 for LiteLLM-bearing source environments such as uv sync --python 3.13 --extra all, or Python 3.12 when validating the lower supported bound. Core and non-LiteLLM source environments still support Python 3.12-3.14.

API key not found

export ANTHROPIC_API_KEY="your-key"     # or OPENAI_API_KEY
env | grep -E 'ANTHROPIC|OPENAI'        # verify

MCP server issues

ouroboros mcp info
ouroboros mcp serve --runtime claude-cli

TUI not displaying

export TERM=xterm-256color
ouroboros tui monitor

Stuck execution

Inside Claude Code:

ooo unstuck

From terminal:

ouroboros run seed.yaml --resume <session_id>
ouroboros cancel execution <session_id>

Quick Reference

Issue Solution
Skill not loaded claude plugin install ouroboros@ouroboros --force
CLI not found pip install ouroboros-ai
API errors Check ANTHROPIC_API_KEY / OPENAI_API_KEY
TUI blank export TERM=xterm-256color
High costs Reduce seed scope or use a lower model tier
Execution stuck ooo unstuck or ouroboros run seed.yaml --resume <id>

Best Practices

For Better Interviews

  1. Be specific -- "build a Twitter clone with real-time messaging" beats "build a social app"
  2. State constraints early -- budget, timeline, technical limitations
  3. Define success -- clear acceptance criteria produce better seeds

For Effective Seeds

  1. Include non-functional requirements -- performance, security, scalability
  2. Define boundaries -- what is in scope and what is not
  3. Specify integrations -- APIs, databases, third-party services

For Successful Execution

  1. Validate first -- ouroboros run seed.yaml --dry-run checks YAML and schema before executing
  2. Monitor with the TUI -- run ouroboros monitor in a separate terminal during long workflows
  3. Keep QA enabled -- post-execution QA runs automatically unless you pass --no-qa
  4. Let evaluation run -- formal evaluation (and Ralph when it is not approved) follows every completed or failed run unless you pass --no-auto-evaluate or set execution.auto_evaluate: false

Next Steps

Need help? Open an issue on GitHub.