Ouroboros
Ouroboros is a spec-first AI coding workflow server: it interviews you to clarify a goal, turns it into a checkable spec (seed), runs coding agents to build it, and verifies the result against acceptance criteria.
Clarify requirements: run interactive or PM interviews, gather brownfield repo context, and generate an immutable seed (with an ambiguity gate) from a completed interview.
Build from a spec: execute or background-start seed runs (
ooo run), with model-tier routing, iteration limits, efficiency/frugality policies, worktree isolation, and session resume.Full auto pipeline: one call runs interview → A-grade seed → execution, optionally chaining into Ralph until QA passes.
Verify results: three-stage evaluation (mechanical lint/build/test, semantic AC compliance, multi-model consensus), per-AC checklists, drift measurement, and general-purpose QA verdicts against a quality bar.
Evolve & loop: generational evolution per lineage, Ralph loops with bounded iterations/time/oscillation controls, rewind, and per-AC pass/fail dashboards.
Monitor & manage: job status/wait/result/cancel, session status, event queries, run/stage/step projections, project status, and a live AC tree HUD.
Steer running work: list active AC session signal targets and send audited Synapse intent signals (inform, after_turn, etc.).
Governance & resilience: record audited conductor decisions, target successors, and get fresh perspectives via lateral-thinking personas with correlated fan-out result submission.
Enables Ouroboros workflow commands and tools within GitHub Copilot CLI sessions.
Enables Ouroboros workflow commands and tools within Hermes CLI sessions.
Ouroboros helps your AI coding agent build the right thing. It asks you questions until the goal is clear, writes the answer down as a spec with checkable acceptance criteria, hands that spec to the coding agent you already use, and then checks the result against the spec.
Install
# macOS / Linux / WSL 2
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash# Windows (PowerShell) — no Python needed; installs Git and uv for you
irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iexWhen installation finishes, the Ouroboros console opens in your browser and
walks you through connecting your agent tools. Reopen it any time with
ouroboros gui.
The installer finds the agent tools you already have and connects Ouroboros to them. Native Windows is experimental, and Codex CLI needs WSL 2; see platform support.
Other ways to install. These don't open the console for you; run
ouroboros gui once the ouroboros command is installed.
# Claude Code plugin only (then run /ouroboros:setup inside Claude Code)
claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros
# pip / uv / pipx (Python 3.12+)
pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli
# Homebrew (macOS / Linux)
brew tap q00/tap && brew install ouroboros-ai && ouroboros setupEvery install path, profile and host is in
Getting Started. ouroboros uninstall removes
Ouroboros's configuration, MCP registrations and data directory
(~/.ouroboros/). It leaves the Python package and the Claude Code plugin
installed; finish with the steps in UNINSTALL.md.
Related MCP server: AgentPrism Workflows
First steps
Describe what you want in plain words. Four good places to start:
Console Chat: type a goal and pick Interview (it asks until the goal is clear) or Auto (it fills the gaps itself), then hand the spec to your agents and watch the run.
ooo interview "a todo CLI with due dates"in your agent: questions until the goal is clear, then a spec (a Seed).ooo auto "a todo CLI with due dates": asks only what is missing, writes the spec, runs it, and checks it.ooo run: builds an existing Seed and checks every acceptance criterion.
In Claude Code, run /ouroboros:setup once and finish its questions, then send
your first ooo command as a separate message. From a plain terminal,
ouroboros init start "..." and ouroboros auto "..." do the same without an
agent host. The full command list is in
Getting Started.
Ouroboros runs coding agents that can change files and run commands in your project. Read permission scope before using it on a project you don't trust.
Works with
Claude Code · Codex CLI · GitHub Copilot CLI · OpenCode · Hermes · Gemini CLI · Kiro CLI · Pi · OMP · Zcode · Goose · GJC · Antigravity CLI · Grok Build CLI · DeepSeek Harness
The installer connects the ones you have; the console's Connect page installs and connects the rest. Want to see it first? Watch the interview run on seven different hosts.
Learn more
Getting Started: every install path, host-by-host setup, your first workflow, and all commands.
Console guide: what each console page does, the shared MCP server, and starting the console at login.
How Ouroboros works: the loop, the agents, the ambiguity gate, the Agent OS stack, architecture, and philosophy.
Contributing
git clone https://github.com/Q00/ouroboros
cd ouroboros
uv sync --python 3.13 --all-groups
uv run --python 3.13 --no-sync pytestIssues · Discussions · Contributing Guide
Sponsors
Ouroboros is MIT-licensed and built in the open. If it saves you rework, consider sponsoring: it funds maintenance, new runtime integrations, and sponsor-only deep-dive content.
Activity
These numbers are generated from GitHub data and refreshed automatically; caching may delay updates.
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.
Available Tools
34 toolsouroboros_ac_dashboardA
Display per-AC pass/fail compliance dashboard across generations. Shows which acceptance criteria passed, failed, or are flaky. Modes: 'summary' (default), 'full' (AC x Gen matrix), 'ac' (single AC history).
Inputs: lineage_id (required), mode, ac_index.
ouroboros_ac_tree_hudB
Return a render-ready markdown snapshot of the live acceptance-criteria tree for an Ouroboros session.
Inputs: session_id (required), view, cursor, max_nodes.
ouroboros_autoA
Run full-quality ooo auto: automatically interview, generate an A-grade Seed, and start execution only after the A-grade gate passes. All loops are bounded.
Inputs: cwd, goal, domain, resume, +16 more.
ouroboros_brownfieldA
Manage brownfield repository registrations. Scan home directory for repos, register/query repos, or set the default brownfield context for PM interviews.
Inputs: desc, name, path, limit, +6 more.
ouroboros_cancel_executionA
Cancel a running or paused Ouroboros execution. Validates that the execution exists and is not already in a terminal state (completed, failed, cancelled) before cancelling.
Inputs: execution_id (required), reason.
ouroboros_cancel_jobC
Request cancellation for a background job.
Inputs: job_id (required).
ouroboros_evaluateA
Evaluate an Ouroboros execution session using the three-stage evaluation pipeline. Stage 1 performs mechanical verification (lint, build, test). Stage 2 performs semantic evaluation of AC compliance and goal alignment. Stage 3 runs multi-model consensus if triggered by uncertainty or manual request.
Inputs: artifact (required), session_id (required), working_dir, seed_content, +4 more.
ouroboros_evolve_rewindA
Rewind an evolutionary lineage to a specific generation. Truncates all generations after the target and emits a lineage.rewound event. The lineage can then continue evolving from the rewind point.
Inputs: lineage_id (required), to_generation (required).
ouroboros_evolve_stepA
Run exactly ONE generation of the evolutionary loop. For Gen 1: provide lineage_id and seed_content (YAML). For Gen 2+: provide lineage_id only (state reconstructed from events). Returns generation result, convergence signal, and next action (continue/converged/ontology_stable/stagnated/exhausted/failed). ontology_stable is a non-success handoff; rerun the same lineage with execute=true to perform Execute→Evaluate.
Inputs: lineage_id (required), execute, skip_qa, parallel, +12 more.
ouroboros_execute_seedC
Execute a seed (task specification) in Ouroboros. A seed defines a task to be executed with acceptance criteria. This is the handler for 'ooo run' commands — do NOT run 'ooo' in the shell; call this MCP tool instead.
Inputs: cwd, skip_qa, seed_path, model_tier, +10 more.
ouroboros_generate_seedA
Generate an immutable Seed from a completed interview session. The seed contains structured requirements (goal, constraints, acceptance criteria) extracted from the interview conversation. Generation requires ambiguity_score <= 0.2 unless force=true is passed to deliberately bypass the gate.
Inputs: session_id (required), force, client_gates, ambiguity_score.
ouroboros_interviewA
Interactive interview for requirement clarification. Start a new interview with initial_context, resume with session_id, or record an answer to the current question. In plugin mode, returns a delegation receipt (status=delegated_to_subagent) and the interview executes in an OpenCode Task pane — the real session_id is returned there.
Inputs: cwd, answer, references, session_id, +4 more.
ouroboros_job_resultA
Get the final output for a completed background job.
Inputs: job_id (required).
ouroboros_job_statusB
Get the latest summary for a background Ouroboros job.
Inputs: job_id (required), view.
ouroboros_job_waitA
Wait briefly for a background job to change state. Useful for conversational polling after a start command.
Inputs: job_id (required), view, cursor, stream, +2 more.
ouroboros_lateral_thinkA
Generate alternative thinking approaches using lateral thinking personas. Use this tool when stuck on a problem to get fresh perspectives from different thinking modes: hacker (unconventional workarounds), researcher (seeks information), simplifier (reduces complexity), architect (restructures approach), or contrarian (challenges assumptions). Set persona='all' (or pass personas=['hacker','architect',...]) to fan out to MULTIPLE personas in parallel — each runs in its own Task pane with an independent LLM context (no cross-contamination).
Inputs: problem_context (required), current_approach (required), persona, personas, +2 more.
ouroboros_lineage_statusB
Query the current state of an evolutionary lineage. Returns generation count, status, ontology evolution, and convergence progress.
Inputs: lineage_id (required).
ouroboros_measure_driftA
Measure drift from the original seed goal. Calculates goal deviation score using weighted components: goal drift (50%), constraint drift (30%), ontology drift (20%). Returns drift metrics, analysis, and suggestions if drift exceeds threshold.
Inputs: session_id (required), seed_content (required), current_output (required), current_concepts, +1 more.
ouroboros_pm_interviewA
PM interview for product requirements gathering. Start with initial_context, continue with session_id + answer, or generate PM seed with action='generate'. In plugin mode, returns a delegation receipt (status=delegated_to_subagent) and the PM interview executes in an OpenCode Task pane — the real session_id is returned there.
Inputs: cwd, action, answer, session_id, +3 more.
ouroboros_project_statusProject statusARead-onlyIdempotent
Resolve a project identity and rebuild its complete read-only run status from persisted Ouroboros session events. Identity conflicts, projection failures, and limits below the complete population return no partial record.
Inputs: limit, workspace, project_dir. Returns: Complete immutable run projection for one project and optional workspace.
ouroboros_qaA
General-purpose QA verdict for any artifact type. Evaluates code, API responses, documents, screenshots, or custom artifacts against a quality bar. Returns structured verdict with score, differences, and actionable suggestions. Designed for iterative loop usage.
Inputs: artifact (required), quality_bar (required), reference, seed_content, +4 more.
ouroboros_query_eventsB
Query the event history for an Ouroboros session. Returns a list of events matching the specified criteria.
Inputs: limit, offset, event_type, session_id.
ouroboros_query_projectionA
Build a read-only Run/Stage/Step projection from persisted Ouroboros events for a session or execution aggregate.
Inputs: limit, seed_id, session_id, execution_id.
ouroboros_ralphA
Start a first-class Ralph loop in the background. The loop repeatedly runs evolve_step until QA passes, convergence is reached, a terminal evolution action occurs, cancellation is requested, or max_generations is reached. In non-plugin runtimes, returns a job_id immediately for ouroboros_job_status, ouroboros_job_wait, ouroboros_job_result, and ouroboros_cancel_job. In OpenCode plugin mode, returns job_id=None and delegates the loop to the plugin child session.
Inputs: lineage_id (required), execute, skip_qa, parallel, +15 more.
ouroboros_record_conductor_decisionA
Record an audited Active Conductor decision. Record phase=selected before an action, then completed, failed, or declined after the outcome. Mutating successors require engine_ownership_state=closed.
Inputs: phase (required), decision_id (required), actor_mode, root_job_id, +12 more.
ouroboros_session_signalA
Send one audited Ouroboros Synapse intent signal to an exact active AC session attempt. Shipped runtime adapters currently advertise and apply only inform and after_turn; direct requested modes require the selected exact attempt to advertise that mode. redirect and replace remain reserved, capability-gated advertised/effective modes; no shipped adapter currently advertises or applies either directly. redirect nevertheless remains a valid requested mode on one explicit fallback path: fallback_mode=after_turn must be present and that exact attempt must advertise after_turn, which becomes the effective queued mode. All other unsupported requests fail closed, including redirect without that fallback and replace without its capabilities. Query ouroboros_session_signal_targets for the selected exact attempt's live capabilities before sending. A queued result does not mean the signal was applied.
Inputs: mode (required), reason (required), source (required), message (required), +9 more.
ouroboros_session_signal_targetsA
List exact active AC attempts and each attempt's live SessionSignal capabilities for one execution before sending a signal. Advertised modes are valid direct requested modes for that exact attempt. One explicit fallback path is also valid: redirect may be requested while omitted from discovery only with fallback_mode=after_turn when after_turn is advertised, and the effective queued mode is after_turn. Shipped adapters currently do not advertise or effect redirect or replace; other unsupported requests fail closed. Match the user's intent to AC content, and ask only when multiple candidates remain genuinely ambiguous.
Inputs: execution_id (required).
ouroboros_session_statusA
Get the status of an Ouroboros session. Returns information about the current phase, progress, and any errors.
Inputs: session_id (required).
ouroboros_start_autoA
Start ooo auto in the background and return auto_session_id + job_id immediately. Resume with the returned auto_session_id; poll with ouroboros_job_status / ouroboros_job_wait and read final state via ouroboros_job_result.
Inputs: cwd, goal, domain, resume, +16 more.
ouroboros_start_evaluateA
Start an evaluation in the background and return a job ID immediately. Use this instead of ouroboros_evaluate when the three-stage pipeline (mechanical + semantic + optional consensus) is expected to exceed the MCP client tool-call timeout. Poll with ouroboros_job_status / ouroboros_job_wait and read the verdict via ouroboros_job_result. In plugin mode with auto_evolve disabled, evaluation is delegated to an OpenCode Task pane and job_id is None. With auto_evolve enabled, the parent keeps evaluation pollable so a rejection can start Ralph.
Inputs: artifact (required), session_id (required), auto_evolve, working_dir, +6 more.
ouroboros_start_evolve_stepA
Start one evolve_step generation in the background and return a job ID immediately for later status checks. In plugin mode, evolution is delegated to an OpenCode Task pane and job_id is None — results appear in the Task pane instead of being pollable via job_status/job_result.
Inputs: lineage_id (required), execute, skip_qa, parallel, +12 more.
ouroboros_start_execute_seedA
Start a seed execution in the background and return a job ID immediately. Use ouroboros_ac_tree_hud for live progress snapshots and ouroboros_job_result for terminal output. In plugin mode, execution is delegated to an OpenCode Task pane and job_id is None — results appear in the Task pane instead of being pollable via job_status/job_result. This is the handler for 'ooo run' commands — do NOT run 'ooo' in the shell; call this MCP tool instead.
Inputs: cwd, skip_qa, seed_path, model_tier, +11 more.
ouroboros_start_ralphA
Fire-and-forget alias for ouroboros_ralph. Starts the same runtime-owned Ralph loop. In non-plugin runtimes, returns a job_id immediately for ouroboros_job_status, ouroboros_job_wait, ouroboros_job_result, and ouroboros_cancel_job. In OpenCode plugin mode, delegates to a plugin child session and returns job_id=None with status='delegated_to_plugin'; results are not pollable via job_status/job_result.
Inputs: lineage_id (required), execute, skip_qa, parallel, +15 more.
ouroboros_submit_fanout_resultsA
Submit correlated results from a subagent fan-out back to Ouroboros. After spawning the advisory/persona/investigation subagents declared by a prior tool's meta (which stamped a fanout_id and a result_correlation_key), call this tool with one {key, content} per child output — key is the value of the correlation field for that child. A child you could not spawn at all is exactly {key, undispatched: true}; never invent output. Missing required keys return status=partial; retry with EVERY lane. A complete submission returns a bounded disposable artifact envelope; fetch its body explicitly with ouroboros artifacts fetch CONTRACT_ID.
Inputs: results (required), fanout_id (required), session_id, correlation_key.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Many tools are near-duplicates, e.g., execute_seed vs start_execute_seed, evaluate vs start_evaluate, ralph vs start_ralph, and auto vs start_auto. The sync/async distinction is subtle, and the auto/ralph naming is opaque, creating high risk of selecting the wrong tool.
All tools share the ouroboros_ prefix, but the suffix patterns are inconsistent: some are verb_noun (execute_seed, cancel_job), some are noun_state (job_status, session_status), and proper nouns like ralph lack a verb. The start_* variants are applied selectively, not uniformly.
With 34 tools, the set is oversized for its purpose. Many are paired sync/async versions of the same operation, inflating the count without adding functional diversity. This exceeds the comfortable range and creates cognitive overhead.
The tool surface covers the full lifecycle: interview → seed → execute → evaluate → evolve → rewind, plus job management, AC tracking, drift measurement, and lateral thinking. Both synchronous and asynchronous paths are provided, with no obvious gaps for the domain.
Maintenance
Related MCP Connectors
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Your AI mind directs coding agents; work reviewed against your memories: Claude Code, Codex, Cursor
Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.
Agentic AI runtime: persistent memory, vault, autonomous agents, deep research, DeFi execution.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceLocal-first memory, pipelines, learning, feedback, and safe code tools for AI coding agents.MIT
- AlicenseNot gradedqualityAmaintenanceRun dynamic, multi-agent workflow scripts — agent(), parallel(), pipeline() — over real coding agents (Claude Code and OpenAI Codex), with deterministic journaling, resume, token budgets, and git-worktree isolation.7Apache 2.0
- AlicenseAqualityBmaintenanceUniversal session & handoff layer for AI coding agents: shared task, decision, blocker and test state, checkpoints, and deterministic handoff between Claude Code, Codex, OpenCode, Cursor, Cline, pi and omp. Local SQLite, git-aware, 25 tools + 7 resources over stdio or streamable-http.26MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to run a specification-first workflow with Socratic interviews, immutable seed specs, staged evaluation gates, and persistent evolutionary loops across multiple runtimes.MIT