# How to Install Ouroboros from PyPI and Run `ooo setup` for Initial Configuration > Install Ouroboros from PyPI with pip install ouroboros-ai. Run ooo setup in Claude Code to register the MCP server and initialize your project configuration. - Repository: [Q00/ouroboros](https://github.com/Q00/ouroboros) - Tags: getting-started - Published: 2026-03-14 --- **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`](https://github.com/Q00/ouroboros/blob/main/pyproject.toml), with the CLI entry point implemented in [`src/ouroboros/cli/main.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/main.py). ### Standard Installation with pip Use pip to install the full-mode package globally or within a virtual environment: ```bash 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`](https://github.com/Q00/ouroboros/blob/main/docs/cli-reference.md): ```bash 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`](https://github.com/Q00/ouroboros/blob/main/skills/setup/SKILL.md), executed through the wrapper in [`commands/setup.md`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/docs/getting-started.md) and [`docs/architecture.md`](https://github.com/Q00/ouroboros/blob/main/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**: ```bash pip install ouroboros-ai ``` 2. **Start a Claude Code session**: ```bash claude ``` 3. **Run the setup wizard inside the Claude Code REPL**: ```bash ooo setup ``` This registers the MCP server globally and optionally updates your [`CLAUDE.md`](https://github.com/Q00/ouroboros/blob/main/CLAUDE.md) file with the Ouroboros reference block. 4. **Verify the CLI is operational**: ```bash 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`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/main.py): ```bash # 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: ```bash # 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`](https://github.com/Q00/ouroboros/blob/main/pyproject.toml). - **Run `ooo setup`** inside a Claude Code session to register the MCP server globally and optionally configure [`CLAUDE.md`](https://github.com/Q00/ouroboros/blob/main/CLAUDE.md). - The setup connects the **Plugin Layer** (skills) to the **Core Layer** (MCP server) according to the architecture in [`docs/architecture.md`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/main.py). Install the package and run `ouroboros setup` followed by `ouroboros run --seed ` 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`](https://github.com/Q00/ouroboros/blob/main/skills/setup/SKILL.md), which contains the actual implementation for MCP registration and [`CLAUDE.md`](https://github.com/Q00/ouroboros/blob/main/CLAUDE.md) injection. The [`commands/setup.md`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/main.py).