Complete command reference for the Ouroboros CLI.
For install instructions, onboarding, and first-run setup, see Getting Started.
ouroboros [OPTIONS] COMMAND [ARGS]...| Option | Description |
|---|---|
-V, --version |
Show version and exit |
--install-completion |
Install shell completion |
--show-completion |
Show shell completion script |
--help |
Show help message |
For the full first-run walkthrough (interview → seed → execute), see Getting Started.
| 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:
oooandouroborosboth launch the main CLI.ozois a standalone shorthand that launches only the Zcode convenience commands (equivalent toouroboros zcode ...).
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.
--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"}kindisphase(the phase or its progress message changed),question(the interview asked roundround) oranswer(auto answered roundround). Files written before the Seed review was removed may also holdgradeandrepairlines, with thegradefield set; nothing writes them now, andgradeisnullon every new line.phaseis the auto phase at that moment:created,interview,seed_generation,run,complete,blockedorfailed. Older files may also hold the retiredreview,repair,ralph_handoff,evaluateandunstuck_lateralphases.answer_sourcesays where an answer came from:user_goal,repo_fact,existing_convention,user_preference,conservative_default,assumption,non_goal,blockerorrequester.
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.
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_responsein~/.ouroboros/data/interview_<interview_session_id>.json). - In the auto session file (
~/.ouroboros/data/<auto_session_id>.json),auto_answer_log[].sourceisrequester.requester_loghas one entry per question sent to the requester:round,question,draft_source,draft_answer,outcome(answered,timeout,nonzero_exit,empty_answer,invalid_outputorlaunch_failed),used,answer,detailandelapsed_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_askedevent (fieldsround,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 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 100ouroboros 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.yamlExample cancelled CLI retrieval output:
$ ouroboros job result job_auto_docs_cancelled
detached auto cancelled: user requested cancellationExample expired CLI retrieval output:
$ ouroboros job result job_auto_docs_expired
detached auto result artifact: expired seed.yaml
ooo autodoes not accept--opencode-mode. OpenCode mode is selected once at install time viaouroboros setup --opencode-mode <plugin|subprocess>(recorded in~/.ouroboros/config.yaml); the auto CLI reads that persisted value but never exposes it as a flag.
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 codexdoes 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. Ifinterview.startblocks, the timeout originates from the in-process authoring path, not from the Codex CLI. Set realistic expectations when chainingooo autofrom external gateways.
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 |
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-interactiveWhat 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
zcodeand 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_backendto~/.ouroboros/config.yaml - For Claude CLI setup: configures the dependency-free
claude_mcpruntime and leaves~/.claude/mcp.jsonownership to the host/plugin - For explicit
--runtime claude-sdk: preserves the SDK runtime, rejects an MCP 2 environment, and leaves~/.claude/mcp.jsonuntouched - For Codex CLI: sets
orchestrator.codex_cli_pathandllm.backend: codexin~/.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 serveentry with the canonical Codex environment is migrated to the isolated managed launcher; custom executable paths and extra process controls remain untouched. Native Windowsautocreates no MCP child,stdiois refused, and explicithttpwrites 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 execinvocation; it retires only untouched legacy generated profile anchors and preserves user-created Codex profiles - For Codex CLI: reads
codex --helpas 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--helpsucceeds, 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.mdin 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_pathandllm.backend: kiroin~/.ouroboros/config.yaml, and registers the Ouroboros MCP server in~/.kiro/settings/mcp.jsonwithOUROBOROS_RUNTIME=kiro/OUROBOROS_LLM_BACKEND=kirobaked into the entry'senv. The launcher is always isolated throughuvxorpipx 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.mdand configures Ouroboros-launched Copilot child sessions to read it viaCOPILOT_CUSTOM_INSTRUCTIONS_DIRS - For GJC: sets
orchestrator.gjc_cli_pathandllm.backend: gjcin~/.ouroboros/config.yaml - For GJC: installs the
ooobridge extension into<agent-dir>/extensionsand the renderer-generated skill capability guide into<agent-dir>/rules/ouroboros-skill-capability-guide.md - For Zcode: sets
orchestrator.runtime_backend: zcodeandorchestrator.zcode_cli_pathwhile leaving the completion-onlyllm.backendunchanged
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 configorouroboros config --webto 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.tomlremains the Codex MCP/env hookup file; user-created Codex--profilesettings 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 stdioonly when you intentionally want setup to replace it.
ouroboros setup also includes brownfield repository registration helpers:
ouroboros setup scan [SCAN_ROOT]
ouroboros setup list
ouroboros setup defaultouroboros 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.
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.
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 initList 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 --summaryGenerate 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_IDThe 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_120000Run 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 ./docsFor 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 |
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 NAMEList 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.
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.
Execute a workflow from a seed file.
ouroboros run [workflow] [OPTIONS] SEED_FILEArguments:
| 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 4After 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.
Resume a paused or failed execution.
Current state:
run resumeis a placeholder helper. For real orchestrator sessions, useouroboros 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>
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.
Print the latest status for a background job.
ouroboros job status [OPTIONS] JOB_ID| Option | Description |
|---|---|
--view TEXT |
full (default), summary, or compact |
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 |
Print the terminal result for a background job.
ouroboros job result JOB_IDPrint 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 summaryFetch, 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.
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 |
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: .) |
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 30dInspect read-only Workflow IR projections.
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 --jsonCancel stuck or orphaned executions.
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"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_minutessetting 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:
completeonly).
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 --forceRelated: 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.
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-browserRun 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 |
Options:
| Option | Description |
|---|---|
-p, --port INTEGER |
Console port (default 10300) |
Examples:
ouroboros service install
ouroboros service status
ouroboros service uninstallManage 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_requiredsetting 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 onemodels.defaultswitch; the field under them takes any model id. The Pin per-role model ids switch setsmodels.pin, and the per-stage model ids it applies are grouped under Advanced.
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 orchestratorShow 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 zcodeInitialize Ouroboros configuration.
ouroboros config initCreates ~/.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.
Set a configuration value using dot notation.
ouroboros config set KEY VALUEArguments:
| 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 trueRestore 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 changeValidate current configuration. Checks that the runtime backend is supported and the CLI binary path exists.
ouroboros config validateManage Codex-specific Ouroboros integration artifacts.
Refresh the packaged Codex-side Ouroboros rules and skills without changing MCP or Ouroboros config files.
ouroboros codex refreshThis 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.
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.
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 |
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) |
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"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 |
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-dataWhat it removes:
ouroborosentry from~/.claude/mcp.json[mcp_servers.ouroboros]section from~/.codex/config.toml~/.codex/rules/ouroboros*.mdand~/.codex/skills/ouroboros-*<!-- ooo:START -->…<!-- ooo:END -->block fromCLAUDE.md- OpenCode bridge plugin (
<opencode_config_dir>/plugins/ouroboros-bridge/) and its entry inopencode.jsonc .ouroboros/directory in the current project~/.ouroboros/directory (unless--keep-data)
What it does NOT remove:
- The Python package — run
pip uninstall ouroboros-aioruv tool uninstall ouroboros-aiseparately - The Claude Code plugin — run
claude plugin uninstall ouroborosseparately - Your project source code or git history
See UNINSTALL.md for the full guide.
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 -yWhat it does:
- Compares the installed version against the latest on PyPI (pre-release aware)
- Reads the running environment's local
uvorpipxreceipt and replays it through that manager, preserving the exact environment and recorded extras/additional requirements - Verifies that the same environment's console reports at least the target version before changing any runtime integration
- Refreshes the selected host plugin integration
- Re-runs
ouroboros setup --runtime <rt> --non-interactivefor a single selected runtime, orouroboros setup refreshfor--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
pipinstall 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 isolatedouroboros-ai[mcp]process viauvx/pipx run.
Read-only diagnostics for an Ouroboros installation. For MCP server
diagnostics, see mcp doctor.
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 --jsonCheck Ouroboros system status.
Current state: all status subcommands are read-only.
status executionsandstatus executionread the configured EventStore when it exists, falling back to the default runtime store at~/.ouroboros/ouroboros.db;status runprovides the richer Run/Stage/Step projection, andstatus projectrebuilds complete cross-run Project Map status.
Show unified ooo auto + Ralph handoff status for an auto session.
ouroboros status auto AUTO_SESSION_IDArguments:
| Argument | Required | Description |
|---|---|---|
AUTO_SESSION_ID |
Yes | Auto session id to inspect, such as auto_<hex> |
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 |
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.
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 healthstatus 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 |
+--------------------------------------------+---------+
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 --allShow details for a specific execution.
ouroboros status execution [OPTIONS] EXECUTION_IDArguments:
| 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_abc123Interactive TUI monitor for real-time workflow monitoring.
Equivalent invocations:
ouroboros tui(no subcommand),ouroboros tui monitor, andouroboros monitorare all equivalent — they all launch the TUI monitor.
Launch the interactive TUI monitor to observe workflow execution in real-time.
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 sltNote: The
sltbackend requires theouroboros-tuibinary 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 monitorobserves the event store and does not own the running execution, so the pause/resume bindings are hidden there. Useouroboros cancel executionto stop a run. See TUI Usage for details.
MCP (Model Context Protocol) server commands for Claude Desktop and other MCP-compatible clients.
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]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]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/projectsFor 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(orOUROBOROS_MCP_AUTH_TOKEN), enforced by the SDK's bearer-auth middleware. Requests without a valid token get401before any tool dispatch.--allow-remote, an explicit acknowledgement of the exposure.--allowed-hostfor wildcard binds, which pins theHostallowlist that blocks DNS rebinding. A forgedHostgets421.
--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.
Run fast, read-only environment diagnostics. The default command does not start a server:
ouroboros mcp doctor
ouroboros mcp doctor --jsonUse the opt-in local stdio probe when the environment checks pass but an MCP host still cannot discover Ouroboros:
ouroboros mcp doctor --probe-local-stdioThe 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.
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 |
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.
Inspect a plugin manifest without registering it or granting trust. Reads neither the lockfile nor the trust store.
ouroboros plugin discover TARGETTARGET is a plugin directory or its ouroboros.plugin.json file.
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 |
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 |
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) |
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) |
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) |
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 |
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 --jsonFor 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.
# Interactive: list and pick
ouroboros cancel execution
# Cancel all at once
ouroboros cancel execution --allThe 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.
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) |
| Code | Description |
|---|---|
0 |
Success |
1 |
General error |