Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
How to install ouroboros?
q00/ouroboros
$git clone https://github.com/q00/ouroborosInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install ouroboros by running `git clone https://github.com/q00/ouroboros`, then use it for the current task and follow its documentation at https://github.com/q00/ouroboros.
README.md
| 1 | <p align="right"> |
| 2 | <strong>English</strong> | <a href="./README.ko.md">한국어</a> | <a href="./README.zh-CN.md">简体中文</a> |
| 3 | </p> |
| 4 | |
| 5 | <p align="center"> |
| 6 | <br/> |
| 7 | ◯ ─────────── ◯ |
| 8 | <br/><br/> |
| 9 | <img src="./docs/images/ouroboros.png" width="520" alt="Ouroboros"> |
| 10 | <br/><br/> |
| 11 | <strong>O U R O B O R O S</strong> |
| 12 | <br/><br/> |
| 13 | ◯ ─────────── ◯ |
| 14 | <br/> |
| 15 | </p> |
| 16 | |
| 17 | |
| 18 | <p align="center"> |
| 19 | <strong>Stop prompting. Start specifying.</strong> |
| 20 | <br/> |
| 21 | <sub>The <strong>Agent OS</strong> for replayable, specification-first AI coding workflows</sub> |
| 22 | </p> |
| 23 | |
| 24 | <p align="center"> |
| 25 | <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a> |
| 26 | <a href="https://github.com/Q00/ouroboros/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/Q00/ouroboros/test.yml?branch=main" alt="Tests"></a> |
| 27 | <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a> |
| 28 | <a href="https://github.com/sponsors/Q00"><img src="https://img.shields.io/github/sponsors/Q00?logo=githubsponsors&color=EA4AAA&label=sponsors" alt="GitHub Sponsors"></a> |
| 29 | </p> |
| 30 | |
| 31 | <p align="center"> |
| 32 | <a href="#quick-start">Quick Start</a> · |
| 33 | <a href="#why-ouroboros">Why</a> · |
| 34 | <a href="#what-you-get">Results</a> · |
| 35 | <a href="#the-loop">How It Works</a> · |
| 36 | <a href="#commands">Commands</a> · |
| 37 | <a href="#from-wonder-to-ontology">Philosophy</a> |
| 38 | </p> |
| 39 | |
| 40 | **Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, and Zcode.** |
| 41 | |
| 42 | Ouroboros is an **Agent OS** for AI coding: a local-first runtime layer that |
| 43 | turns non-deterministic agent work into a replayable, observable, policy-bound |
| 44 | execution contract. It replaces ad-hoc prompting with a structured |
| 45 | specification-first workflow: interview, crystallize, execute, evaluate, |
| 46 | evolve. |
| 47 | |
| 48 | --- |
| 49 | |
| 50 | ## The Ouroboros Agent OS Stack |
| 51 | |
| 52 | Like any OS, Ouroboros is split into a stable **OS layer** of primitives, an |
| 53 | **application layer** of domain workflows, and a **shell** that humans actually |
| 54 | sit in front of. Three repos, one stack: |
| 55 | |
| 56 | | Layer | Repo | Role | What it gives you | |
| 57 | | :--- | :--- | :--- | :--- | |
| 58 | | **Shell** (terminal client) | [`Q00/ourocode`](https://github.com/Q00/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 | |
| 59 | | **Apps** (domain workflows) | [`Q00/ouroboros-plugins`](https://github.com/Q00/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 | |
| 60 | | **OS** (this repo) | [`Q00/ouroboros`](https://github.com/Q00/ouroboros) | Agent OS core — Seed, Ledger, Runtime, MCP, safety boundaries | `ooo` commands, spec-first workflow engine, multi-runtime adapter | |
| 61 | |
| 62 | **How they connect:** |
| 63 | |
| 64 | ``` |
| 65 | ourocode ──► ooo / ouroboros-plugins ──► ouroboros core (Seed · Ledger · MCP · Runtime) |
| 66 | shell user-level apps kernel |
| 67 | ``` |
| 68 | |
| 69 | - The **kernel** (`ouroboros`) owns the contract: every action becomes a |
| 70 | Seed-bound, ledger-recorded, replayable event — regardless of which LLM |
| 71 | executes it. |
| 72 | - **Plugins** (`ouroboros-plugins`) declare scoped capabilities against that |
| 73 | contract, so domain workflows (review a PR, triage a Linear ticket, run a |
| 74 | release) stay auditable and policy-bound instead of being one-off prompts. |
| 75 | - **Ourocode** is the terminal shell: it surfaces MCP state, interview |
| 76 | questions, and wonderTool decisions as first-class TUI elements, so you can |
| 77 | drive the OS without leaving the keyboard or switching between CLIs. |
| 78 | |
| 79 | Use `ouroboros` alone with any supported CLI, layer plugins on for domain |
| 80 | workflows, or install `ourocode` when you want a unified terminal cockpit. |
| 81 | |
| 82 | > **Disclaimer.** The Ouroboros project and community are **not affiliated with |
| 83 | > any |
Related
6 picksType
- langchain-mcp-adaptersMake Anthropic Model Context Protocol (MCP) tools compatible with LangChain and LangGraph agents.Jul 2026
- mcporterTypeScript runtime and CLI for connecting to configured Model Context Protocol servers.Jul 2026
- mcp-proxyA MCP server which proxies requests to a remote MCP server over streamable HTTP or SSE.Jul 2026
- mcp-atlassianThe Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification.Jul 2026
- open-webuiOpen WebUIJul 2026
- rulesyncUnified AI rules management CLI tool that generates configuration files for various AI development toolsJul 2026
