Launch the Ouroboros Python engine via uvx to provide DSH with specification-driven AI workflows as MCP tools (Interview→Seed→Execute→Evaluate→Evolution loop), requiring no installation or additional code.
- Language
- Python
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add github:Q00/ouroboros/integrations/dsh-pluginRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
一句话定位
这个 bundle 把 Ouroboros——一套"先把需求问清楚再动代码"的 Python AI 工作流引擎——以 MCP 工具的形式挂进 DeepSeek Harness,让你在 dsh 对话框里说 ooo interview、ooo auto、ooo qa 时不用手动切换窗口。
核心能力
- 在 dsh 对话里直接调用 30 多个 Ouroboros 工具(采访、Seed、执行、评估、进化、QA、撤销、回滚等),模型根据工具描述自动选择
- 运行完整的
采访 → Seed → 执行 → 评估闭环(auto 工具一次跑完同步返回,30 分钟超时) - 在既有 dsh 项目里用 Socratic 采访压低需求模糊度,达到阈值才允许生成 Seed 规范
- 用进化循环(演化、回滚、世代追踪)反复打磨 Seed,直到评估器放行
- 提供异常分支工具:取消执行、取消后台任务、查询任务状态、查询投影事件、查询仪表盘
- 软失败启动:本机若没装
uv或 Ouroboros 还没配置,dsh 仍能正常起来,只是 Ouroboros 工具不显示,其它插件不受影响
技术实现
- 语言: 整个 bundle 是纯配置(YAML + JSON),没有任何自定义插件代码;背后的 Ouroboros 是 Python
- 关键依赖:
@deepseek-ai/dsh-mcp-client(MCP stdio 客户端)、uvx(随用随取的 Python 运行时)、ouroboros-ai[mcp](MCP 2.0 协议的服务端包) - 架构模式: 通过 Cordis 补丁(
dsh.bundle.patch)插入一行mcp-ouroboros,由 dsh 的 MCP 客户端用 stdio 协议拉起ouroboros mcp serve,子进程再把 30 多个工具暴露给上层 agent - 入口文件:
integrations/dsh-plugin/cordis.patch.yml(逻辑入口),integrations/dsh-plugin/package.json(声明dsh.bundle.patch路径)
适用场景
想让 DSH 不再"上来就写代码"的人:在用 dsh 做正经需求时,先让 Ouroboros 把模糊想法拆成可验收的 Seed,再交给执行器,最后让评估器打分迭代。也适合需要在 dsh 里同时跑调研、设计、评审多道工序、又不想离开 dsh 窗口的开发者。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Python | >= 3.12 | 由 uvx 在隔离环境里自动拉取,无需手动 pip install |
| uv (uvx) | 最新稳定版 | 需在 PATH 上;首次启动时它会自己下载 Ouroboros 及其依赖 |
| dsh | 未声明具体版本 | bundle 自身不约束;父仓库通过 dsh-mcp-client 加载 |
| Node.js | >= 22 | 仅在你想用 OUROBOROS_LLM_BACKEND=dsh 并从源码构建 dsh 时需要 |
| Agent runtime | 可执行一个 CLI 运行时 | claude-cli、codex、opencode 任一;告诉 Ouroboros 由谁执行 ooo auto |
| 操作系统 | 跨平台 | 无原生模块,不强绑 Linux/macOS/Windows |
安装方式
dsh plugin --profile web add github:Q00/ouroboros/integrations/dsh-plugin
配置项
本 bundle 没有 DSHP 风格的"配置页",所有可选参数都通过环境变量注入,dsh 子进程只允许这几项透传:
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
OUROBOROS_AGENT_RUNTIME | 环境变量 | 指定哪个 CLI 跑 ooo auto 的执行步骤(claude-cli、codex、opencode 等) | 不设,继承 ouroboros setup 的默认 |
OUROBOROS_LLM_BACKEND | 环境变量 | 采访/Seed/QA 用什么 LLM;设为 dsh 时改走 DeepSeek Harness(需配合下面两项) | 不设,继承 ouroboros setup 的默认 |
OUROBOROS_DSH_CONFIG_PATH | 环境变量 | 当 OUROBOROS_LLM_BACKEND=dsh 时必填,绝对路径,指向 dsh 的 Cordis 组合配置 | 不设 |
OUROBOROS_DSH_CLI_PATH | 环境变量 | dsh-acp-demo 二进制不在 PATH 时给它指路 | 走 PATH |
ANTHROPIC_API_KEY | 环境变量 | 透传给 Ouroboros 默认 LLM 后端 | 不设即空 |
DEEPSEEK_API_KEY | 环境变量 | dsh 后端的回环凭证 | 不设即空 |
toolCallTimeoutMs | patch 参数 | ouroboros_auto 同步入参,30 分钟(1800000 毫秒) | 已写在补丁里 |
其余非凭证类变量(PATH、HOME、OUROBOROS_* 选择器)dsh 会自动透传,无需在这里声明。
常见问题
Q: 必须装 Python 吗?
A: 系统级 Python 不需要。bundle 用 uvx 在隔离环境里下载并运行 Python 3.12+ 与 Ouroboros,只要机器上有 uv(从 https://astral.sh/uv 一行安装命令搞定)即可。
Q: 安装后看不到 mcp__ouroboros__* 工具怎么办?
A: 先确认 uv --version 能跑;再确认你是否设过 OUROBOROS_AGENT_RUNTIME,或者跑过 ouroboros setup。记住启动失败是软失败(failOnStartupError: false),dsh 不会因为这个插件崩,只是工具列表里少了它。
Q: 跟单独装 Ouroboros 比,这个 bundle 缺了什么?
A: 没有 SKU 上的差异——bundle 本质就是一行 cordis.patch.yml,真正的 Ouroboros 包还是从 PyPI 用 uvx 拉。换句话说,你既可以在 dsh 里聊,也可以在终端单独跑 ooo,两边共享同一份配置。
Q: 如何把 OpenAI/Google 的 key 也传进去?
A: 在自家 profile 的 cordis.patch.yml 里复制 mcp-ouroboros 整段 config,在 env 里追加 OPENAI_API_KEY (或 GOOGLE_API_KEY 等);注意 dsh 后来的 layer 是覆盖整段而非深合并,所以不要只 patch 一行,得带 config 块一起重写。
Q: 网络断了/uv 抽风了,工具列表还在,调用却一直失败?
A: 这是预期行为:该 bundle 没有自动重连逻辑(reconnect loop 只在 dsh 主仓库 main 分支里),你需要修复根因后手动重启 dsh 或重载插件。
上手难度
进阶 — 不需要写代码,但要把 uv、环境变量、Ouroboros 的 agent runtime 选择这层概念搞明白才能顺畅启用,普通用户需要看一遍 README 才能用上。
已知问题与限制
OUROBOROS_LLM_BACKEND=dsh不是单变量切换:必须从源码构建 dsh(pnpm install && pnpm run build,Node.js >= 22),发布版@deepseek-ai/dsh-acp-demo在dsh-tool-bashpeer 依赖链上仍冲突;还必须提供绝对路径的 Cordis 组合文件(OUROBOROS_DSH_CONFIG_PATH),相对路径会被拒绝- MCP 子进程不能托管 in-process 的 Claude SDK,所以
OUROBOROS_AGENT_RUNTIME必须是一个可执行 CLI(不能填claude这种 SDK 名),除非你想ouroboros auto那步调用就报错 - 子进程环境做了凭证剥离:只有
ANTHROPIC_API_KEY和DEEPSEEK_API_KEY在白名单,其它*_KEY都不会自动透传给 Ouroboros - 重连不是默认行为:已发布的 dsh 0.0.1-rc.1 没有 reconnect 循环,只有最新的
main分支有带指数退避和重试上限的版本;安装完若崩溃,需手动重载插件或重启 dsh - bundle 不发布独立版本号或 release,跟着父 Ouroboros 仓库的
main分支走,意味着用dsh plugin add时拿到的始终是上游main头
◯ ─────────── ◯
O U R O B O R O S
◯ ─────────── ◯
It gets smarter on its own. We just hold the line.
Skip the prompt engineering. The agent runs, fails, and gets smarter every generation. The grading command and expected result never make it into the success contract we hand it.
The Agent OS for replayable AI coding workflows
Quick Start · Why · Results · How It Works · Commands · Philosophy · Guide
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme-hero bash
One command installs it. Then run ooo setup once inside your coding agent — details in Quick Start.
Separate runs, separate hosts. Different tasks on purpose — the engine is what is shared, not the prompt
 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, 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.
The Ouroboros Agent OS Stack
Like any OS, Ouroboros is split into a stable OS layer of primitives, an application layer of domain workflows, and a shell that humans actually sit in front of. Three repos, one stack:
| Layer | Repo | Role | What it gives you |
|---|---|---|---|
| Shell (terminal client) | Ouro-labs/ourocode | Native terminal UI for running ooo workflows across Claude / Codex / Gemini CLIs in one session | TUI, wonderTool decision pickers, MCP pane state, command discovery |
| Apps (domain workflows) | Ouro-labs/ouroboros-plugins | UserLevel plugin contract — composes core primitives into installable domain programs (PR ops, Jira sync, incidents, releases) | Plugin manifest, scoped permissions, audit/provenance, reference plugins |
| OS (this repo) | Q00/ouroboros | Agent OS core — Seed, Ledger, Runtime, MCP, safety boundaries | ooo commands, spec-first workflow engine, multi-runtime adapter |
How they connect:
ourocode ──► ooo / ouroboros-plugins ──► ouroboros core (Seed · Ledger · MCP · Runtime)
shell user-level apps kernel
- The kernel (
ouroboros) owns the contract: every action becomes a Seed-bound, ledger-recorded, replayable event — regardless of which LLM executes it. - Plugins (
ouroboros-plugins) declare scoped capabilities against that contract, so domain workflows (review a PR, triage a Linear ticket, run a release) stay auditable and policy-bound instead of being one-off prompts. - Ourocode is the terminal shell: it surfaces MCP state, interview questions, and wonderTool decisions as first-class TUI elements, so you can drive the OS without leaving the keyboard or switching between CLIs.
Use ouroboros alone with any supported CLI, layer plugins on for domain
workflows, or install ourocode when you want a unified terminal cockpit.
Disclaimer. The Ouroboros project and community are not affiliated with any cryptocurrency, token, memecoin, or trading community — including, but not limited to, any "ouroboros" tickers on pump.fun or other launchpads. This is an open-source developer tool. We do not issue, endorse, or hold any coins. Any token claiming association with this project is unauthorized.
Naming note. A separate, unaffiliated open-source project also uses the name "Ouroboros" — Anton Razzhigaev's self-modifying, autonomous-memory agent at
github.com/razzant/ouroboros. No shared code, no relationship. This project locks a specification before executing rather than rewriting its own architecture; if you're looking for the latter, that's the other one.
Why Ouroboros?
Most AI coding fails at the input, not the output. The bottleneck is not AI capability -- it is human clarity.
| Problem | What Happens | Ouroboros Fix |
|---|---|---|
| Vague prompts | AI guesses, you rework | Socratic interview exposes hidden assumptions |
| No spec | Architecture drifts mid-build | Immutable seed spec locks intent before code |
| Manual QA | "Looks good" is not verification | 3-stage automated evaluation gate |
Quick Start
Install — one command, everything auto-detected:
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash
First command — open your AI coding agent and run these in order:
> ooo setup
> ooo interview "I want to build a task management CLI"
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:
$ ouroboros init start --orchestrator "I want to build a task management CLI tool"
That recording is this exact command. It is at the top of this page so you can see the tool before installing it.
ouroboros setup refresh 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 AGENTS.md for OpenCode, bridges for Pi and GJC. Your machine will show whichever of the thirteen you have installed.
Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi 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|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 withkiro-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, orOUROBOROS_LLM_BACKEND=dsh) — this drives DeepSeek Harness's ACP server under the hood. Or go the other way: install thedsh-ouroborosplugin (dsh plugin --profile <your-profile> add "github:Q00/ouroboros#main&path:integrations/dsh-plugin") and typeooo interview/ooo autodirectly in the DeepSeek Harness chat — the sameouroboros_interview/ouroboros_autotools run natively inside it, Socratic questions and all. Both directions, including what thedshbackend needs beyond the one variable, are in the DeepSeek Harness guide.
Codex plugin quick start
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.
codex plugin marketplace add Q00/ouroboros
codex plugin add ouroboros@ouroboros
Start a new Codex session, then run these commands in order:
ooo setup
ooo interview "Build a task management CLI"
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.
Kiro CLI quick start
pipx install 'ouroboros-ai[mcp]' # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime kiro # detects Kiro CLI, registers MCP server, and
# writes OUROBOROS_RUNTIME=kiro into
# ~/.kiro/settings/mcp.json (the trusted,
# setup-managed location -- a project .env
# is untrusted input and this key is ignored there)
Then use ooo commands inside a Kiro CLI session.
GitHub Copilot CLI quick start
gh auth login # one-time GitHub auth (used for live model discovery)
pipx install 'ouroboros-ai[mcp]' # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot # discovers models live, picks a default,
# registers MCP server in ~/.copilot/mcp-config.json
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.
See the GitHub Copilot CLI runtime guide for full details.
Other install methods
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):
claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros
Then run ooo setup inside a Claude Code session.
pip / uv / pipx:
pip install ouroboros-ai # base
pip install 'ouroboros-ai[claude]' # + default Claude Agent SDK profile (MCP 1.x)
pip install 'ouroboros-ai[claude-cli]' # + dependency-free Claude CLI worker profile
pip install 'ouroboros-ai[claude-sdk]' # + explicit alias for the Claude SDK profile
pip install 'ouroboros-ai[litellm]' # + LiteLLM multi-provider; Python 3.12-3.13
pip install 'ouroboros-ai[mcp]' # + MCP server/client support
pip install 'ouroboros-ai[tui]' # + Textual terminal UI
pip install 'ouroboros-ai[all]' # MCP 1.x app bundle; excludes the MCP 2 server
ouroboros setup # configure runtime
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.
[claude] preserves the in-process Agent SDK and its MCP 1.x dependency graph;
[claude-sdk] is its explicit alias. The MCP 2 server runs from a separate
[mcp] environment and selects the [claude-cli] subprocess worker when
Claude is the host. Never install [mcp,claude], [mcp,claude-sdk], or
[all,mcp] in one interpreter. See the package compatibility and migration matrix.
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 <kiro|copilot|hermes>; 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):
brew tap q00/tap
brew install ouroboros-ai
ouroboros setup # configure runtime
Self-hosted tap, not yet in homebrew-core. Installs the same package published to PyPI.
See runtime guides: Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Zcode · Pi JSON mode · Goose · GJC · Antigravity CLI · Grok Build CLI
Uninstall
ouroboros uninstall
Removes all configuration, MCP registration, and data. See UNINSTALL.md for 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: -32000when an existing environment shadows the[mcp]profile (#2012). This matters if you install through a downstream package rather than PyPI, since those can lag.
Most people find out they were unclear about three files into the review.
If that feels familiar, star Q00/ouroboros on GitHub so the next person it could save can find it.
What You Get
After one loop of the Ouroboros cycle, a vague idea becomes a verified codebase:
| Step | Before | After |
|---|---|---|
| Interview | "Build me a task CLI" | 12 hidden assumptions exposed, ambiguity scored to 0.19 |
| Seed | No spec | Immutable specification with acceptance criteria, ontology, constraints |
| Evaluate | Manual review | 3-stage gate: Mechanical (free) -> Semantic -> Multi-Model Consensus |
What just happened?
interview -> Socratic questioning exposed 12 hidden assumptions
seed -> Crystallized answers into an immutable spec (Ambiguity: 0.15)
run -> Executed via Double Diamond decomposition
evaluate -> 3-stage verification: Mechanical -> Semantic -> Consensus
Use
ooo <cmd>inside your AI coding agent session, orouroboros init start,ouroboros run seed.yaml, etc. from the terminal.
The serpent completed one loop. Each loop, it knows more than the last.
How It Compares
AI coding tools are powerful -- but they solve the wrong problem when the input is unclear.
| Vanilla AI Coding | Ouroboros | |
|---|---|---|
| Vague prompt | AI guesses intent, builds on assumptions | Socratic interview forces clarity before code |
| Spec validation | No spec -- architecture drifts mid-build | Immutable seed spec locks intent; ambiguity gate (<= 0.2) blocks premature code without explicit force |
| Evaluation | "Looks good" / manual QA | 3-stage automated gate: Mechanical -> Semantic -> Multi-Model Consensus |
| Rework rate | High -- wrong assumptions surface late | Low -- assumptions surface in the interview, not in the PR review |
The Loop
The ouroboros -- a serpent devouring its own tail -- is not decoration. It IS the architecture:
Interview -> Seed -> Execute -> Evaluate
^ |
+---- Evolutionary Loop ----+
Each cycle does not repeat -- it evolves. The output of evaluation feeds back as input for the next generation, until the system truly knows what it is building.
| Phase | What Happens |
|---|---|
| Interview | Socratic questioning exposes hidden assumptions |
| Seed | Answers crystallize into an immutable specification |
| Execute | Double Diamond: Discover -> Define -> Design -> Deliver |
| Evaluate | 3-stage gate: Mechanical ($0) -> Semantic -> Multi-Model Consensus |
| Evolve | Wonder ("What do we still not know?") -> Reflect -> next generation |
"This is where the Ouroboros eats its tail: the output of evaluation becomes the input for the next generation's seed specification." --
reflect.py
Convergence is reached when ontology similarity >= 0.95 -- when the system has questioned itself into clarity.
Ralph: The Loop That Never Stops
ooo ralph runs the evolutionary loop persistently -- across session boundaries -- until convergence is reached. Each step is stateless: the EventStore reconstructs the full lineage, so even if your machine restarts, the serpent picks up where it left off.
Ralph Cycle 1: evolve_step(lineage, seed) -> Gen 1 -> action=CONTINUE
Ralph Cycle 2: evolve_step(lineage) -> Gen 2 -> action=CONTINUE
Ralph Cycle 3: evolve_step(lineage) -> Gen 3 -> action=CONVERGED
+-- Ralph stops.
The ontology has stabilized.
Commands
Inside AI coding agent sessions, use ooo <cmd> skills. From the terminal, use the ouroboros CLI.
Skill (ooo) | CLI equivalent | What It Does |
|---|---|---|
ooo setup | ouroboros setup | Register runtime and configure project (one-time) |
ooo interview | ouroboros init start | Socratic questioning -- expose hidden assumptions |
ooo auto | ouroboros auto | Goal → A-grade Seed → execution handoff with bounded loops |
ooo seed | (generated by interview) | Crystallize into immutable spec |
ooo run | ouroboros run seed.yaml | Execute via Double Diamond decomposition |
ooo evaluate | (via MCP) | 3-stage verification gate |
ooo evolve | (via MCP) | Evolutionary loop until ontology converges |
ooo unstuck | (via MCP) | 5 lateral thinking personas when you are stuck |
ooo status | ouroboros status executions / ouroboros status execution <id> | Session tracking + (MCP-only) drift detection |
ooo resume-session | ouroboros resume | List in-flight sessions and re-attach commands |
ooo cancel | ouroboros cancel execution [<id>|--all] | Cancel stuck or orphaned executions |
ooo ralph | (via MCP) | Persistent loop until verified |
ooo tutorial | (interactive) | Interactive hands-on learning |
ooo help | ouroboros --help | Full reference |
ooo pm | (via MCP) | PM-focused interview + PRD generation |
ooo qa | (via skill) | General-purpose QA verdict for any artifact |
ooo update | ouroboros update | Check for updates + upgrade to latest |
ooo brownfield | (via skill) | Scan and manage brownfield repo/worktree defaults |
ooo publish | (skill/runtime surface; uses gh CLI) | Publish a Seed as GitHub Epic/Task issues for team workflows |
Not all skills have direct CLI equivalents. Some (
evaluate,evolve,unstuck,ralph,publish) are available through agent skills, runtime rules, or MCP tools rather than a directouroboros <subcommand>shell command./resumeis reserved for Claude Code's built-in session picker; useooo resume-sessionfor Ouroboros in-flight sessions. Claude Code also reserves/run,/status,/help, and/config. The safe direct skill forms are/ouroboros:ouroboros-run,/ouroboros:ouroboros-status,/ouroboros:ouroboros-help, and/ouroboros:ouroboros-config; the familiarooo run,ooo status,ooo help, andooo configphrases remain supported.
See the CLI reference for full details.
The Nine Minds
Nine agents, each a different mode of thinking. Loaded on-demand, never preloaded:
| Agent | Role | Core Question |
|---|---|---|
| Socratic Interviewer | Questions-only. Never builds. | "What are you assuming?" |
| Ontologist | Finds essence, not symptoms | "What IS this, really?" |
| Seed Architect | Crystallizes specs from dialogue | "Is this complete and unambiguous?" |
| Evaluator | 3-stage verification | "Did we build the right thing?" |
| Contrarian | Challenges every assumption | "What if the opposite were true?" |
| Hacker | Finds unconventional paths | "What constraints are actually real?" |
| Simplifier | Removes complexity | "What's the simplest thing that could work?" |
| Researcher | Stops coding, starts investigating | "What evidence do we actually have?" |
| Architect | Identifies structural causes | "If we started over, would we build it this way?" |
Under the Hood
Architecture overview -- Python >= 3.12
src/ouroboros/
+-- bigbang/ Interview, ambiguity scoring, brownfield explorer
+-- routing/ PAL Router -- 3-tier cost optimization (1x / 10x / 30x)
+-- execution/ Double Diamond, hierarchical AC decomposition
+-- evaluation/ Mechanical -> Semantic -> Multi-Model Consensus
+-- evolution/ Wonder / Reflect cycle, convergence detection
+-- resilience/ 4-pattern stagnation detection, 5 lateral personas
+-- observability/ 3-component drift measurement, auto-retrospective
+-- persistence/ Event sourcing (SQLAlchemy + aiosqlite), checkpoints
+-- orchestrator/ Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi)
+-- core/ Types, errors, seed, ontology, security
+-- providers/ LiteLLM adapter (100+ models)
+-- mcp/ MCP client/server integration
+-- plugin/ Plugin system (skill/agent auto-discovery)
+-- tui/ Terminal UI dashboard
+-- cli/ Typer-based CLI
Key internals:
- PAL Router -- Frugal (1x) -> Standard (10x) -> Frontier (30x) with auto-escalation on failure, auto-downgrade on success
- Drift -- Goal (50%) + Constraint (30%) + Ontology (20%) weighted measurement, threshold <= 0.3
- Brownfield -- Auto-detects config files across multiple language ecosystems
- Evolution -- Up to 30 generations, convergence at ontology similarity >= 0.95
- Stagnation -- Detects spinning, oscillation, no-drift, and diminishing returns patterns
- Agent OS runtime -- Replayable execution contract across capability discovery, policy, directives, event journal, and agent processes
- Runtime backends -- Pluggable abstraction layer (
orchestrator.runtime_backendconfig) with first-class support for Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Goose, Kiro, Copilot, and Pi; same workflow spec, different execution engines
See Architecture for the full design document.
From Wonder to Ontology
The philosophical engine behind Ouroboros
Wonder -> "How should I live?" -> "What IS 'live'?" -> Ontology -- Socrates
Every great question leads to a deeper question -- and that deeper question is always ontological: not "how do I do this?" but "what IS this, really?"
Wonder Ontology
"What do I want?" -> "What IS the thing I want?"
"Build a task CLI" -> "What IS a task? What IS priority?"
"Fix the auth bug" -> "Is this the root cause, or a symptom?"
This is not abstraction for its own sake. When you answer "What IS a task?" -- deletable or archivable? solo or team? -- you eliminate an entire class of rework. The ontological question is the most practical question.
Ouroboros embeds this into its architecture through the Double Diamond:
* Wonder * Design
/ (diverge) / (diverge)
/ explore / create
/ /
* ------------ * ------------ *
\ \
\ define \ deliver
\ (converge) \ (converge)
* Ontology * Evaluation
The first diamond is Socratic: diverge into questions, converge into ontological clarity. The second diamond is pragmatic: diverge into design options, converge into verified delivery. Each diamond requires the one before it -- you cannot design what you have not understood.
Ambiguity Score: The Gate Between Wonder and Code
The Interview does not end when you feel ready -- it ends when the math says you are ready. Ouroboros quantifies ambiguity as the inverse of weighted clarity:
Ambiguity = 1 - Sum(clarity_i * weight_i)
Each dimension is scored 0.0-1.0 by the LLM (temperature 0.1 for reproducibility), then weighted:
| Dimension | Greenfield | Brownfield |
|---|---|---|
| Goal Clarity -- Is the goal specific? | 40% | 35% |
| Constraint Clarity -- Are limitations defined? | 30% | 25% |
| Success Criteria -- Are outcomes measurable? | 30% | 25% |
| Context Clarity -- Is the existing codebase understood? | -- | 15% |
Threshold: Ambiguity <= 0.2. A score above that blocks Seed generation. Passing force explicitly is what gets past it, and the CLI puts that choice on screen next to continue and cancel. The gate is a default worth arguing with, not a lock.
Example (Greenfield):
Goal: 0.9 * 0.4 = 0.36
Constraint: 0.8 * 0.3 = 0.24
Success: 0.7 * 0.3 = 0.21
------
Clarity = 0.81
Ambiguity = 1 - 0.81 = 0.19 <= 0.2 -> Ready for Seed
Why 0.2? Because at 80% weighted clarity, the remaining unknowns are small enough that code-level decisions can resolve them. Above that threshold, you are still guessing at architecture.
Ontology Convergence: When the Serpent Stops
The evolutionary loop does not run forever. It stops when consecutive generations produce ontologically identical schemas. Similarity is measured as a weighted comparison of schema fields:
Similarity = 0.5 * name_overlap + 0.3 * type_match + 0.2 * exact_match
| Component | Weight | What It Measures |
|---|---|---|
| Name overlap | 50% | Do the same field names exist in both generations? |
| Type match | 30% | Do shared fields have the same types? |
| Exact match | 20% | Are name, type, AND description all identical? |
Threshold: Similarity >= 0.95 -- the loop converges and stops evolving.
But raw similarity is not the only signal. The system also detects pathological patterns:
| Signal | Condition | What It Means |
|---|---|---|
| Stagnation | Similarity >= 0.95 for 3 consecutive generations | Ontology has stabilized |
| Oscillation | Gen N ~ Gen N-2 (period-2 cycle) | Stuck bouncing between two designs |
| Repetitive feedback | >= 70% question overlap across 3 generations | Wonder is asking the same things |
| Hard cap | 30 generations reached | Safety valve |
Gen 1: {Task, Priority, Status}
Gen 2: {Task, Priority, Status, DueDate} -> similarity 0.78 -> CONTINUE
Gen 3: {Task, Priority, Status, DueDate} -> similarity 1.00 -> CONVERGED
Two mathematical gates, one philosophy: do not build until you are clear (Ambiguity <= 0.2), do not stop evolving until you are stable (Similarity >= 0.95).
Contributing
git clone https://github.com/Q00/ouroboros
cd ouroboros
uv sync --python 3.13 --all-groups
uv run --python 3.13 --no-sync pytest
Issues · Discussions · Contributing Guide
Sponsors
Ouroboros is MIT-licensed and built in the open. If it saves you rework — or you want the loop to keep evolving — consider sponsoring. Sponsorship directly funds maintenance, new runtime integrations, and sponsor-only deep-dive content.
Every sponsor keeps the serpent evolving. Thank you.
Activity
These numbers are generated from GitHub data and refreshed automatically; caching may delay updates.
"The beginning is the end, and the end is the beginning."
The serpent does not repeat -- it evolves.
MIT License