setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# /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 -->
```bash
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:

```bash
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

```bash
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.

From Q00/ouroboros, MIT.

More from Q00/ouroboros