/setup

name: setup
description: "Guided onboarding wizard for Ouroboros setup"
disable-model-invocation: true

/ouroboros:setup

Guided Ouroboros setup inside a Claude Code session.

> Other runtimes (Codex, Copilot, OpenCode, and others) configure through the > CLI instead, for example `ouroboros setup --runtime codex` or > `ouroboros setup --runtime copilot`. See > [Getting Started](https://github.com/Q00/ouroboros/blob/main/docs/getting-started.md).

Usage

ooo setup
/ouroboros:setup
/ouroboros:setup --uninstall

Claude setup confirms the runtime profile (the Claude Agent SDK on MCP 1.x) and optionally adds an Ouroboros reference block to the project's CLAUDE.md. It deliberately leaves `~/.claude/mcp.json` untouched because marketplace plugin wiring owns that file. `[claude]` and its explicit `[claude-sdk]` alias use MCP 1.x. The plugin launches `[mcp]` in a separate MCP 2 process with the dependency-free `[claude-cli]` worker.

Setup Wizard Flow

Ask questions with the active runtime's `ask_user` capability unless a step says otherwise.

Python Runtime (Required)

Define this resolver in the same shell before any snippet below. It accepts only Python 3.12 or newer (`python3`, then `python`, then uv) and preserves arguments and stdin. Quote every argument passed to `ouroboros_python`.

<!-- ouroboros-python-resolver:start -->

ouroboros_python() {
  if command -v python3 >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 "$@")
    return
  fi
  if command -v python >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python "$@")
    return
  fi
  if command -v uv >/dev/null 2>&1; then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command uv run --no-project --quiet --python '>=3.12' python "$@")
    return
  fi
  printf '%s\n' 'Ouroboros skills require Python >= 3.12 or uv on PATH.' >&2
  return 127
}

<!-- ouroboros-python-resolver:end -->

Step 0.5: Community Support

If `star_asked` is not `true` in `~/.ouroboros/prefs.json`, ask "Ouroboros is free and open-source. A GitHub star helps other developers discover it. Star the repo?" with **Star on GitHub** (run `gh api -X PUT /user/starred/Q00/ouroboros`) and **Skip for now**. After any answer, merge `star_asked: true` into the prefs file, keeping existing keys:

ouroboros_python - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
try:
    with open(path, encoding='utf-8') as f:
        prefs = json.load(f)
    if not isinstance(prefs, dict):
        prefs = {}
except Exception:
    prefs = {}
prefs['star_asked'] = True
with open(path, 'w', encoding='utf-8') as f:
    json.dump(prefs, f, indent=2)
    f.write('\n')
PY

Step 1: Environment Detection

ouroboros_python --version
which uvx 2>/dev/null && uvx --version 2>/dev/null
which claude 2>/dev/null
uv python list 2>/dev/null | grep "cpython-3.1[2-9]"

The resolver already rejects Python below 3.12 and falls back to a uv-managed interpreter; that does not make the `[claude-sdk]` and MCP 2 profiles import-compatible. Report what was found, then:

| Environment | Action | |:------------|:-------| | Python >= 3.12 + Claude CLI | Ready: configure `[claude]` SDK/MCP 1 and skills | | uvx + Python >= 3.12 | MCP-capable elsewhere: use a supported CLI-backed runtime setup for isolated `ouroboros-ai[mcp]` | | Python < 3.12 only | Run `uv python install 3.12`, then re-run `ooo setup` | | No package runner or Ouroboros package | Install uv (below), then re-run `ooo setup` |

Prefer package managers for uv: `pipx install uv`, `pip install --user uv`, or `brew install uv`; the vendor one-liner `curl -LsSf https://astral.sh/uv/install.sh | sh` is the last resort.

**IMPORTANT**: Never install `[mcp,claude]`, `[mcp,claude-sdk]`, or `[all,mcp]` together and never write a direct `ouroboros` or `python -m ouroboros` MCP fallback. MCP 2 launchers must use an isolated `uvx --isolated --python '>=3.12' --from 'ouroboros-ai[mcp]' ...` or `pipx run --spec 'ouroboros-ai[mcp]' ...` process. Only `[mcp,claude-cli]` is supported because the CLI worker is out of process. Do not write an Ouroboros entry to `~/.claude/mcp.json`; the plugin owns that registration.

Step 1.5: Runtime Configuration

Write the Claude runtime selection to `~/.ouroboros/config.yaml`. The welcome gate and the CLI read it; nothing else in this wizard writes it. This step never touches `~/.claude/mcp.json`.

Define `ouroboros_cli` in the same shell as each command below (shell state does not persist between commands):

ouroboros_cli() {
  if command -v ouroboros >/dev/null 2>&1; then
    command ouroboros "$@"
  else
    uvx --isolated --python '>=3.12' --from 'ouroboros-ai' ouroboros "$@"
  fi
}
ouroboros_cli config show orchestrator
ouroboros_cli config show llm

The welcome gate is ready only when `orchestrator.runtime_backend` is `claude` or `claude_mcp` AND `llm.backend` is `claude`. A missing file or section counts as not set.

• Both conditions hold: already configured. Skip to Step 2.
• `runtime_backend` is `claude_mcp` but `llm.backend` is not `claude`: run

`ouroboros_cli setup --runtime claude-cli --non-interactive` (keeps the CLI transport).

• `runtime_backend` is another runtime (for example `codex`): ask the user

whether to switch the default runtime to Claude. If they decline, keep the existing configuration and skip to