by Q00
Stop prompting. Start specifying.
# Add to your Claude Code skills
git clone https://github.com/Q00/ouroborosNew: OpenClaw Integration — Ouroboros now runs inside chat platforms via OpenClaw. Install the skill, connect MCP, and your team can run
ooocommands directly from Slack, Discord, or any OpenClaw-supported channel.clawhub install ouroboros openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai[mcp]","ouroboros","mcp","serve"]}'
Turn a vague idea into a verified, working codebase -- with any AI coding agent.
Ouroboros sits between you and your AI runtime (Claude Code, Codex CLI, or others). It replaces ad-hoc prompting with a structured specification-first workflow: interview, crystallize, execute, evaluate, evolve.
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 |
Install — one command, everything auto-detected:
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash
Build — open your AI coding agent and go:
> ooo interview "I want to build a task management CLI"
Works with Claude Code, Codex CLI, and OpenCode. The installer detects Claude Code and Codex CLI automatically and registers the MCP server. For OpenCode, run after installation.
No comments yet. Be the first to share your thoughts!
ouroboros setup --runtime opencodeClaude Code plugin only (no system package):
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] # + Claude Code deps
pip install ouroboros-ai[litellm] # + LiteLLM multi-provider
pip install ouroboros-ai[mcp] # + MCP server/client support
pip install ouroboros-ai[tui] # + Textual terminal UI
pip install ouroboros-ai[all] # everything (claude + litellm + mcp + tui + dashboard)
ouroboros setup # configure runtime
Legacy compatibility: ouroboros-ai[dashboard] is still accepted as a compatibility alias while extras migrate.
See runtime guides: Claude Code · Codex CLI · OpenCode
Chat platform integration (OpenClaw / Slack / Discord):
clawhub install ouroboros # install OpenClaw skill
openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai[mcp]","ouroboros","mcp","serve"]}'
If
openclaw mcp setis not recognized, runopenclaw updateto get the latest version.
Guide: Channel workflow integration
ouroboros uninstall
Removes all configuration, MCP registration, and data. See UNINSTALL.md for details.
Python >= 3.12 required. See pyproject.toml for the full dependency list.
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 |
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.
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 | | 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 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.
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.
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 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 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 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