Ouroboros智能体操作系统

Windows (PowerShell) — no Python needed; installs Git and uv for you

irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex ```

<p align="center">_{One command installs it. Then run <code>ooo setup</code> once inside your coding agent — details in <a href="#quick-start">Quick Start</a>.}</p>

<p align="center">_{<b>Separate runs, separate hosts. Different tasks on purpose — the engine is what is shared, not the prompt</b>}</p>

Terminal CLI — a task-management CLI: ouroboros init start asking about ordering and scope, then reporting an ambiguity score	ChatGPT (Codex) — called as an integration, on a video-publishing harness: the interview, its advisory lanes, and the ambiguity ledger	Claude Code — a YouTube automation task, with the six advisory lanes running in parallel before the interview submits
Hermes (Discord) — a kart-racing game, run as a chat bot, ending at Final ambiguity: 0.15	DeepSeek Harness — an OSS-trend outreach script, driven from a dsh chat: mcp__ouroboros__ouroboros_interview turn by turn, fan-out results submitted between rounds	Kiro — the Kiro CLI running the Ouroboros interview flow, turning a vague request into a structured, testable Seed

Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, OMP, Zcode, Goose, GJC, Antigravity, and Grok.

Ouroboros is an Agent OS for AI coding: a local-first runtime layer that turns non-deterministic agent work into a replayable, observable, policy-bound execution contract. It replaces ad-hoc prompting with a structured specification-first workflow: interview, crystallize, execute, evaluate, evolve.

---

Windows (PowerShell 5.1+ or pwsh 7+) — nothing to install first

irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex

The Windows installer installs Git and uv through winget when they are missing,
lets uv download its own Python, then installs `ouroboros-ai` and wires the
host it finds. Native Windows is experimental and Codex CLI needs WSL 2; see
[platform support](./docs/platform-support.md).

**First command** — open your AI coding agent and run these in order:

`ooo setup` is a one-time configuration step. `ooo interview` is the first
workflow command and starts the Socratic interview. After setup, Codex follows
its currently selected model and Claude Code starts with its recommended model
settings. Choose **Directly configure models** only when you want to pin a
stage to a specific model; it opens the local settings screen in your browser.
You can return to those settings any time with `ooo config`.

Or from a plain terminal, without an agent host:

<p align="center">
  <sub>That recording is this exact command. It is at the top of this page so you can see the tool before installing it.</sub>
</p>

<p align="center">
  <img src="./docs/images/ooo-setup-refresh.gif" width="760" alt="Terminal recording of ouroboros setup refresh installing Codex rules and skills, Hermes skills, the OpenCode plugin and instruction guide, and the Pi and GJC bridges, ending with the line Refreshed runtime artifacts: codex, hermes, opencode, pi, gjc">
</p>

<p align="center">
  <sub><code>ouroboros setup refresh</code> on one machine. It installs into the hosts that machine actually has, each in the shape that host expects: rules and skills for Codex, skills for Hermes, a plugin and an <code>AGENTS.md</code> for OpenCode, bridges for Pi and GJC. Your machine will show whichever of the thirteen you have installed.</sub>
</p>

> Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi CLI, OMP CLI, Zcode, Goose, GJC, Antigravity CLI, and Grok Build CLI. The installer detects available runtimes and registers the MCP server where the host supports it. For explicit selection, run `ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi|omp|zcode|goose|gjc|antigravity|grok>` after installation. Copilot live-discovers its subscription catalog via the GitHub Copilot models API; Kiro's settings picker queries the authenticated CLI with `kiro-cli chat --listmodels -f json`, so account and enterprise allow-list changes appear without a hardcoded model table.

> **DeepSeek support.** Ouroboros speaks DeepSeek two ways. Point the interview/Seed/QA pipeline at DeepSeek's own models with `--llm-backend dsh` (`ouroboros mcp serve --runtime claude-cli --llm-backend dsh`, or `OUROBOROS_LLM_BACKEND=dsh`) — this drives [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)'s ACP server under the hood. Or go the other way: install the [`dsh-ouroboros` plugin](./integrations/dsh-plugin) (`dsh plugin --profile <your-profile> add "github:Q00/ouroboros#main&path:integrations/dsh-plugin"`) and type `ooo interview` / `ooo auto` directly in the DeepSeek Harness chat — the same `ouroboros_interview` / `ouroboros_auto` tools run natively inside it, Socratic questions and all. Both directions, including what the `dsh` backend needs beyond the one variable, are in the [DeepSeek Harness guide](./docs/guides/deepseek-harness.md).

<details>
<summary><strong>Codex plugin quick start</strong></summary>

Needs `codex` on your `PATH` and `uvx` on the host (the plugin's MCP descriptor
launches the server with it). Install uv with `pipx install uv`,
`pip install --user uv`, or `brew install uv`.

Start a new Codex session, then run these commands in order:

`ooo setup` is the one-time runtime preparation. Once ready, Ouroboros follows
Codex's current default model; choose **Directly configure models** only when
you want to pin a specific model for a pipeline stage.

</details>

<details>
<summary><strong>Kiro CLI quick start</strong></summary>

Then use `ooo` commands inside a Kiro CLI session.

</details>

<details>
<summary><strong>GitHub Copilot CLI quick start</strong></summary>

Restart your Copilot CLI session, then use `ooo` commands inside it. Model-ID mapping is catalog-gated: the current direct and OpenRouter Opus defaults resolve to Copilot's published `claude-opus-5`, while legacy Anthropic versions convert only their trailing numeric separator and only when the discovered catalog contains the exact candidate. Unknown IDs remain unchanged so Copilot reports an explicit unavailable-model error instead of silently selecting a different model. Leave role models unset so setup writes a discovered ID, or set a Copilot-valid ID explicitly. See the [Copilot runtime guide](./docs/runtime-guides/copilot.md).

See the [GitHub Copilot CLI runtime guide](./docs/runtime-guides/copilot.md) for full details.

</details>

<details>
<summary><strong>Other install methods</strong></summary>

**Claude Code plugin only** (no Python package or global Python to install; the
host needs uv, which provides both `uvx` for the MCP server and the skills'
Python >= 3.12 fallback):

Then run `ooo setup` inside a Claude Code session.

**pip / uv / pipx**:

Core and non-LiteLLM installs support Python 3.12-3.14. LiteLLM-bearing installs (`[litellm]`, `[all]`, and source `--extra all`) support Python 3.12-3.13; use Python 3.13 for current examples. See [Platform Support](./docs/platform-support.md#python-profile-matrix).

The recommended standalone installation is `ouroboros-ai[mcp,tui]` followed by
an explicit MCP v2-compatible runtime selection. The example uses
`--runtime claude-cli`; substitute another compatible runtime such as `codex`,
`opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, or `gjc`.
Use `[claude]` and `[claude-sdk]` only in isolated MCP 1.x environments.

`pip install 'ouroboros-ai[mcp]'` is valid for embedding the MCP client/server library in an already isolated Python environment, but host registration requires `uvx --isolated --python '>=3.12'` or `pipx`. Use `pipx install 'ouroboros-ai[mcp]'` or `uv tool install 'ouroboros-ai[mcp]'` before `ouroboros setup --runtime <claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc>`; setup exits without changing runtime configuration when neither isolated launcher is available.

Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias/no-op; it does not install dashboard runtime payload. `ouroboros-ai[all]` includes that no-op alias only for compatibility.

**Homebrew (macOS/Linux)**:

Self-hosted tap, not yet in homebrew-core. Installs the same package published to PyPI.

See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [Hermes](./docs/runtime-guides/hermes.md) · [OpenCode](./docs/runtime-guides/opencode.md) · [Kiro CLI](./docs/runtime-guides/kiro.md) · [Gemini CLI](./docs/runtime-guides/gemini.md) · [GitHub Copilot CLI](./docs/runtime-guides/copilot.md) · [Zcode](./docs/runtime-guides/zcode.md) · [Pi JSON mode](https://pi.dev/docs/latest/json) · [OMP (Oh My Pi)](./docs/runtime-guides/omp.md) · [Goose](./docs/runtime-guides/goose.md) · [GJC](./docs/runtime-guides/gjc.md) · [Antigravity CLI](./docs/runtime-guides/antigravity.md) · [Grok Build CLI](./docs/runtime-guides/grok.md)

</details>

<details>
<summary><strong>Uninstall</strong></summary>

Removes all configuration, MCP registration, and data. See UNINSTALL.md for details.

</details>

Python >= 3.12 required. LiteLLM-bearing profiles support Python 3.12-3.13. See Platform Support and pyproject.toml. Installing as an MCP server: use 0.51.1 or later. Earlier versions can fail at startup with Failed to reconnect to plugin:ouroboros:ouroboros: -32000 when an existing environment shadows the [mcp] profile (#2012). This matters if you install through a downstream package rather than PyPI, since those can lag.

<p align="center"> _{Most people find out they were unclear about three files into the review.<br/> If that feels familiar, star <a href="https://github.com/Q00/ouroboros"><strong>Q00/ouroboros on GitHub</strong></a> so the next person it could save can find it.} </p>

---

Quick Start

Install — one command, everything auto-detected:

```bash

How It Compares

AI coding tools are powerful -- but they solve the wrong problem when the input is unclear.

---