Skip to content

Latest commit

 

History

History
2386 lines (1789 loc) · 111 KB

cli-reference.md

File metadata and controls

2386 lines (1789 loc) · 111 KB

CLI Reference

Complete command reference for the Ouroboros CLI.

Installation

For install instructions, onboarding, and first-run setup, see Getting Started.

Usage

ouroboros [OPTIONS] COMMAND [ARGS]...

Global Options

Option Description
-V, --version Show version and exit
--install-completion Install shell completion
--show-completion Show shell completion script
--help Show help message

Quick Start

For the full first-run walkthrough (interview → seed → execute), see Getting Started.


Commands Overview

Command Description
setup Detect runtimes and configure Ouroboros for your environment
init / interview Start an interactive interview (interview is an alias of init)
auto Run bounded goal → interview → Seed → execution handoff pipeline
job Inspect detached job status, waits, results, and event streams
run Execute Ouroboros workflows
qa Evaluate an artifact against a natural-language quality bar
cancel Cancel stuck or orphaned executions
cleanup Prune leftover auto-session worktrees, branches, locks, and state files
config Manage Ouroboros configuration (show, switch backend, set values)
gui Open the browser console: connect tools, agents & models, providers, runs, chat
service Run the console and its shared MCP server at login (launchd / systemd)
uninstall Cleanly remove all Ouroboros configuration from your system
update Update Ouroboros to the latest version (package + runtime integration)
status Check Ouroboros system status
tui Interactive TUI monitor for real-time workflow monitoring
monitor Shorthand for tui monitor
mcp MCP server commands for Claude Desktop and other MCP clients
plugin Manage UserLevel plugins (install, list, remove)
pm Product Management interview for requirements gathering
doctor Diagnose configuration and runtime health
detect Inspect a project once with an LLM and write validated Stage 1 commands to .ouroboros/mechanical.toml
artifacts Manage and inspect execution artifacts
harness Inspect and compare exported auto-interview traces
resume List in-flight sessions from the EventStore and show re-attachment commands
codex Codex-specific setup and configuration
seed Generate or inspect seed specifications
workflow-ir Inspect workflow intermediate representation
zcode Convenience wrapper for Zcode (bundles start, qa, run with Zcode pre-selected; for global config use setup --runtime zcode)

Shorthand entry points: ooo and ouroboros both launch the main CLI. ozo is a standalone shorthand that launches only the Zcode convenience commands (equivalent to ouroboros zcode ...).


ouroboros auto

Run the full-quality auto pipeline from a single goal. This is the CLI equivalent of ooo auto in agent sessions.

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

Options:

Option Description
--resume TEXT Resume an existing auto session id
--runtime TEXT Runtime backend for the run-handoff phase. Shipped values: claude, codex, opencode, hermes, gemini, goose, kiro, copilot, pi, omp, gjc, antigravity, grok, zcode. Authoring phases (interview, seed generation) always run in-process inside the Ouroboros MCP server in ooo auto flow - see What --runtime controls in ooo auto below.
--max-interview-rounds INTEGER Maximum automatic interview rounds; prevents unbounded interview loops
--max-repair-rounds INTEGER Deprecated and ignored: auto no longer reviews or repairs the Seed. Prints a warning when passed
--skip-run Stop after the Seed is written
--show-ledger Print assumptions and non-goals captured during auto convergence
--status Print the persisted state for --resume <id> without running
--requester-command CMD Ask the requester instead of assuming (off by default; see below). Overrides OUROBOROS_AUTO_REQUESTER_COMMAND
--requester-timeout SECONDS Seconds to wait for one requester answer before keeping auto's draft (default 300). Overrides OUROBOROS_AUTO_REQUESTER_TIMEOUT_SECONDS
--progress-jsonl PATH Also append every live progress event to PATH as one JSON object per line (see Machine-readable progress). The text output is unchanged

Auto mode writes the generated Seed and starts execution on it directly: there is no Seed review, grade, repair, or pre-run check in between, and the run verifies each acceptance criterion after it executes. A session saved in the old review or repair phase, or blocked by the old pre-run checks, resumes with --resume and goes straight to the run. If a phase times out or hits a hard blocker, the command prints the auto session id and a resume command instead of hanging indefinitely.

Machine-readable progress

--progress-jsonl PATH appends each live progress event to PATH, one JSON object per line, and flushes the line before the pipeline goes on. The text trace (the [auto] … lines) prints exactly as without the option, and --quiet silences only the text, not the file. The Ouroboros console uses this file to show an Auto chat as a live view.

Each line has every field of an event:

{"auto_session_id": "auto_8820ee51202b", "phase": "interview", "kind": "answer", "message": "answered round 6/50 from non_goal", "round": 6, "grade": null, "question": "Which parts are out of scope?", "answer": "CLI and packaging are non-goals.", "answer_source": "non_goal", "timestamp": "2026-11-16T23:54:22.448527+00:00"}
  • kind is phase (the phase or its progress message changed), question (the interview asked round round) or answer (auto answered round round). Files written before the Seed review was removed may also hold grade and repair lines, with the grade field set; nothing writes them now, and grade is null on every new line.
  • phase is the auto phase at that moment: created, interview, seed_generation, run, complete, blocked or failed. Older files may also hold the retired review, repair, ralph_handoff, evaluate and unstuck_lateral phases.
  • answer_source says where an answer came from: user_goal, repo_fact, existing_convention, user_preference, conservative_default, assumption, non_goal, blocker or requester.

The file is appended to, never truncated, and is not created until the first event. Its directory must already exist. A write that fails (a missing directory, no permission, a full disk) does not stop the pipeline: the first failure prints one warning on stderr, and later events are still attempted. With --status, nothing runs and nothing is written.

Asking the requester instead of assuming

Auto answers interview questions itself. When a draft answer has source conservative_default or assumption, auto is guessing. With --requester-command CMD (or OUROBOROS_AUTO_REQUESTER_COMMAND), auto asks the requester at exactly those questions and still answers every other question itself.

For each such question, auto runs CMD once. The command is split like a shell command (shlex.split) but runs without a shell. Its stdin is one JSON object:

{"question": "...", "goal": "...", "draft_answer": "...", "draft_source": "conservative_default", "round": 3}

Its stdout is either {"answer": "..."} or plain text. A nonempty answer replaces the draft. A timeout, a nonzero exit, an empty answer, or a JSON object without a string answer keeps the draft. The option wins over the variable, and --requester-command "" turns the requester off. The command is read again on every invocation and is not stored in the session, so pass it again with --resume.

Where the answers are recorded:

  • The interview transcript gets [from-auto][requester] <answer> in place of the draft (rounds[].user_response in ~/.ouroboros/data/interview_<interview_session_id>.json).
  • In the auto session file (~/.ouroboros/data/<auto_session_id>.json), auto_answer_log[].source is requester. requester_log has one entry per question sent to the requester: round, question, draft_source, draft_answer, outcome (answered, timeout, nonzero_exit, empty_answer, invalid_output or launch_failed), used, answer, detail and elapsed_seconds. The key is absent when no question went to the requester. Text fields in both logs are cut to 200 characters; the full answer is in the interview transcript.
  • Each question also emits an auto.interview.requester_asked event (fields round, draft_source, outcome, used, detail, elapsed_seconds, question) to the event store.

Time spent waiting for the requester counts against the interview phase timeout (OUROBOROS_PHASE_TIMEOUT_INTERVIEW_SECONDS, default 600 seconds). The requester is available from the CLI only; the MCP auto tools do not use it yet.

Detached auto wait and retrieve

Detached auto work is non-terminal tracked background work. Starting it does not mean the workflow has completed; the returned job_id is a handle for a tracked job whose lifecycle remains observable until it reaches a terminal state such as completed, failed, or cancelled. Terminal results are read from persisted job events; the in-memory handle TTL only bounds live registry cleanup, not completed result retrieval.

CLI users wait and retrieve with the standard job surfaces:

ouroboros job status JOB_ID
ouroboros job wait JOB_ID
ouroboros job result JOB_ID
ouroboros job events JOB_ID --since 0 --limit 100

ouroboros job events is the low-cost external observability surface for dashboards and schedulers. It opens the configured runtime EventStore read-only, does not create schema or write WAL/checkpoint state, and prints cursor-paged JSON for the job aggregate. Pass the returned cursor back as --since on the next poll.

MCP clients use the matching job tools:

ouroboros_job_status(job_id="JOB_ID")
ouroboros_job_wait(job_id="JOB_ID")
ouroboros_job_result(job_id="JOB_ID")

While a detached job is still running, its running lifecycle status is non-terminal tracked background work. Treat status output as progress, not as the final auto result. Retrieve the result only after the job reaches a terminal lifecycle status. When CLI status reports completed, ouroboros job result JOB_ID retrieves the stable completed auto result for that job handle. When CLI status reports failed, the job is terminal and still observable; ouroboros job result JOB_ID returns the stable failure output or error details for that job handle, not a successful auto result. Next steps are to inspect ouroboros job status JOB_ID and ouroboros job result JOB_ID, then resume or retry from the surfaced auto session, execution, or lineage handle when one is present. When CLI status reports cancelled, the job is terminal and still observable; ouroboros job result JOB_ID returns stable cancellation output or error details for that job handle with the cancellation reason when one is available, not a successful auto result. Next steps are to inspect ouroboros job status JOB_ID and ouroboros job result JOB_ID, then restart the detached auto flow or resume from the surfaced auto session, execution, or lineage handle when one is present. The CLI prints the stable cancellation output and exits non-zero because the terminal result is an error result. When a terminal job is older than the in-memory handle TTL, ouroboros job result JOB_ID still retrieves the persisted terminal result for that job handle. ouroboros job status JOB_ID reports the stored terminal lifecycle status, and result retrieval returns the durable result artifact rather than an expiration error. Unknown or otherwise unavailable handles fail through the CLI with a non-zero status and through MCP with an error response. When CLI status cannot resolve the supplied handle, treat the detached work as invalid or unavailable rather than as running or completed. The stable observable status is the non-zero CLI exit plus the human-readable error for that handle. Next steps are to check the copied job_id, inspect any surfaced auto session, execution, or lineage handle, then restart the detached auto flow when no valid handle can be recovered.

Example invalid CLI retrieval output:

$ ouroboros job result missing_detached_auto
Job handle not found: missing_detached_auto. Result unavailable.

Example completed CLI retrieval output:

$ ouroboros job result job_auto_docs_done
detached auto result artifact: seed.yaml

Example cancelled CLI retrieval output:

$ ouroboros job result job_auto_docs_cancelled
detached auto cancelled: user requested cancellation

Example expired CLI retrieval output:

$ ouroboros job result job_auto_docs_expired
detached auto result artifact: expired seed.yaml

ooo auto does not accept --opencode-mode. OpenCode mode is selected once at install time via ouroboros setup --opencode-mode <plugin|subprocess> (recorded in ~/.ouroboros/config.yaml); the auto CLI reads that persisted value but never exposes it as a flag.

What --runtime controls in ooo auto

ooo auto runs four logical phases. --runtime selects the backend for the run-handoff phase only. The three preceding authoring phases (interview, seed generation, seed repair) always run in-process inside the Ouroboros MCP server in ooo auto flow, regardless of --runtime or the persisted opencode_mode. Both auto entry points (cli/commands/auto.py and mcp/tools/auto_handler.py) demote a persisted opencode_mode == "plugin" to subprocess before constructing the authoring handlers, because a _subagent envelope would have no receiver outside an active OpenCode bridge plugin session.

Phase Handler ooo auto behaviour
1. Interview authoring mcp.tools.authoring_handlers.InterviewHandler In-process for every --runtime value. opencode + plugin is demoted to subprocess before the handler is constructed, so authoring never short-circuits to the bridge.
2. Seed generation mcp.tools.authoring_handlers.GenerateSeedHandler Same rule as interview authoring — always in-process for ooo auto.
3. Run handoff mcp.tools.execution_handlers.StartExecuteSeedHandler Routed through the runtime adapter selected by --runtime. CLI entry point (ouroboros auto) also demotes opencode + plugin to subprocess here, because the standalone CLI process is not the OpenCode session that owns the bridge plugin. MCP entry point (mcp/tools/auto_handler.py) keeps plugin for run-handoff because it is invoked from inside the OpenCode session.

Why this matters: --runtime codex does not mean "Codex performs the interview". The Ouroboros MCP server still owns the first authoring question and may time out before any Codex subagent is invoked. If interview.start blocks, the timeout originates from the in-process authoring path, not from the Codex CLI. Set realistic expectations when chaining ooo auto from external gateways.

Underlying MCP-handler dispatch (outside ooo auto)

The same InterviewHandler / GenerateSeedHandler classes can short-circuit to a _subagent envelope only when called directly from inside an active OpenCode bridge plugin session — not from ooo auto. The dispatch gate lives in should_dispatch_via_plugin() and is exhaustively tested in tests/unit/mcp/tools/test_subagent.py::TestShouldDispatchViaPlugin. This truth table describes the gate function alone, not the auto flow:

runtime_backend opencode_mode Gate result
claude (any) False (in-process)
codex (any) False (in-process)
hermes (any) False (in-process)
gemini (any) False (in-process)
kiro (any) False (in-process)
copilot (any) False (in-process)
opencode subprocess False (in-process)
opencode (unset/None) False (in-process — safe default)
opencode plugin True (dispatched via _subagent) — reachable from inside an OpenCode bridge plugin session, not from ooo auto

ouroboros setup

Detect available runtime backends and configure Ouroboros for your environment.

Ouroboros supports multiple runtime backends via a pluggable AgentRuntime protocol. The setup command auto-detects which runtimes are available (including Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Goose, Pi, GJC, Antigravity, Grok, and Zcode) and configures orchestrator.runtime_backend accordingly. Additional runtimes can be registered by implementing the protocol — see Architecture.

ouroboros setup [OPTIONS]

Options:

Option Description
-r, --runtime TEXT Runtime backend to configure. Shipped values: claude, claude-sdk, claude-cli, codex, opencode, hermes, gemini, goose, kiro, copilot, pi, omp, gjc, antigravity, grok, zcode, megacode, host. Auto-detected if omitted
--opencode-mode TEXT OpenCode integration mode: plugin (default, recommended — bridge plugin for interactive sessions) or subprocess (headless/CI). Mutually exclusive — see OpenCode runtime guide
--non-interactive Skip interactive prompts (for scripted installs)
--mcp-mode TEXT Codex MCP config mode: auto (default), preserve, stdio, or native-Windows-only explicit http

For Pi, setup also installs ~/.pi/agent/extensions/ouroboros-ooo-bridge.ts. Restart Pi or run /reload and interactive Pi/roach-pi sessions can dispatch ooo ... commands into Ouroboros through the shared skill router. For OMP (Oh My Pi), setup also installs ~/.omp/agent/extensions/ouroboros-ooo-bridge.ts (dispatch timeout: OUROBOROS_OMP_BRIDGE_TIMEOUT_MS). Restart OMP and interactive OMP sessions can dispatch ooo ... commands into Ouroboros through the shared skill router. For GJC, setup installs the GJC-side ooo bridge extension into <agent-dir>/extensions and a renderer-generated skill capability guide into <agent-dir>/rules/ouroboros-skill-capability-guide.md. Interactive GJC sessions can dispatch ooo ... commands into Ouroboros after the extension is loaded.

Examples:

# Auto-detect runtimes and configure interactively
ouroboros setup

# Explicitly select Codex CLI as runtime backend
ouroboros setup --runtime codex

# Explicitly select Claude Code as runtime backend
ouroboros setup --runtime claude

# Explicitly select Kiro CLI as runtime backend (writes ~/.kiro/settings/mcp.json)
ouroboros setup --runtime kiro

# Keep backend copilot, but opt into experimental live ACP execution
ouroboros setup --runtime copilot
ouroboros config set orchestrator.copilot_transport acp

# Explicitly select Zcode as a runtime-only backend
ouroboros setup --runtime zcode

# Non-interactive setup (for CI or scripted installs)
ouroboros setup --non-interactive

What setup does:

Copilot's runtime token remains copilot for setup, run, and MCP commands; copilot-acp is not a separate --runtime value. ACP is a transport setting, with default cli. orchestrator.copilot_acp_fallback defaults to true, but only permits pre-prompt read-only/tool-less fallback. LLM-only flows remain on the existing CLI adapter. See the ACP guide for permissions, authentication and streaming diagnostics.

  • Detects configured paths and PATH entries for the shipped runtimes, including zcode and the macOS ZCode app-bundle script
  • Prompts you to select a runtime if multiple are found (or auto-selects if only one)
  • Writes orchestrator.runtime_backend to ~/.ouroboros/config.yaml
  • For Claude CLI setup: configures the dependency-free claude_mcp runtime and leaves ~/.claude/mcp.json ownership to the host/plugin
  • For explicit --runtime claude-sdk: preserves the SDK runtime, rejects an MCP 2 environment, and leaves ~/.claude/mcp.json untouched
  • For Codex CLI: sets orchestrator.codex_cli_path and llm.backend: codex in ~/.ouroboros/config.yaml
  • For Codex CLI: installs managed Ouroboros rules into ~/.codex/rules/
  • For Codex CLI: installs managed Ouroboros skills into ~/.codex/skills/
  • For Codex release installs using uvx: pins the MCP package to the installed setup version (ouroboros-ai[mcp]==<version>). Source/dev installs keep serving their current Python environment.
  • For Codex CLI: registers or refreshes setup-managed stdio blocks on supported hosts and preserves user-managed URL/custom blocks by default. A legacy PATH-selected ouroboros mcp serve entry with the canonical Codex environment is migrated to the isolated managed launcher; custom executable paths and extra process controls remain untouched. Native Windows auto creates no MCP child, stdio is refused, and explicit http writes the loopback URL only after resolving a launchable MCP command; the operator owns that visible server process.
  • For Codex CLI: adds missing Ouroboros task profiles whose per-role reasoning effort is passed to each codex exec invocation; it retires only untouched legacy generated profile anchors and preserves user-created Codex profiles
  • For Codex CLI: reads codex --help as UTF-8 to determine the worker-profile format. If the probe fails or the format is unknown, setup reports failure and rolls back its managed changes instead of assuming a legacy profile. Check that the configured Codex executable's --help succeeds, then rerun setup.
  • For OpenCode: registers the Ouroboros MCP server in OpenCode's configuration
  • For OpenCode (plugin mode): installs the bridge plugin into <opencode_config_dir>/plugins/ouroboros-bridge/
  • For OpenCode: installs the runtime skill capability guide into global AGENTS.md in the active OpenCode config directory
  • For Gemini CLI: installs the runtime skill capability guide into ~/.gemini/GEMINI.md
  • For Kiro CLI: sets orchestrator.kiro_cli_path and llm.backend: kiro in ~/.ouroboros/config.yaml, and registers the Ouroboros MCP server in ~/.kiro/settings/mcp.json with OUROBOROS_RUNTIME=kiro / OUROBOROS_LLM_BACKEND=kiro baked into the entry's env. The launcher is always isolated through uvx or pipx run; direct global binaries are rejected because they cannot guarantee MCP 2
  • Kiro, Copilot, and Hermes setup is transactional at the activation boundary: if no isolated launcher is available or host registration fails, setup exits non-zero without persisting the selected Ouroboros runtime
  • For Kiro CLI: installs the runtime skill capability guide into ~/.kiro/steering/ouroboros-skill-capability-guide.md
  • For Copilot CLI: installs the runtime skill capability guide into ~/.copilot/ouroboros-instructions/AGENTS.md and configures Ouroboros-launched Copilot child sessions to read it via COPILOT_CUSTOM_INSTRUCTIONS_DIRS
  • For GJC: sets orchestrator.gjc_cli_path and llm.backend: gjc in ~/.ouroboros/config.yaml
  • For GJC: installs the ooo bridge extension into <agent-dir>/extensions and the renderer-generated skill capability guide into <agent-dir>/rules/ouroboros-skill-capability-guide.md
  • For Zcode: sets orchestrator.runtime_backend: zcode and orchestrator.zcode_cli_path while leaving the completion-only llm.backend unchanged

Claude runtime activation publishes a newly needed credentials.yaml before publishing config.yaml, which is the transaction commit point. If activation fails before that commit, setup removes the live credential name with a guarded atomic move. It does not truncate, overwrite, or unlink the inode: portable filesystems cannot prove that a same-UID process did not create a hardlink at the final mutation boundary. The generated bytes therefore remain in an owner-only hidden .retired recovery artifact for explicit operator inspection and disposal. Any concurrent hardlink alias keeps its original bytes. If the guarded move itself cannot be proven, setup preserves the pathname, recovery journal, and every observed generation for human handoff.

Symlinked POSIX home directories and junction-backed Windows home directories are supported: setup resolves and pins the selected physical home generation before mutation. The .ouroboros directory itself must still be a regular, non-symlink/non-reparse directory and is identity-checked throughout activation.

Codex config split: use ouroboros config or ouroboros config --web to choose Use Codex default model (Codex's current default) or Enter another model ID… to pin a model for each pipeline stage, including Execute. The web view is the same settings UI as the terminal TUI. ~/.codex/config.toml remains the Codex MCP/env hookup file; user-created Codex --profile settings remain supported. If you run a long-lived URL-based Ouroboros MCP server, setup preserves that user-managed entry in the default --mcp-mode auto; use --mcp-mode stdio only when you intentionally want setup to replace it.

Brownfield Subcommands

ouroboros setup also includes brownfield repository registration helpers:

ouroboros setup scan [SCAN_ROOT]
ouroboros setup list
ouroboros setup default

ouroboros setup scan [SCAN_ROOT] walks scan_root for valid seed git repositories and worktrees. When SCAN_ROOT is omitted, scan_root defaults to the current user's home directory. The filesystem walk is bounded to scan_root: dot-prefixed directories and known noisy directories such as node_modules are not walked as seed locations. Local repos, repos without remotes, and repos whose remotes are not named origin are all eligible.

Linked worktree expansion has a different boundary. For each normal repo root found under scan_root with a .git directory, Ouroboros runs git worktree list --porcelain and may register those linked worktrees even when their paths are outside scan_root, as long as Git reports them and the paths still exist. A linked worktree found under scan_root with a .git file is registered itself, but it is not used to register its main worktree or sibling worktrees outside scan_root. This keeps narrow scans scoped when a user intentionally passes one worktree as AI context. Existing registrations and default selections are preserved by upsert.


ouroboros init

Start interactive interview to refine requirements (Big Bang phase).

Shorthand: ouroboros init "context" is equivalent to ouroboros init start "context". When the first argument is not a known subcommand (start, list) and does not start with -, it is treated as the context for init start. A leading option is parsed by init itself, which accepts only --help, so name start before it: ouroboros init start --orchestrator "context".

The top-level interview command is an alias for the same command group, so ouroboros interview start "context" and ouroboros interview list have the same behavior as their init counterparts.

init start

Start an interactive interview to transform vague ideas into clear, executable requirements.

ouroboros init [start] [OPTIONS] [CONTEXT]

Arguments:

Argument Description
CONTEXT Initial context or idea (interactive prompt if not provided)

Options:

Option Description
-r, --resume TEXT Resume an existing interview by ID
--state-dir DIRECTORY Custom directory for interview state files
-o, --orchestrator Use Claude Code for the interview/seed flow; combine with --runtime to choose the workflow handoff backend
--runtime TEXT Agent runtime backend for the workflow execution step after seed generation. Shipped values: claude, codex, opencode, hermes, gemini, goose, kiro, copilot, pi, omp, gjc, antigravity, grok, zcode. Custom adapters registered in runtime_factory.py are also accepted.
--llm-backend TEXT LLM backend for interview, ambiguity scoring, and seed generation (claude_code, litellm, codex, copilot, opencode, gemini, goose, kiro, pi, omp, zcode, dsh, megacode). dsh needs two more settings — see the DeepSeek Harness guide.
-d, --debug Show verbose logs including debug messages
-m, --model TEXT Model for every role in this command: auto (latest of each role's tier), frugal, standard, frontier, or a model id. Tier names work on every backend; Claude aliases such as opus only on Claude backends. Default: models.default in config (auto)
--pin-models/--no-pin-models Run the per-role model ids saved in config for this command (research and reproducibility). Default: models.pin in config (off)

Examples:

# Shorthand (recommended) -- 'start' subcommand is implied
ouroboros init "I want to build a task management CLI tool"

# Explicit subcommand (equivalent)
ouroboros init start "I want to build a task management CLI tool"

# Start with Claude Code (no API key needed)
ouroboros init start --orchestrator "Build a REST API"

# Specify runtime backend for the workflow step
ouroboros init start --orchestrator --runtime codex "Build a REST API"

# Use Codex as the LLM backend for interview and seed generation
ouroboros init start --llm-backend codex "Build a REST API"

# Run the interview and seed generation on the frontier tier
ouroboros init start --model frontier "Build a REST API"

# Resume an interrupted interview
ouroboros init start --resume interview_20260116_120000

# Interactive mode (prompts for input)
ouroboros init

init list

List all interview sessions.

ouroboros init list [OPTIONS]

Options:

Option Description
--state-dir DIRECTORY Custom directory for interview state files
--summary Instead of listing sessions, print interview closure counts per calling surface from the local event store. Default: off. Cannot be combined with --state-dir

--summary reads the interview.* events in the local event store (the same database ouroboros_query_events reads) and prints two tables with one row per calling surface: console, mcp:<host> (for example mcp:claude_code), cli_init, auto, or unrecorded for interviews started before surfaces were recorded. The outcomes table shows interviews started and completed, early closes by a forced Seed ("Write the spec now", force=true, or "Generate Seed anyway"), abandoned interviews (no completion or forced Seed, and idle for 24 hours) with their rate, and interviews still open. The questions table shows questions per completed interview (median and mean) and per forced-early interview (median). It reads counts and labels only, never question or answer text, and sends nothing off the machine. Field definitions are in Event payload schema.

ouroboros init list --summary

ouroboros seed

Generate a Seed YAML specification from a completed interview session, with the same ambiguity scoring and Seed generation that ouroboros init start runs at the end of an interview.

ouroboros seed [OPTIONS] SESSION_ID

The session must be completed; otherwise the command exits with status 1 and names the command that resumes it. When the ambiguity score is not ready for a Seed, the command shows the same menu as init start: choosing to generate anyway writes the Seed, and the other choices exit with status 1 without one. The Seed is written to ~/.ouroboros/seeds/<seed_id>.yaml.

Arguments:

Argument Required Description
SESSION_ID Yes Interview session ID to crystallize into a Seed (see ouroboros init list)

Options:

Option Description
--state-dir DIRECTORY Custom directory for interview state files (default: ~/.ouroboros/data)
--llm-backend TEXT LLM backend for ambiguity scoring and seed generation (claude_code, litellm, codex, copilot, opencode, gemini, goose, kiro, pi, omp, zcode, dsh, megacode). Uses llm.backend from config if omitted

Example:

ouroboros seed interview_20260116_120000

ouroboros pm

Run a PM interview that produces a Product Requirements Document rather than code. Questions are classified as planning questions for the PM, or as development questions deferred to the dev interview.

ouroboros pm [OPTIONS]

When the interview completes, the command saves a PM seed (~/.ouroboros/seeds/pm_seed_<id>.json) and a human-readable pm.md in the --output directory, prints the command that continues into the dev interview, and offers to start it. The PM seed is a handoff artifact for the dev interview, not a runnable Seed. Starting a new session when PM seeds already exist asks for confirmation first.

This direct CLI runs greenfield interviews only. It exits with status 1, and points to ooo pm (MCP), which carries the code and data evidence lanes, when a new session is started while brownfield repositories are registered or when the session being resumed covers a codebase.

Options:

Option Description
-r, --resume TEXT Resume an existing PM interview session by ID
-o, --output TEXT Output directory for the generated pm.md (default: .ouroboros/ in the current directory)
-m, --model TEXT Model for every role in this command: auto (latest of each role's tier), frugal, standard, frontier, or a model id. Default: models.default in config (auto)
--pin-models/--no-pin-models Run the per-role model ids saved in config for this command (research and reproducibility). Default: models.pin in config (off)
--debug Enable debug output

Examples:

# Start a new PM interview
ouroboros pm

# Resume a session and save pm.md to ./docs/
ouroboros pm --resume abc123 --output ./docs

ouroboros detect

For projects with recognized manifests, use one LLM call to propose lint, build, test, and static-analysis commands and persist validated commands to .ouroboros/mechanical.toml. The CLI initializes the selected LLM adapter before discovery, even when the project has no manifests. That backend's initialization requirements must therefore be satisfied; for example, selecting litellm requires its optional package and a supported Python version. If initialization fails, the command exits with Could not initialize LLM adapter before discovery and writes no configuration. After successful initialization, a manifest-free, discoverable standard-library unittest.TestCase suite under tests/ uses deterministic discovery without an LLM call. Modules or packages with a custom load_tests hook do not establish a discoverable suite from their visible test classes, because the hook can replace those tests. Another ordinary module can still establish a suite; otherwise no configuration is produced. An empty project also produces no configuration. If the file already exists, the command leaves it unchanged without initializing an adapter unless --force is passed. This command authors the deterministic Stage 1 configuration; it does not detect installed runtime backends.

ouroboros detect [OPTIONS] [PATH]
Option Description
-f, --force Re-detect and overwrite an existing .ouroboros/mechanical.toml
--backend TEXT Select the LLM adapter initialized before discovery (claude, codex, gemini, opencode, or litellm); only manifest-backed inspection makes an LLM call

ouroboros harness

Read and compare auto-interview trace projections. The command lists runs, renders summaries and outcomes, searches the five JSONL trace streams, compares two runs, or ranks runs by an outcome metric. It does not manage runtime harness configuration. When persisted auto state exists without an exported trace, a requested run may be projected on demand into .ouroboros/traces/<run_id>/.

ouroboros harness list
ouroboros harness show RUN_ID
ouroboros harness trace RUN_ID --grep PATTERN [--stream NAME]
ouroboros harness diff RUN_A RUN_B
ouroboros harness frontier --metric NAME

ouroboros resume

List running or paused sessions directly from the EventStore after an MCP disconnect. The command opens the store read-only and shows identifiers and commands for inspection, monitoring, and resuming execution; it does not resume a session by itself.

ouroboros resume [--all] [--list]

By default, the 20 most recent in-flight sessions are shown. Pass --all to show every in-flight session. After listing sessions, the command prompts for a session and prints re-attachment guidance. Pass --list (-l) to print the table and exit without prompting, for example from scripts or agents.


ouroboros run

Execute Ouroboros workflows.

Shorthand: ouroboros run seed.yaml is equivalent to ouroboros run workflow seed.yaml. When the first argument is not a known subcommand (workflow, resume), it is treated as the seed file for run workflow.

Default mode: Orchestrator mode is enabled by default. --no-orchestrator exists for the legacy standard path, which is still placeholder-oriented.

run workflow

Execute a workflow from a seed file.

ouroboros run [workflow] [OPTIONS] SEED_FILE

Arguments:

Argument Required Description
SEED_FILE Yes Path to the seed YAML file

Options:

Option Description
-o/-O, --orchestrator/--no-orchestrator Use the agent-runtime orchestrator for execution (default: enabled)
--runtime TEXT Agent runtime backend override (claude, codex, opencode, hermes, gemini, copilot, goose, kiro, pi, omp, gjc, antigravity, grok, zcode). Uses configured default if omitted
-r, --resume TEXT Resume a previous orchestrator session by ID. A run continues only while the process that started it holds its live state (its check package's held-out cases never leave that process); resumed from a new process, the run is recorded as failed and a new attempt starts from the project, while the interrupted attempt's work stays on its task branch
--mcp-config PATH Path to MCP client configuration YAML file
--mcp-tool-prefix TEXT Prefix to add to all MCP tool names (e.g., mcp_)
-s, --sequential Execute ACs sequentially instead of in parallel; the same atomic evidence checks apply, including rejection and retry guidance for malformed receipts backed by a current-attempt trusted-wrapper run
--max-decomposition-depth INTEGER Maximum recursive AC decomposition depth (any non-negative integer; default 2). Values 0..4 are eligible for Routing D durable replay. Larger legacy values remain executable but do not publish the Routing D parallel resume-owner guarantee. The same contract applies to OUROBOROS_MAX_DECOMPOSITION_DEPTH and seed.orchestrator.max_decomposition_depth
-n, --dry-run Validate seed without executing. Currently only takes effect with --no-orchestrator. In default orchestrator mode this flag is accepted but has no effect — the full workflow executes
--no-qa Skip post-execution QA evaluation
--auto-evaluate/--no-auto-evaluate After the run finishes (completed or failed), enqueue formal evaluation of the directory the run executed in (inside its task worktree) and wait for its result, as ooo run does. A paused or cancelled run is not evaluated. Default: execution.auto_evaluate in config (on)
--auto-evolve/--no-auto-evolve When formal evaluation is not approved, continue into the bounded Ralph job the evaluation chains and wait for its result. Default: execution.auto_evolve in config (on)
--check-package/--no-check-package Build executable checks from the acceptance criteria before the worker starts, admit them on the current tree, and run them on the finished workspace. By default they only record what they would have decided (record mode): no criterion or run outcome changes and the worker gets no repair turn. --check-package lets them decide the criteria they cover for this run (the existing verifier stays advisory for those and decides the rest); --no-check-package turns them off for this run. Default: OUROBOROS_CHECK_PACKAGE (exactly decide, on (the same as decide), record or off; any other set value, such as 1, true or ON, means off), then boundary.check_package in config, then record. The checks are model-written Python scripts: they run on throwaway copies of the project with the project's interpreter, a per-check timeout, and an allowlisted environment, confined by the execution sandbox (they can write only inside their copy and a scratch directory, and have no network); they can read files you can read. Where the sandbox is unavailable, a check is undecided and does not run. The same switch applies to ooo run from a plugin host, meaning the in-process ouroboros_execute_seed / ouroboros_start_execute_seed path; an execution dispatched to the OpenCode plugin's child session is not governed and reports check_package: not_applied. Only Claude Code and Codex CLI can construct checks; with another runtime the existing verifier decides the run.
-m, --model TEXT Model for every role in this run, the check package and the evaluation it continues into included: auto (latest of each role's tier), frugal, standard, frontier, or a model id. Tier names work on every backend; Claude aliases such as opus only on Claude backends. Default: models.default in config (auto)
--pin-models/--no-pin-models Run the per-role model ids saved in config for this run (research and reproducibility). Default: models.pin in config (off)
-d, --debug Show logs and agent thinking (verbose output)

Examples:

# Run a workflow (shorthand, recommended)
ouroboros run seed.yaml

# Explicit subcommand (equivalent)
ouroboros run workflow seed.yaml

# Use Codex CLI as the runtime backend
ouroboros run seed.yaml --runtime codex

# With MCP server integration
ouroboros run seed.yaml --mcp-config mcp.yaml

# Resume a previous session
ouroboros run seed.yaml --resume orch_abc123

# Skip post-execution QA
ouroboros run seed.yaml --no-qa

# Stop after the run instead of continuing into formal evaluation
ouroboros run seed.yaml --no-auto-evaluate

# Evaluate, but do not continue a rejected evaluation into Ralph
ouroboros run seed.yaml --no-auto-evolve

# Run every role on the frontier tier
ouroboros run seed.yaml --model frontier

# Let the check package decide for this run instead of only recording
# (or: OUROBOROS_CHECK_PACKAGE=decide, or boundary.check_package: decide)
ouroboros run seed.yaml --check-package

# Turn the check package off for this run (or: OUROBOROS_CHECK_PACKAGE=off,
# or boundary.check_package: off in ~/.ouroboros/config.yaml)
ouroboros run seed.yaml --no-check-package

# Debug output
ouroboros run seed.yaml --debug

# Sequential execution (one AC at a time)
ouroboros run seed.yaml --sequential

# Allow up to four recursive splits with Routing D durable replay
ouroboros run seed.yaml --max-decomposition-depth 4

After execution (and post-execution QA on success), ouroboros run continues into formal evaluation and, when the evaluation is not approved, a bounded Ralph job, the same chain ooo run uses. The evaluation and Ralph jobs run in detached background workers; the command waits for each, prints its result, and keeps the run's own exit code (a failed run still exits 1, and a failure to start evaluation is only a warning). Ctrl-C while waiting stops waiting without cancelling the jobs and prints their job ids; follow them with ouroboros job wait <job_id> --timeout-seconds 60 --view compact and ouroboros job result <job_id>.

Depth values above 4 remain accepted for compatibility and execute through the historical legacy parallel path. They do not publish the Routing D parallel resume owner. Use 4 or less when the stronger bounded crash-replay guarantee is required.

run resume

Resume a paused or failed execution.

Current state: run resume is a placeholder helper. For real orchestrator sessions, use ouroboros run seed.yaml --resume <session_id>.

ouroboros run resume [EXECUTION_ID]

Arguments:

Argument Description
EXECUTION_ID Execution ID to resume (uses latest if not specified)

Note: For orchestrator sessions, you can also use:

ouroboros run seed.yaml --resume <session_id>

ouroboros job

Inspect background jobs, such as detached auto work or a job started by an ouroboros_start_* MCP tool. status, wait, and result run the same handlers as the ouroboros_job_status, ouroboros_job_wait, and ouroboros_job_result MCP tools and exit with status 1 when the handler reports an error. For the job lifecycle, see Detached auto wait and retrieve.

job status

Print the latest status for a background job.

ouroboros job status [OPTIONS] JOB_ID
Option Description
--view TEXT full (default), summary, or compact

job wait

Wait briefly for a background job update.

ouroboros job wait [OPTIONS] JOB_ID
Option Description
--cursor INTEGER Previous cursor from job status or job wait (default: 0)
--timeout-seconds INTEGER Maximum seconds to wait for a change (default: 0, an immediate snapshot)
--view TEXT full (default), summary, or compact
--stream TEXT progress (default) or linked

job result

Print the terminal result for a background job.

ouroboros job result JOB_ID

job events

Print the job's events from the EventStore as cursor-paged JSON (job_id, cursor, count, events, read_only). The store is opened read-only; the command exits with status 1 if the database file does not exist.

ouroboros job events [OPTIONS] JOB_ID
Option Description
--since INTEGER Last seen EventStore rowid cursor; must be non-negative (default: 0)
--limit INTEGER Maximum job events to return; must be positive (default: 100)
--db-path TEXT Path to ouroboros.db (default: the configured runtime database)

Example:

ouroboros job wait JOB_ID --timeout-seconds 30 --view summary

ouroboros artifacts

Fetch, replay, and conservatively prune Disposable Memory artifact bodies, stored under .ouroboros/artifacts in a project. Every subcommand takes --project-dir DIRECTORY (default: the current directory) and exits with status 1 on a store error.

artifacts prune

List the artifact bodies eligible for pruning. Nothing is deleted unless --apply is passed.

ouroboros artifacts prune [OPTIONS]
Option Description
--project-dir DIRECTORY Project containing .ouroboros/artifacts (default: .)
--ttl TEXT Minimum artifact age: a whole number and a unit s, m, h, d, or w (default: 90d)
--apply Write tombstones and delete the listed bodies
--allow-replay-tombstone Also prune inactive contracts still inside replay retention

artifacts fetch

Print the artifact body bound to one contract id as JSON.

ouroboros artifacts fetch [OPTIONS] CONTRACT_ID
Option Description
--project-dir DIRECTORY Project containing .ouroboros/artifacts (default: .)

artifacts replay

Replay a contract by reading its stored body; this command never re-executes work. The output is the same JSON body fetch prints.

ouroboros artifacts replay [OPTIONS] CONTRACT_ID
Option Description
--project-dir DIRECTORY Project containing .ouroboros/artifacts (default: .)

Example:

# See what a 30-day prune would remove, without deleting anything
ouroboros artifacts prune --ttl 30d

ouroboros workflow-ir

Inspect read-only Workflow IR projections.

workflow-ir inspect

Project a Seed file into a Workflow IR WorkflowSpec without dispatching any work. Prints the spec id, node and edge counts, and the validation status. Exits with status 1 if the file cannot be read or projected, for example when it is not a YAML mapping or not a valid Seed.

ouroboros workflow-ir inspect [OPTIONS] SEED_FILE
Option Description
--json Emit seed_file, the full workflow_spec, and validation as JSON

Example:

ouroboros workflow-ir inspect seed.yaml --json

ouroboros cancel

Cancel stuck or orphaned executions.

cancel execution

Cancel a specific execution, all running executions, or interactively pick from active sessions.

ouroboros cancel execution [OPTIONS] [EXECUTION_ID]

Arguments:

Argument Description
EXECUTION_ID Session/execution ID to cancel. If omitted, enters interactive mode

Options:

Option Description
-a, --all Cancel all running/paused executions
-r, --reason TEXT Reason for cancellation (default: "Cancelled by user via CLI")
-l, --list List active executions and exit without prompting or cancelling

Examples:

# Interactive mode - list active executions and pick one
ouroboros cancel execution

# List active executions without prompting (scripts, agents)
ouroboros cancel execution --list

# Cancel a specific execution by session ID
ouroboros cancel execution orch_abc123def456

# Cancel all running executions
ouroboros cancel execution --all

# Cancel with a custom reason
ouroboros cancel execution orch_abc123 --reason "Stuck for 2 hours"

ouroboros cleanup

Prune residue left behind by auto sessions: managed worktrees under the configured worktree root (default ~/.ouroboros/worktrees/), their ooo/auto_* branches, stale task lock files, and orphaned session state files (~/.ouroboros/data/auto_*.json).

ouroboros cleanup [OPTIONS]

Safety rules:

  • Cleanup retains worktrees with a live or unverifiable task lock. This relies on participants using compatible lock-aware versions, reliable filesystem locking, and unique hostnames across machines that share the worktree root. In particular, two different machines with the same hostname cannot safely share that root.
  • A remote-host lock is retained even if its heartbeat is old; a timestamp cannot prove the remote owner exited. The legacy worktree_lock_stale_after_minutes setting no longer authorizes remote lock recovery. Verify remote ownership and resolve abandoned locks manually before retrying cleanup.
  • A hostname change (including a container or network-dependent hostname change) makes an earlier lock appear to belong to another host. It is retained without automatic reclamation, even on the same machine. Investigate the recorded owner and confirm it is no longer active before manually resolving the lock.
  • Empty, damaged, or unreadable lock records are also retained. Investigate the workspace and its possible owners before manually resolving such a lock; an unreadable record is not evidence that the workspace is idle.
  • Dirty worktrees are never removed, even with --force.
  • Branches are only deleted via safe git branch -d (fully merged); unmerged branches always survive.
  • Without --force, only worktrees whose branch is fully merged are removed.
  • State files are pruned only when the session is terminal and its worktree is gone (default: complete only).

Options:

Option Description
--dry-run Report what would be removed without removing anything
-f, --force Also remove clean worktrees whose branch is not merged yet (branch is kept)
--state-all Prune state files of blocked/failed sessions too (default: complete only)

Examples:

# See what would be cleaned up
ouroboros cleanup --dry-run

# Remove merged-and-clean auto worktrees, stale locks, completed session state
ouroboros cleanup

# Also drop clean-but-unmerged worktrees (their branches survive)
ouroboros cleanup --force

Related: the orchestrator.worktree_cleanup config field (keep | remove | prune-merged, default prune-merged) controls automatic cleanup when a session releases its worktree; ooo cleanup handles residue from sessions that ended before this policy existed, were cancelled, or ran with keep.


ouroboros gui

Serve the Ouroboros console, a local web app for connecting tools, agents and models, providers, runs and chat, and open it in the browser. If a console is already running, a second invocation opens that one instead of starting another. See the console guide.

ouroboros gui [OPTIONS]

Options:

Option Description
-p, --port INTEGER Port to serve on (default 10300, or any free port when 10300 is busy)
--host TEXT Bind address (default 127.0.0.1). A non-loopback address such as 0.0.0.0 makes the console reachable from other machines; the printed URL then carries the access token
--no-browser Print the URL without opening a browser
--page TEXT Page to open, e.g. models, integrations, chat

Examples:

# Open the console
ouroboros gui

# Open the Agents & models page
ouroboros gui --page models

# Serve on another port without opening a browser
ouroboros gui --port 10400 --no-browser

ouroboros service

Run the console, and the shared streamable-http MCP server it supervises, at login: a launchd agent on macOS or a systemd user unit on Linux.

ouroboros service COMMAND [OPTIONS]
Command Description
install Install and start the login service
uninstall Stop and remove the login service
status Show whether the login service is installed and running

service install

Options:

Option Description
-p, --port INTEGER Console port (default 10300)

Examples:

ouroboros service install
ouroboros service status
ouroboros service uninstall

ouroboros config

Manage Ouroboros configuration.

Running ouroboros config with no subcommand opens the settings GUI — the terminal settings app in a real terminal, or the browser console's Agents & models page (ouroboros gui, see the console guide) inside an agent session or with --web. Both include one-click routing presets — multi-LLM stage-routing recommendations that stage which agent runs each pipeline stage (interview → execute → evaluate → reflect). Click a preset, review the per-stage Agent cards, then Save to persist into orchestrator.runtime_profile.stages. The shipped presets:

Preset interview execute evaluate reflect Rationale
All Claude claude claude claude claude Single-vendor baseline — one subscription, predictable
Claude+Verify claude claude antigravity claude Cross-vendor verification — an independent vendor grades the work
Tri-Vendor claude claude antigravity grok Maximum diversity across generate / verify / diverge
Codex Core codex codex claude grok OpenAI-centric execution with a cross-vendor verify gate
Frugal Mix antigravity grok antigravity codex Cost/speed-leaning mix (Gemini Flash via agy, fast Grok)

The spine of these recommendations is vendor diversity between the generate stage (execute) and the verify stage (evaluate). The persisted consensus.diversity_required setting is currently inert and does not enforce provider diversity; verify the effective providers for your configuration. A preset may reference a backend whose CLI is not installed; staging still works and the per-card warning flags it. Pick the preset closest to your subscriptions, then tune individual cards. Model presets (Auto / Frugal / Standard / Frontier) sit in the Defaults band and set the one models.default switch; the field under them takes any model id. The Pin per-role model ids switch sets models.pin, and the per-stage model ids it applies are grouped under Advanced.

config show

Display current configuration summary, or a specific section.

The summary includes a models table: one row per role (the check package runs on the Execute model) with its tier, backend, resolved model, and source (auto, pin, invocation, configured, or shipped_fallback), under a models: auto (pin off), models: pinned, or models: <value> for every role (<source>) header. Saved per-role model ids that are not applied because pin is off are listed under ignored (pin off), each with the hint set models.pin: true to use. --json emits the same data under the models key.

ouroboros config show [SECTION]

Arguments:

Argument Description
SECTION Configuration section to display (e.g., orchestrator, llm, consensus)

Examples:

# Show configuration summary (backend, models, CLI path, DB, log level)
ouroboros config show

# Machine-readable view; the models table is under the "models" key
ouroboros config show --json

# Show only orchestrator section
ouroboros config show orchestrator

config backend

Show or switch the runtime backend by delegating to that backend's setup flow. The setup policy decides whether llm.backend also changes. Runtime-only backends such as Antigravity, Grok, and Zcode always update only the orchestrator runtime and preserve the existing completion backend.

ouroboros config backend [BACKEND]

Arguments:

Argument Description
BACKEND Backend to switch to: claude, codex, gemini, zcode, hermes, goose, pi, omp, gjc, antigravity, or grok. Omit to show current. For opencode, use ouroboros setup instead

Examples:

# Show current backend
ouroboros config backend

# Switch to Codex CLI
ouroboros config backend codex

# Switch to Claude Code
ouroboros config backend claude

# Switch to Hermes
ouroboros config backend hermes

# Switch to the runtime-only Zcode backend without changing llm.backend
ouroboros config backend zcode

config init

Initialize Ouroboros configuration.

ouroboros config init

Creates ~/.ouroboros/config.yaml and ~/.ouroboros/credentials.yaml with default templates. Sets chmod 600 on credentials.yaml. If the files already exist they are not overwritten.

config set

Set a configuration value using dot notation.

ouroboros config set KEY VALUE

Arguments:

Argument Required Description
KEY Yes Configuration key (dot notation)
VALUE Yes Value to set

Boolean settings accept true/false, 1/0, yes/no, on/off, t/f, and y/n (case-insensitive). Other values, including empty strings and values with surrounding whitespace, are rejected with a nonzero exit code; the configuration file and any existing undo backup remain unchanged.

A successful save keeps the previous configuration file as config.yaml.bak. Use ouroboros config undo to restore it. Rejected values and recoverable write failures preserve the current configuration and the existing backup.

Examples:

# Change log level
ouroboros config set logging.level debug

# Override LLM backend separately from runtime backend
ouroboros config set llm.backend litellm

# One model switch for every role: auto, frugal, standard, frontier, or a model id
ouroboros config set models.default frontier

# Run the per-role model ids saved in config (research and reproducibility)
ouroboros config set models.pin true

config undo

Restore the configuration before the last successful settings GUI save or config set. This is a one-step history: run the same command again to redo. The backup must pass configuration validation before it can be restored.

ouroboros config undo   # Restore the previous configuration
ouroboros config undo   # Redo the change

config validate

Validate current configuration. Checks that the runtime backend is supported and the CLI binary path exists.

ouroboros config validate

ouroboros codex

Manage Codex-specific Ouroboros integration artifacts.

codex refresh

Refresh the packaged Codex-side Ouroboros rules and skills without changing MCP or Ouroboros config files.

ouroboros codex refresh

This command updates packaged ~/.codex/rules/ouroboros*.md and ~/.codex/skills/ouroboros-* artifacts. It does not modify ~/.codex/config.toml or ~/.ouroboros/config.yaml. It intentionally does not prune extra ouroboros-* files because prefix ownership can include user-managed artifacts.

ouroboros zcode

Convenience commands that run init start, qa, and run workflow with Zcode selected for that invocation, without changing ~/.ouroboros/config.yaml. For a persistent default, use ouroboros setup --runtime zcode. The standalone ozo entry point runs this same command group. When OUROBOROS_ZCODE_CLI_PATH is unset and /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs exists, that path is used.

Shorthand: ouroboros zcode "context" is equivalent to ouroboros zcode start "context". Unless one of the arguments is a subcommand name (start, qa, run) or --help, all of them go to start.

zcode start

Start an interview with Zcode as both the LLM backend and the workflow runtime (init start --orchestrator --runtime zcode --llm-backend zcode).

ouroboros zcode [start] [OPTIONS] [CONTEXT]
Option Description
-r, --resume TEXT Resume an existing interview by ID
--state-dir DIRECTORY Custom directory for interview state files
-d, --debug Show verbose logs

zcode qa

Evaluate text or a file with ouroboros qa, using Zcode as the LLM backend.

ouroboros zcode qa [OPTIONS] ARTIFACT
Option Description
-q, --quality-bar TEXT Plain-language description of what PASS means (default: PASS if this is clear, correct, and useful.)
-t, --artifact-type TEXT code, document (default), api_response, screenshot, test_output, or custom
-r, --reference TEXT Optional reference text or file path
--pass-threshold FLOAT Score threshold for PASS, from 0.0 to 1.0 (default: 0.8)

zcode run

Run a Seed with run workflow in orchestrator mode and Zcode as the execution runtime. The LLM backend is left as configured.

ouroboros zcode run [OPTIONS] SEED_FILE
Option Description
--project-dir DIRECTORY Project directory to run in
-r, --resume TEXT Resume a previous orchestrator session by ID
--no-qa Skip post-execution QA evaluation
-d, --debug Show verbose logs
-s, --sequential Execute acceptance criteria sequentially
--max-decomposition-depth INTEGER Maximum recursive split depth; depths above 4 use legacy execution

Example:

ouroboros zcode "Build a REST API"

ouroboros qa

Run a general-purpose QA verdict over an artifact using the same implementation as the ouroboros_qa MCP tool.

ouroboros qa ARTIFACT [OPTIONS]

ARTIFACT may be literal text or a path to a file. --reference and --seed-content accept the same literal-or-file behavior.

For an in-process QA evaluation, the returned QA session ID can be passed to ouroboros_session_status to read the last completed evaluation's score and verdict. That status describes the last completed evaluation, not an active or failed later attempt. The QA status record stores the score summary, not the artifact, reference, prompt, or model response. The auto_ ID prefix is reserved for auto sessions; a QA ID that conflicts with another session is reported as an error. Plugin delegation retains its host-owned lifecycle.

Standalone ouroboros qa writes its score summary to the configured default EventStore (persistence.database_path, with the existing legacy database fallback at ~/.ouroboros/ouroboros.db). A failed write fails the command; a computed verdict alone is not a completed, queryable evaluation. Query the ID using a server connected to that same database. mcp serve --db X uses X for synchronous, background, and embedded post-execution QA. Embedded run, auto, and evolve QA reuse their owner's store without opening a second default database. The standalone command does not inherit another server's --db option.

Options:

Option Description
-q, --quality-bar TEXT Natural-language description of what PASS means
-t, --artifact-type TEXT Artifact type, such as code, api_response, document, screenshot, test_output, or custom
-r, --reference TEXT Optional reference text or path for comparison
--pass-threshold FLOAT Score threshold for PASS verdict, from 0.0 to 1.0
--qa-session-id TEXT Existing QA session ID for iterative checks
--seed-content TEXT Optional Seed YAML text or path for additional context

Exit codes:

Code Meaning
0 QA completed and the verdict passed
1 QA handler failed before producing a verdict
2 QA completed and the verdict did not pass

ouroboros uninstall

Cleanly remove all Ouroboros configuration from your system. Reverses everything ouroboros setup did.

ouroboros uninstall [OPTIONS]

Options:

Option Description
--keep-data Keep entire ~/.ouroboros/ directory (config, credentials, seeds, logs, DB)
--dry-run Show what would be removed without actually deleting
-y, --yes Skip confirmation prompt

Examples:

# Interactive uninstall (shows what will be removed, asks for confirmation)
ouroboros uninstall

# Non-interactive
ouroboros uninstall -y

# Preview only
ouroboros uninstall --dry-run

# Remove MCP/artifacts but keep ~/.ouroboros/
ouroboros uninstall --keep-data

What it removes:

  • ouroboros entry from ~/.claude/mcp.json
  • [mcp_servers.ouroboros] section from ~/.codex/config.toml
  • ~/.codex/rules/ouroboros*.md and ~/.codex/skills/ouroboros-*
  • <!-- ooo:START --> … <!-- ooo:END --> block from CLAUDE.md
  • OpenCode bridge plugin (<opencode_config_dir>/plugins/ouroboros-bridge/) and its entry in opencode.jsonc
  • .ouroboros/ directory in the current project
  • ~/.ouroboros/ directory (unless --keep-data)

What it does NOT remove:

  • The Python package — run pip uninstall ouroboros-ai or uv tool uninstall ouroboros-ai separately
  • The Claude Code plugin — run claude plugin uninstall ouroboros separately
  • Your project source code or git history

See UNINSTALL.md for the full guide.


ouroboros update

Update Ouroboros to the latest version. Native counterpart of the ooo update skill — works in any shell, with no AI session required.

ouroboros update [OPTIONS]

Options:

Option Type Default Description
--check flag off Only report installed vs latest version — change nothing
-y, --yes flag off Skip confirmation prompt (for scripts)
--dry-run flag off Show the commands that would run without executing them
--prerelease / --no-prerelease flag auto Include pre-releases (default: only when a pre-release is installed)
-r, --runtime text auto Runtime integration to refresh after upgrading. all refreshes Claude and Codex without changing the configured backend; auto preserves the configured backend; none skips refresh

Examples:

# Version check only
ouroboros update --check

# Interactive update
ouroboros update

# Non-interactive (scripts, CI)
ouroboros update -y

# Preview the commands without running them
ouroboros update --dry-run

# Refresh both Claude Code and Codex integrations
ouroboros update --runtime all -y

# Upgrade the package but skip runtime integration refresh
ouroboros update --runtime none -y

What it does:

  1. Compares the installed version against the latest on PyPI (pre-release aware)
  2. Reads the running environment's local uv or pipx receipt and replays it through that manager, preserving the exact environment and recorded extras/additional requirements
  3. Verifies that the same environment's console reports at least the target version before changing any runtime integration
  4. Refreshes the selected host plugin integration
  5. Re-runs ouroboros setup --runtime <rt> --non-interactive for a single selected runtime, or ouroboros setup refresh for --runtime all

For a uv installation, the updater first checks the active root package's recorded version constraint against the selected PyPI target. A conflicting pin, bound, or exclusion exits with code 1 before confirmation or package mutation, including with --dry-run. The diagnostic identifies the constraint, target and receipt, and explains how to deliberately revise the original install command while preserving its uv root, executable directory, Python, extras, additional requirements and index/options. It never removes the constraint or rewrites the receipt. Compatible ranges and wildcards retain the normal upgrade path; additional packages' constraints are left to uv. --check remains a version-only query and does not inspect the installation receipt. Package upgrade success is reported only after the installed version has been verified.

Older environments without packaging can still start the updater, check versions, and upgrade unconstrained uv installations. If their receipt contains a root constraint or marker, validation stops before mutation with a diagnostic to restore packaging using the original manager and installation options. The updater does not guess whether that constraint permits the target.

If the package upgrade is verified but a required integration refresh fails, the command reports a partial update and exits with code 1. Each failed step prints its recovery command, including the selected executable and any explicit runtime CLI override. Codex setup retains --preserve-existing-llm; OpenCode setup retains the selected mode. After resolving the reported cause, run the commands in the same environment so settings such as HOME and CODEX_HOME still select the original installation. Windows instructions use PowerShell; other platforms use a POSIX shell. Apply any listed follow-up command only after the preceding command succeeds. In PowerShell, check $LASTEXITCODE for the native command's result only after the executable actually starts; the environment-restoration block can change $?. PowerShell errors while starting the executable or preparing the recovery helper are failures even if an earlier $LASTEXITCODE is still 0. Resolve those errors before running any follow-up command.

Once the package is current, rerunning ouroboros update exits as up to date without retrying failed integration refreshes. Use the printed recovery commands instead. This guidance does not repair a failed package-manager upgrade.

With --runtime auto (the default), an existing configured backend is preserved. Only an unconfigured installation probes for the claude CLI first and then codex; when neither is found the runtime refresh is skipped with a notice and the package upgrade still completes. Existing OpenCode integrations also preserve their mutually exclusive plugin or subprocess mode. Runtime executable selection preserves the supported environment override before the persisted orchestrator.*_cli_path, then PATH; the exact validated executable is reused for plugin and setup refresh so a stale PATH binary cannot replace it. Runtime setup and the post-update version check always use the console script inside the same proven package environment, including .exe/PATHEXT launcher resolution on native Windows.

With --runtime all, the updater refreshes the Claude plugin, the Codex Ouroboros marketplace, and all previously installed runtime artifacts through ouroboros setup refresh. This path does not rewrite the configured execution backend. Claude can apply the new plugin with /reload-plugins or a restart; active Codex sessions must restart because Codex does not currently retain an in-use plugin generation during marketplace cache rotation.

When Codex is selected (--runtime codex, auto resolving to Codex, or all), the updater also reports the installed ouroboros@ouroboros plugin version. This read-only check runs after runtime refresh and on --check or an already current package. It queries the same configured Codex executable with plugin list --marketplace ouroboros --json, rather than inferring an installed version from available releases or cached directories. After an upgrade, the comparison uses the newly verified package version.

A different plugin version produces a warning with both versions. Inspect the marketplace ref before deciding whether to update that integration: a pinned release may intentionally differ, and refreshing the same pinned ref will not advance it. The diagnostic never changes refs or configuration, and does not certify the version loaded by an already-running Codex session or MCP server. An unavailable CLI, unsupported command, five-second timeout, or unreadable inventory is reported as unknown, separately from not installed. Inventory with more than 64 nested object/array containers (including the root) is also unknown, consistently across supported Python versions. These advisory results do not change the update command's exit status. An editable package reporting 0.0.0 is shown without inferring version drift. Other selected runtimes, --runtime none, and --dry-run skip this query.

Installation identity: the updater does not guess from global tool lists, PATH order, directory names, or the selected runtime. If the receipt is missing or ambiguous, the owning manager is unavailable, or a direct pip install cannot prove its requested extras, it exits without changing anything and asks you to reinstall with the exact original profile.

The [claude] extra is never combined with or substituted for [mcp] — the Claude Agent SDK embeds MCP 1.x while the protocol server requires MCP 2. MCP hosts launch their own isolated ouroboros-ai[mcp] process via uvx/pipx run.


ouroboros doctor

Read-only diagnostics for an Ouroboros installation. For MCP server diagnostics, see mcp doctor.

doctor install

Inspect the package, plugin, and MCP install surfaces without writing any file: the running package, the Codex personal plugin and its MCP launcher, the Claude Code plugin and its MCP launcher, a user-level ouroboros entry in ~/.claude/mcp.json, and the ZCode bridge plugin and launcher. Each surface is reported as OK, WARN, or FAIL, with its path, launcher, and a hint when one applies. A Codex or Claude Code plugin manifest whose version differs from the running package is a warning. The command exits with status 1 if any surface fails.

ouroboros doctor install [OPTIONS]
Option Description
--json Emit the surfaces as a JSON array on stdout

Example:

ouroboros doctor install --json

ouroboros status

Check Ouroboros system status.

Current state: all status subcommands are read-only. status executions and status execution read the configured EventStore when it exists, falling back to the default runtime store at ~/.ouroboros/ouroboros.db; status run provides the richer Run/Stage/Step projection, and status project rebuilds complete cross-run Project Map status.

status auto

Show unified ooo auto + Ralph handoff status for an auto session.

ouroboros status auto AUTO_SESSION_ID

Arguments:

Argument Required Description
AUTO_SESSION_ID Yes Auto session id to inspect, such as auto_<hex>

status run

Build a read-only Run/Stage/Step projection from persisted events. Provide at least one selector: a positional RUN_ID (treated as the execution anchor), --execution-id, or --session-id. The command is a thin surface over the ouroboros_query_projection MCP tool — --json output is byte-identical to what the MCP query returns for the same anchor.

ouroboros status run [RUN_ID] [--session-id TEXT] [--execution-id TEXT] [OPTIONS]

Arguments:

Argument Required Description
RUN_ID No Positional execution anchor; maps to execution_id. Cannot be combined with --session-id or a conflicting --execution-id

Options:

Option Description
--session-id TEXT Orchestrator session ID to project; required unless RUN_ID or --execution-id is provided. May be combined with --execution-id when the MCP projection handler needs session narrowing
--execution-id TEXT Execution aggregate ID to project; required unless RUN_ID or --session-id is provided. May be combined with --session-id for session narrowing
--seed-id TEXT Optional seed ID override for projection labels
--limit INTEGER Optional event count safety cap
--json Emit machine-readable projection JSON

Exit codes (Wave-1 #946 S2 contract):

Code Meaning
0 Projection rendered successfully
1 Generic projection failure surfaced by the MCP handler
2 Unknown run anchor — no events match the requested RUN_ID / selectors
64 Malformed input — missing selectors or conflicting RUN_ID / option combination

status project

Rebuild complete run status for the project containing PROJECT_DIR (or the current directory when omitted). This command and the read-only ouroboros_project_status MCP tool use the same handler. --json therefore emits the exact MCP structuredContent ProjectRecord.

ouroboros status project [PROJECT_DIR] [--workspace PATH] [--limit N] [--json]
Option Description
--workspace PATH Filter to one canonical project-relative workspace after validating all project identity candidates
--limit N Complete-run safety cap (default 100); an undersized limit fails instead of truncating
--json Emit deterministic ProjectRecord JSON identical to the MCP structured result

The project record also includes ambiguity-gate provenance for the Seeds in the recorded project runs: gated_seed_count (normal gate passes), forced_seed_count (force=True), unknown_seed_count (legacy or otherwise unrecorded decisions), and override_rate. The rate is forced_seed_count / (forced_seed_count + gated_seed_count); it is null in JSON and shown as n/a when there are no known decisions. Unknown entries do not contribute to the denominator.

The command performs no writes or schema creation. Identity conflicts, projection failures, and undersized limits return exit code 1 with no partial record; malformed CLI limits or workspace values return exit code 64.

status health

Check local system health. The command validates configuration, checks the configured database path, verifies the effective runtime CLI is reachable after applying OUROBOROS_AGENT_RUNTIME / OUROBOROS_RUNTIME and runtime-specific OUROBOROS_*_CLI_PATH overrides, and confirms that credentials for the active LLM provider are present without printing key material. CLI-authenticated backends such as Copilot are reported as local CLI authentication rather than requiring an API key.

For file-backed credentials, status health reads credentials.yaml as UTF-8. Invalid UTF-8, invalid YAML, and read failures produce fixed diagnostics without including parser excerpts or the underlying read exception. A credential-presence check still does not verify authentication.

ouroboros status health

status health exits with status 0 when no check is error; it exits with status 1 if any check is error. Warnings, such as a missing database file that will be created on first run or an empty template credential value, are rendered in the table but do not fail the command.

Representative Output:

                   System Health
+--------------------------------------------+---------+
| Name                                       | Status  |
+--------------------------------------------+---------+
| Configuration — ~/.ouroboros/config.yaml   |   ok    |
| Database — data/ouroboros.db (...)         |   ok    |
| Runtime backend — claude: /usr/bin/claude  |   ok    |
| Credentials — anthropic key present        |   ok    |
+--------------------------------------------+---------+

status executions

List recent executions with status information.

ouroboros status executions [OPTIONS]

Options:

Option Description
-n, --limit INTEGER Number of executions to show (default: 10)
-a, --all Show all executions

Examples:

# Show last 10 executions
ouroboros status executions

# Show last 5 executions
ouroboros status executions -n 5

# Show all executions
ouroboros status executions --all

status execution

Show details for a specific execution.

ouroboros status execution [OPTIONS] EXECUTION_ID

Arguments:

Argument Required Description
EXECUTION_ID Yes Execution ID to inspect

Options:

Option Description
-e, --events Show execution events

Examples:

# Show execution details
ouroboros status execution exec_abc123

# Show execution with events
ouroboros status execution --events exec_abc123

ouroboros tui

Interactive TUI monitor for real-time workflow monitoring.

Equivalent invocations: ouroboros tui (no subcommand), ouroboros tui monitor, and ouroboros monitor are all equivalent — they all launch the TUI monitor.

tui monitor

Launch the interactive TUI monitor to observe workflow execution in real-time.

Terminal recording of ooo tui monitor: a session list with goals and statuses, selecting a session to show its AC execution tree with three failed criteria, then the event log listing received execution events
Session list → AC execution tree for one session → event log (execution.plan.created, execution.ac.capsule.compiled, …)

ouroboros tui [monitor] [OPTIONS]

Options:

Option Description
--db-path PATH Override the shared EventStore path (default: resolved from persistence.database_path, with the legacy database fallback)
--backend TEXT TUI backend to use: python (Textual, default) or slt (native Rust binary)

Examples:

# Launch TUI monitor (default Textual backend)
ouroboros tui monitor

# Override the shared database path for this monitor
ouroboros tui monitor --db-path ~/.ouroboros/ouroboros.db

# Use the native SLT backend (requires ouroboros-tui binary)
ouroboros tui monitor --backend slt

Note: The slt backend requires the ouroboros-tui binary in your PATH. Install it with:

cd crates/ouroboros-tui && cargo install --path .

TUI Screens:

Key Screen Description
1 Dashboard Overview with phase progress, drift meter, cost tracker
2 Execution Execution details, timeline, phase outputs
3 Logs Filterable log viewer with level filtering
4 Debug State inspector, raw events, configuration
s Session Selector Browse and switch between monitored sessions
e Lineage View evolutionary lineage across generations (evolve/ralph)

Keyboard Shortcuts:

Key Action
1-4 Switch to numbered screen
s Session Selector
e Lineage view
q Quit
p Pause execution — hidden in tui monitor
r Resume execution — hidden in tui monitor
Up/Down Scroll

Note: ouroboros tui monitor observes the event store and does not own the running execution, so the pause/resume bindings are hidden there. Use ouroboros cancel execution to stop a run. See TUI Usage for details.


ouroboros mcp

MCP (Model Context Protocol) server commands for Claude Desktop and other MCP-compatible clients.

mcp doctor --machine-snapshot

Run read-only MCP environment diagnostics. The default command prints health checks; --json emits the existing list of checks. Add --machine-snapshot to opt into a typed, content-free static snapshot; with --json, the result is an object containing the existing checks list and machine_snapshot fields.

The snapshot covers OS, architecture, Python, current executable, installed ouroboros-ai version/location, home-directory disk usage, and fixed ~/.ouroboros/config.yaml lstat metadata. It never reads configuration contents or credentials, invokes commands, scans PATH, inspects processes, probes ports or networks, writes files, or repairs anything. Missing, permission, unsupported, and unexpected probe failures are reported as not_checked with stable reasons. Native Windows machine architecture is explicitly not_checked rather than inferred from shell commands or environment variables. PATH collisions, loopback/port checks, and owned-process metadata are outside this static snapshot.

ouroboros mcp doctor [--json] [--machine-snapshot]

mcp doctor-runtime

Show bounded, read-only runtime metadata for local MCP diagnostics. --json emits typed fields for fixed PATH executable provenance and collisions, ephemeral IPv4/IPv6 loopback bindability, and metadata for Ouroboros's own MCP PID registry.

Human-readable output shows the bounded executable candidates and collisions, unavailable reasons, loopback results, and each registry record's metadata. The registry location is displayed using the stable label ~/.ouroboros/mcp-servers; the resolved absolute home path is not included.

The command reads only PATH and the home-location information used by the server's normal Path.home() lookup (including a HOME override on POSIX). The resolved home and absolute registry path are used only for the bounded registry lookup; neither value is included in output or stored. PATH candidate and collision paths under that home are displayed with a ~ prefix in both JSON and human output after lexical dot-segment normalization; paths outside that home retain their location provenance. It reads no configuration, registry contents, process arguments, or credentials, executes no commands, connects to no network, and does not mutate the machine. PATH and registry scans have fixed bounds. Loopback probes only bind an ephemeral socket and close it immediately. An invalid or unresolvable home location reports registry status not_checked with reason owner_unavailable, without including the location or exception details.

ouroboros mcp doctor-runtime [--json]

mcp serve

Start the MCP server to expose Ouroboros tools to Claude Desktop or other MCP clients.

ouroboros mcp serve [OPTIONS]

Options:

Option Description
-h, --host TEXT Host to bind to (default: localhost)
-p, --port INTEGER Port to bind to (default: 8080)
-t, --transport TEXT Transport type: stdio, sse, or streamable-http (default: stdio). Note: http is only a client config alias for outbound MCP connections and is NOT a valid serve transport.
--auth-token TEXT Shared secret clients present as Authorization: Bearer <token>. Required for a network transport on a non-loopback host. Prefer the OUROBOROS_MCP_AUTH_TOKEN environment variable — a token on the command line is visible to every process on the machine through ps.
--allow-remote Acknowledges that a non-loopback bind exposes seed execution beyond this machine. Required alongside --auth-token to serve on a routable address.
--allowed-host TEXT Host header value clients will use, e.g. ouroboros.internal:8080. Repeatable. Required for wildcard binds (--host 0.0.0.0), whose reachable name cannot be inferred. A :* suffix allows any port.
--allowed-origin TEXT Origin header value to permit. Repeatable. Empty by default, which rejects every browser-originated request.
--workspace-root TEXT Confines seed execution to directories under this path. Repeatable. Strongly recommended for network binds; unset means a caller may name any existing directory on the machine as an agent working tree.
--db TEXT Path to the EventStore database file
--runtime TEXT Agent runtime backend for orchestrator-driven tools (claude, claude-sdk, claude-cli, codex, opencode, hermes, gemini, copilot, goose, kiro, pi, omp, gjc, antigravity, grok, zcode). The MCP 2 server rejects SDK-backed claude/claude-sdk; use claude-cli for its out-of-process Claude worker.
--llm-backend TEXT LLM backend for interview/seed/evaluation tools (claude_code, litellm, codex, copilot, opencode, gemini, goose, kiro, pi, omp, zcode, dsh, megacode). Affects which tool variants are instantiated

Examples:

# Start with stdio transport (for Claude Desktop)
ouroboros mcp serve --runtime claude-cli

# Start with SSE transport on custom port
ouroboros mcp serve --runtime claude-cli --transport sse --port 9000

# Start with streamable HTTP transport on custom port
ouroboros mcp serve --runtime claude-cli --transport streamable-http --port 9000

# Start with Codex-backed orchestrator tools
ouroboros mcp serve --runtime codex --llm-backend codex

# Serve to other machines. Every flag below is required, not optional:
# the bind is refused without them.
export OUROBOROS_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
ouroboros mcp serve --runtime claude-cli \
  --transport streamable-http --host 0.0.0.0 --port 8080 \
  --allow-remote \
  --allowed-host ouroboros.internal:8080 \
  --workspace-root /srv/ouroboros/projects

For serving with streamable HTTP, use streamable-http, not http. http is accepted only in MCP client configuration as a compatibility alias for dialing another server's streamable HTTP endpoint; mcp serve uses the precise protocol name so users do not confuse it with a generic HTTP API. Streamable HTTP clients should connect to http://<host>:<port>/mcp.

When --runtime is omitted, mcp serve inherits the configured runtime and ultimately the default [claude] Agent SDK profile. Because the server process uses MCP 2, it fails closed before startup if that effective runtime is SDK-backed. Pass an explicit MCP-2-compatible runtime or persist one with ouroboros setup.

MCP SDK server caveats: Network serving uses the SDK v2 MCPServer API. The streamable HTTP path is /mcp.

Network exposure:

Reaching an Ouroboros MCP port is enough to call ouroboros_execute_seed, which runs caller-supplied seed YAML through a real agent runtime with that runtime's full file and shell authority. The port is therefore as privileged as a shell on the host, and mcp serve treats it that way.

The default bind — stdio, or localhost for a network transport — needs no credentials: the client already owns the process, and Ouroboros supplies explicit DNS-rebinding protection settings for loopback binds (keeping an empty Origin policy fail-closed rather than inheriting the SDK's permissive browser-origin defaults).

A bind that other machines can reach is refused unless all of the following are supplied:

  • --auth-token (or OUROBOROS_MCP_AUTH_TOKEN), enforced by the SDK's bearer-auth middleware. Requests without a valid token get 401 before any tool dispatch.
  • --allow-remote, an explicit acknowledgement of the exposure.
  • --allowed-host for wildcard binds, which pins the Host allowlist that blocks DNS rebinding. A forged Host gets 421.

--workspace-root is not required but should be treated as such for any shared deployment: without it a caller may name any existing directory on the host as an agent's working tree.

Rate limiting (RateLimitConfig) is available once an auth method is configured, because the token supplies the per-client identity it buckets by. Without authentication it is refused rather than silently sharing one bucket across all callers.

Scoped IPv6 addresses (those with a zone identifier such as fe80::1%eth0) cannot be used as network bind addresses when authentication is configured. The MCP SDK's Pydantic URL parser does not accept zone identifiers in URL authorities — neither raw nor percent-encoded — so authentication metadata (issuer and resource server URLs) cannot be constructed. Ouroboros rejects scoped IPv6 binds at startup with a clear error. This applies both to non-loopback scoped addresses (where auth is mandatory) and to scoped loopback addresses (e.g. ::1%lo) when an auth token is explicitly passed or inherited from environment configuration. Unauthenticated scoped loopback addresses remain usable since they do not require AuthSettings construction. To resolve: use the address without a zone ID (e.g. ::1 instead of ::1%lo), bind to a non-link-local address, or remove the auth token for loopback use.

Startup behavior:

On startup, mcp serve automatically cancels any sessions left in RUNNING or PAUSED state for more than 1 hour. These are treated as orphaned from a previous crash. Cancelled sessions are reported on stderr for stdio and on the console for network transports (sse, streamable-http). This cleanup is best-effort and does not prevent the server from starting if it fails.

MCP host integration:

ouroboros setup --runtime claude configures the default Agent SDK profile (runtime_backend: claude) on MCP 1.x. claude-sdk is an explicit alias; ouroboros setup --runtime claude-cli selects the dependency-free worker used inside an MCP 2 server environment. Setup leaves ~/.claude/mcp.json untouched; the marketplace plugin launches an isolated server equivalent to:

{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": ["--isolated", "--python", ">=3.12", "--from", "ouroboros-ai[mcp]", "ouroboros", "mcp", "serve", "--runtime", "claude-cli", "--llm-backend", "claude_code"]
    }
  }
}

If uvx is unavailable, use the package-isolated pipx runner:

{
  "mcpServers": {
    "ouroboros": {
      "command": "pipx",
      "args": ["run", "--spec", "ouroboros-ai[mcp]", "ouroboros", "mcp", "serve", "--runtime", "claude-cli", "--llm-backend", "claude_code"]
    }
  }
}

Runtime selection is configured in ~/.ouroboros/config.yaml (written by ouroboros setup):

orchestrator:
  runtime_backend: claude   # SDK default; isolated MCP 2 launchers use "claude_mcp"

Override per-session with the OUROBOROS_AGENT_RUNTIME environment variable if needed.

mcp doctor

Run fast, read-only environment diagnostics. The default command does not start a server:

ouroboros mcp doctor
ouroboros mcp doctor --json

Use the opt-in local stdio probe when the environment checks pass but an MCP host still cannot discover Ouroboros:

ouroboros mcp doctor --probe-local-stdio

The probe launches this installation's own server with the current Python interpreter in isolated mode, with a temporary home and working directory. It loads the production server composition directly, bypassing shell profiles, project dotenv files, update checks, and normal CLI startup. The child starts with -I -S -B, creates the stdlib asyncio event loop, then installs its Python audit hook before site.main() runs .pth files and sitecustomize. The hook rejects events whose names start with socket., plus subprocess.Popen, os.system, os.exec, os.posix_spawn, os.fork, and os.forkpty. This is a best-effort restriction, not an operating system sandbox. It does not block os.spawn or os.startfile, or every multiprocessing launch path (including direct _posixsubprocess.fork_exec calls without an audit event). Native code and ctypes can bypass the hook, and file writes are not blocked. The hook does not establish that arbitrary installed code cannot access the network or user files. Run it only with a trusted Python environment.

The ordinary doctor checks also run before the probe. They import installed backend packages, which can perform network requests during import; the complete doctor --probe-local-stdio command is therefore not guaranteed to be offline. The probe reports stable stages for local startup/stdio transport, protocol discovery, and expected tool recognition. It lists tools but never calls one. The child uses stdio only, disables telemetry, and uses temporary state instead of the normal Ouroboros configuration, EventStore, and PID registry in its intended path. The probe attempts to clean up its child and temporary state on both success and failure. Transport success is observed before protocol discovery, and a cleanup failure causes the probe to fail even when tool discovery succeeded. The three diagnostic stage results remain unchanged; teardown failures add a local_stdio_cleanup failure result and force the overall exit status to 1.

This first diagnostic increment does not probe configured or third-party MCP servers, execute arbitrary launchers, open a network transport, inventory the whole machine, invoke an LLM, or repair the installation. A failed probe is a normal Doctor failure: all emitted stages remain visible and the command exits with status 1.

mcp info

Show MCP server information and available tools.

ouroboros mcp info [OPTIONS]

Options:

Option Description
--runtime TEXT Agent runtime backend for orchestrator-driven tools (claude, codex, opencode, hermes, gemini, copilot, goose, kiro, pi, omp, gjc, antigravity, grok, zcode). Affects which tool variants are instantiated
--llm-backend TEXT LLM backend for interview/seed/evaluation tools (claude_code, litellm, codex, copilot, opencode, gemini, goose, kiro, pi, omp, zcode, dsh, megacode). Affects which tool variants are instantiated

Available Tools:

Tool Description
ouroboros_execute_seed Execute a seed specification
ouroboros_session_status Get the status of a session
ouroboros_project_status Rebuild complete read-only cross-run project status
ouroboros_query_events Query event history

ouroboros plugin

Manage UserLevel plugins. discover, inspect, and list are read-only. add, install, trust, disable, and remove change the lockfile (default ~/.ouroboros/plugins.lock), the trust store (default ~/.ouroboros/trust), or the installed plugin homes (default ~/.ouroboros/plugins). Every subcommand except discover accepts --lockfile PATH and --trust-root PATH to use other locations.

An installed plugin runs as ouroboros <plugin-name> <command> [ARGS]...: a top-level name that is not a built-in command is looked up in the lockfile.

plugin discover

Inspect a plugin manifest without registering it or granting trust. Reads neither the lockfile nor the trust store.

ouroboros plugin discover TARGET

TARGET is a plugin directory or its ouroboros.plugin.json file.

plugin inspect

Show an installed plugin's metadata and trust state, without changing any state.

ouroboros plugin inspect [OPTIONS] NAME
Option Description
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root

plugin list

List installed plugins with their trust state.

ouroboros plugin list [OPTIONS]
Option Description
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root
--json Emit JSON for piping instead of a table

plugin add

Install one or more plugins from a repository URL or a local path. Install strings that point inside a repository (such as ...#plugins/<name>) are rejected.

ouroboros plugin add [OPTIONS] TARGET
Option Description
--plugin TEXT Name of a plugin in the repository catalog, for non-interactive use; repeatable
--cache-root PATH Where to clone repository URLs (default: ~/.ouroboros/cache)
--plugin-home-root PATH Where to install plugin homes (default: ~/.ouroboros/plugins)
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root; used to invalidate prior grants on a version bump
--catalog-state PATH Override the known-catalog state path (default: ~/.ouroboros/plugin-catalogs.json)

plugin install

Install one plugin, non-interactively. TARGET is either a plugin name, resolved through the known catalogs, or a local plugin directory containing ouroboros.plugin.json. A name must be exposed by exactly one known catalog; an ambiguous name fails with the list of candidates, and --from picks one.

ouroboros plugin install [OPTIONS] TARGET
Option Description
--from TEXT Source to install the named plugin from: a repository URL, or an absolute local path (registered on first use)
--plugin-home-root PATH Where to install plugin homes
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root; used to invalidate prior grants on a subject change
--cache-root PATH Where to clone repository URLs for --from (default: ~/.ouroboros/cache)
--catalog-state PATH Override the known-catalog state path (default: ~/.ouroboros/plugin-catalogs.json)

plugin trust

Grant permission scopes to an installed plugin. Scopes are exact strings: one scope does not imply a longer one that starts with it. trust is also how a disabled plugin is re-enabled: a plugin whose manifest declares no permissions can be trusted with no --scope, while one that declares permissions needs at least one.

ouroboros plugin trust [OPTIONS] NAME
Option Description
--scope TEXT Permission scope to grant; repeatable
--granted-by TEXT User identity recorded in the audit trail (default: user:cli)
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root
--audit-log PATH Append plugin.trusted events to this file as JSON Lines (default: not written)

plugin disable

Disable an installed plugin. The disable record survives upgrades, the trust file is wiped, and the lockfile entry stays, so plugin trust can re-enable it.

ouroboros plugin disable [OPTIONS] NAME
Option Description
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root; required when the plugin was trusted under a non-default root

plugin remove

Remove an installed plugin: its lockfile entry, trust file, disable record, and plugin home.

ouroboros plugin remove [OPTIONS] NAME
Option Description
--lockfile PATH Override the lockfile path
--trust-root PATH Override the trust root
--plugin-home-root PATH Remove the plugin home from this root instead of the path recorded in the lockfile

Example:

ouroboros plugin discover ./my-plugin
ouroboros plugin install ./my-plugin
ouroboros plugin list --json

Typical Workflows

For first-time setup and the complete onboarding flow, see Getting Started. For runtime-specific configuration, see the Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro CLI, GitHub Copilot CLI, Pi CLI, OMP CLI, and GJC references.

Cancelling Stuck Executions

# Interactive: list and pick
ouroboros cancel execution

# Cancel all at once
ouroboros cancel execution --all

Environment Variables

The table below covers the most commonly used variables. For the full list — including all per-model overrides (e.g., OUROBOROS_QA_MODEL, OUROBOROS_SEMANTIC_MODEL, OUROBOROS_CONSENSUS_MODELS, etc.) — see config-reference.md.

Variable Overrides config key Description
ANTHROPIC_API_KEY — Anthropic API key for Claude models
OPENAI_API_KEY — OpenAI API key for LiteLLM / Codex CLI
OPENROUTER_API_KEY — OpenRouter API key for consensus and LiteLLM
OUROBOROS_AGENT_RUNTIME orchestrator.runtime_backend Override the runtime backend (claude_mcp for Claude CLI, claude for the isolated SDK runtime, or another supported runtime)
OUROBOROS_RUNTIME orchestrator.runtime_backend (fallback) Shortcut env var honored by both orchestrator.runtime_backend and llm.backend resolution when their dedicated env vars are unset
OUROBOROS_KIRO_CLI_PATH orchestrator.kiro_cli_path Explicit path to kiro-cli binary when it is not on PATH
OUROBOROS_COPILOT_TRANSPORT orchestrator.copilot_transport cli (default) or experimental acp; backend remains copilot. Trusted environment only
OUROBOROS_COPILOT_ACP_FALLBACK orchestrator.copilot_acp_fallback Boolean, default true; read-only/tool-less fallback before prompt submission only. No auth fallback or prompt replay
OUROBOROS_AGENT_PERMISSION_MODE orchestrator.permission_mode Stored runtime preference; runner-driven seed execution forces the native bypassPermissions equivalent for fresh and resumed dispatches wherever the backend exposes an approval surface. OpenCode maps it to --dangerously-skip-permissions; Pi and GJC have no separate approval flag and already run headlessly without an approval dialogue
OUROBOROS_MODEL_TIER_ROUTING — Model-tier routing is enabled by default. Set to 0, off, or false (case- and whitespace-insensitive) to disable it completely
OUROBOROS_SHADOW_REPLAY — Arms the opt-in shadow-baseline experiment only for 1, true, or on. Current live decompositions are quarantined before baseline model dispatch because they lack deterministic MECE attestation; bundled runtimes also lack the required isolation attestation
OUROBOROS_MAX_PARALLEL_WORKERS orchestrator.max_parallel_workers Maximum concurrent Acceptance Criteria workers for parallel execution
OUROBOROS_LEAK_SCAN_MAX_ENTRIES — Entry budget for the pre-worker check-package leak scan. Default: 2000000. A positive integer overrides it; empty, invalid, zero, and negative values use the default. Read when the module is imported; set before starting the process. Exhaustion refuses worker start as an incomplete scan. This is a traversal budget, not a performance guarantee
OUROBOROS_LLM_BACKEND llm.backend Override the LLM-only flow backend
OUROBOROS_CLI_PATH orchestrator.cli_path Path to the Claude CLI binary
OUROBOROS_CODEX_CLI_PATH orchestrator.codex_cli_path Path to the Codex CLI binary
OUROBOROS_OPENCODE_CLI_PATH orchestrator.opencode_cli_path Path to the OpenCode CLI binary
OUROBOROS_GJC_CLI_PATH orchestrator.gjc_cli_path Explicit path to gjc binary when it is not on PATH
OUROBOROS_SESSION_WALL_CLOCK_SECONDS runtime_controls.session_wall_clock_seconds Override the Auto session wall-clock watchdog budget; 0 disables the watchdog
OUROBOROS_MCP_TOOL_TIMEOUT_SECONDS runtime_controls.mcp_tool_timeout_seconds Optional adapter-level MCP timeout; 0 disables the fixed wall-clock cap
OUROBOROS_GENERATION_IDLE_TIMEOUT_SECONDS runtime_controls.generation_idle_timeout_seconds Stop an evolve generation after no lineage/execution activity is observed
OUROBOROS_GENERATION_NO_PROGRESS_TIMEOUT_SECONDS runtime_controls.generation_no_progress_timeout_seconds Stop an evolve generation after activity continues without material progress
OUROBOROS_GENERATION_SAFETY_TIMEOUT_SECONDS runtime_controls.generation_safety_timeout_seconds Optional final hard cap for one generation; 0 disables it
OUROBOROS_WATCHDOG_POLL_SECONDS runtime_controls.watchdog_poll_seconds EventStore polling interval for generation watchdog decisions

Copilot ACP is an exception to runner-requested unrestricted approval: bypassPermissions is capped to acceptEdits, with an exact native tool envelope and one-shot permission decisions.


Configuration Files

Ouroboros stores configuration in ~/.ouroboros/:

File Description
config.yaml Main configuration — see config-reference.md for all options
credentials.yaml API keys (chmod 600; created by ouroboros config init)
ouroboros.db SQLite database for event sourcing. The runtime, status/resume commands, and TUI share persistence.database_path; legacy installs continue using ~/.ouroboros/ouroboros.db until the configured target exists.
logs/ouroboros.log Log output (path configurable via logging.log_path)

Exit Codes

Code Description
0 Success
1 General error