4. Install

This guide uses the Claude Code plugin as the default path. The order is login, plugin install, ooo setup, then verification.

Ouroboros 0.51.5upstream d103058feverified 2026-08-14 against docs and code

Diagram of the four install steps: login, plugin, setup, verify — Installation is four steps: login, plugin, setup, verify.

4.1 Prerequisites

Claude Code with plugin support must be installed.
You do not need to set up a global Python environment, but you do need uv: the plugin launches its MCP server through uvx. Any of pipx install uv, pip install --user uv, or brew install uv works.
On Windows, follow the Linux steps inside WSL 2. Git Bash is not WSL 2, and running the install commands there can fail; if WSL itself will not install, see the troubleshooting guide.

Open a Claude Code session in your terminal.

claude

/login

Expected result: after browser authentication, the session shows you are logged in. Without login, later ooo commands will not work.

4.3 Install the plugin

Run the next two commands in a normal terminal, outside Claude Code.

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

Terminal output showing the Ouroboros 0.50.4 plugin installed in Claude Code — Install output captured on 2026-07-16 on Ubuntu 24.04 with Claude Code 2.1.210 and Ouroboros 0.50.4. This screenshot alone is from 0.50.4; the two commands above are unchanged in 0.51.5.

Expected result: claude plugin list shows ouroboros@ouroboros as enabled.

4.4 ooo setup — connect Core over MCP

Open a Claude Code session in the project folder you will work in, and type:

ooo setup

ooo setup selects a runtime profile and saves that choice to ~/.ouroboros/config.yaml. Optionally it adds a command summary to the project's CLAUDE.md. MCP server registration belongs to the plugin you installed in 4.3, so ooo setup leaves ~/.claude/mcp.json untouched.

Expected result: the detected runtimes, Setup complete!, and the config path (~/.ouroboros/config.yaml). Check the MCP connection itself with /mcp in step 4.7. Close Claude Code completely and reopen it after setup.

4.5 Verify

Run this inside the Claude Code session.

ooo help

Expected result: a command list including interview, seed, run, and evaluate. If it does not appear, see chapter 11.

4.6 Update

Run this inside the Claude Code session.

ooo update

Expected result: the current and latest versions are compared and updated to match your install method. Reopen the Claude Code session afterwards.

4.7 Definition of done

claude plugin list shows ouroboros@ouroboros as enabled.
ooo help prints the command list.
Claude Code's /mcp shows the ouroboros server as connected.

Installing from the terminal without Claude Code

The standalone CLI requires Python 3.12 or later and installs from a normal terminal.

pip install ouroboros-ai
ouroboros setup

Other runtimes such as Codex CLI are selected with ouroboros setup --runtime codex. Once that is done, the same ooo commands shown throughout this guide work the same way in that session; the examples are just written from the Claude Code chat window's point of view.