How to Install Ouroboros from PyPI and Run `ooo setup` for Initial Configuration

Install the ouroboros-ai package from PyPI using pip install ouroboros-ai, then execute ooo setup inside a Claude Code session to register the Model-Context-Protocol (MCP) server and initialize your project configuration.

The Ouroboros framework provides an evolutionary AI coding architecture through the Q00/ouroboros repository. Installing from PyPI and running the initial setup wizard connects the Plugin Layer (Claude Code skills) to the Core Layer (local MCP server), enabling the full ooo command suite for both Plugin Mode and Full Mode operations.

Installing Ouroboros from PyPI

The official package is distributed as ouroboros-ai on PyPI. The package metadata and dependencies are defined in pyproject.toml, with the CLI entry point implemented in src/ouroboros/cli/main.py.

Standard Installation with pip

Use pip to install the full-mode package globally or within a virtual environment:

pip install ouroboros-ai

This command installs the necessary dependencies and makes the ouroboros CLI command available in your shell path.

Alternative Installation with uv

For faster resolution and installation, use the uv package manager as documented in docs/cli-reference.md:

uv pip install ouroboros-ai

Both installation methods provide identical functionality and access to the MCP server components required for initial configuration.

Understanding the ooo setup Command

ooo setup is a one-time onboarding wizard that bridges the Plugin Layer and Core Layer of the Ouroboros architecture. According to the implementation in skills/setup/SKILL.md, executed through the wrapper in commands/setup.md, this command performs two critical registration actions:

• Registers the MCP server globally: This wires Claude Code skills to the local Python runtime, enabling the tool-provider services required for all subsequent ooo commands.
• Optionally injects an Ouroboros reference block: Adds configuration context to your project's CLAUDE.md file for better Claude Code integration.

The MCP server lives in the Core Layer alongside immutable data models (Seed, Acceptance-Criteria Tree, Ontology). Registration is mandatory for both Plugin Mode (commands inside Claude Code) and Full Mode (native CLI communication with the local server), as detailed in docs/getting-started.md and docs/architecture.md.

Step-by-Step Installation and Setup Workflow

Follow this sequence to install Ouroboros and complete initial configuration:

1. Install the package from PyPI:

pip install ouroboros-ai

2. Start a Claude Code session:

claude

3. Run the setup wizard inside the Claude Code REPL:

ooo setup

This registers the MCP server globally and optionally updates your CLAUDE.md file with the Ouroboros reference block.

4. Verify the CLI is operational:

ooo help

Full-Mode Setup (Outside Claude Code)

If you prefer using the native CLI directly for scripting or CI pipelines, use the entry point defined in src/ouroboros/cli/main.py:

# Install the package

pip install ouroboros-ai

# Run setup via the native CLI

ouroboros setup

This performs the identical MCP registration as ooo setup but from the shell rather than the Claude Code REPL, enabling Full Mode operation without an active Claude session.

Verifying Your Installation

After running ooo setup, test the complete workflow to ensure the MCP bridge between the Execution Layer and State Layer is functioning:

# Conduct a Socratic interview to extract requirements

ooo interview "Build a task-manager CLI"

# Generate an immutable Seed specification

ooo seed

# Execute the Double-Diamond pipeline

ooo run

If these commands execute without MCP connection errors, your installation and setup are complete. The evolutionary execution engine, Ralph loop, and event-sourced SQLite store are now accessible through the registered server.

Summary

• Install Ouroboros from PyPI using pip install ouroboros-ai or uv pip install ouroboros-ai, as defined in pyproject.toml.
• Run ooo setup inside a Claude Code session to register the MCP server globally and optionally configure CLAUDE.md.
• The setup connects the Plugin Layer (skills) to the Core Layer (MCP server) according to the architecture in docs/architecture.md.
• Verify the installation by running ooo help or executing the interview-seed-run workflow.
• Use ouroboros setup (native CLI) instead of ooo setup (skill) when operating outside Claude Code in Full Mode.

Frequently Asked Questions

Do I need to run ooo setup for every new project?

No. ooo setup registers the MCP server globally on your machine, so you only need to run it once per development environment. However, you may optionally re-run it to inject the Ouroboros reference block into a specific project's CLAUDE.md file for better Claude Code context.

Can I use Ouroboros without Claude Code?

Yes. While ooo setup is designed to run inside a Claude Code session for Plugin Mode, you can operate in Full Mode by using the native CLI entry point at src/ouroboros/cli/main.py. Install the package and run ouroboros setup followed by ouroboros run --seed <path> to execute workflows directly from your shell without the Claude Code plugin system.

What is the MCP server and why must it be registered?

The Model-Context-Protocol (MCP) server is the bridge component in Ouroboros's Core Layer that translates Claude Code skill invocations into local Python tool executions. Registration writes the necessary configuration so that the Claude Code plugin system can locate and communicate with the server process, enabling skills like ooo interview and ooo seed to function correctly.

Where is the setup logic implemented in the source code?

The setup wizard logic resides in skills/setup/SKILL.md, which contains the actual implementation for MCP registration and CLAUDE.md injection. The commands/setup.md file provides a minimal wrapper that invokes this skill when you type ooo setup in the Claude Code REPL. The entry point for the native CLI equivalent is defined in src/ouroboros/cli/main.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}