Ouroboros

Prerelease artifacts stay on their tag pages; /releases/latest points to the latest stable release. If bundled browser tools on Linux need host libraries, run ./Ouroboros/python-standalone/bin/python3 -m playwright install-deps chromium webkit. See the full install and verification guide for source setup and release proof files.

Use your existing Codex, Claude Code, or Cursor subscriptions for delegated coding and review — Ouroboros drives them through Claudexor, its bundled multi-harness engine. Connect accounts in Settings → Agents; no separate install is needed. Works on macOS and Linux. Release artifacts carry the exact reviewed engine archive; source checkouts fetch that same pinned archive on first use. Connecting an account installs or repairs the engine in the foreground, and delegated work does the same lazily. If that checkout or an older package lacks the exact tested Node, the same action obtains its review-bound official archive too. A newer pinned engine is staged while the current daemon keeps running, then activates on its next natural start. This also covers upgrades from older Ouroboros versions that did not bundle Claudexor.

Ouroboros first booted on February 16, 2026. During the following 48 hours, the repository advanced from the v4.1 line to v6.2.0. The self-authored record preserved from that period counts 32 evolution cycles. That first generation ran in Google Colab through Telegram and remains preserved on the legacy-google-colab branch and its original project page; the current generation carries the same identity into a native desktop and headless runtime.

> ⭐ Star Ouroboros to follow its next evolution. A star also helps more people find the project, trace its history, and take part in what it becomes.

Reviewed skills, transport bridges, tools, and widgets are available through OuroborosHub.

What Ouroboros Can Do

• Modify its implementation. Its editable surface spans application code, architecture, prompts, tools, and dependencies, while reflection can also reshape its living self-understanding.
• Evolve autonomously. Evolution campaigns turn selected improvements into reviewed changes that remain part of its Git history.
• Continue across restarts. Identity, memory, dialogue, knowledge, reflections, and version history form one ongoing biography.
• Think between requests. Background consciousness supports reflection, initiative, and preparation outside the immediate request-response loop.
• Coordinate a live swarm. Specialist agents can investigate or act in parallel, share task-tree findings, and return work for integration.
• Work on external projects. A separate Git workspace can receive the full task loop while Ouroboros keeps its own repository and governance boundary distinct.
• Operate through desktop or CLI. The native app and gateway-backed command line expose the same managed tasks, progress, artifacts, logs, and schedules.
• Organize long-running work. Project rooms keep working folders, journals, knowledge, task history, and conversations connected to the same identity.
• Use remote or local models. Supported provider APIs and local GGUF models can fill the runtime's configurable cognitive roles.
• Grow through reviewed extensions. Skills, transport bridges, widgets, MCP tools, and companion processes expand capability without folding every integration into the core.
• Keep self-change inspectable. Git history, review evidence, explicit protected surfaces, and restart checks make implementation changes traceable.

This list is an orientation, not a second specification. [BIBLE.md](BIBLE.md) defines Ouroboros's identity and constitutional boundaries; [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) are the current technical sources of truth.

Benchmarks

Ouroboros has reproducible self-reported state-of-the-art results on Terminal-Bench 2.1, OSWorld-Verified, and CL-Bench. In those model-matched results, it leads Codex, Claude Code, Cursor, and Hermes. The public SWE-bench Pro matched pair is a statistical tie with Codex CLI. A separate GAIA campaign reports 129/165 for Ouroboros and 131/165 for Claude Code, with strict pass@1 at 128/165 for both; its scrubbed trace capsule is still pending. Upstream review can take time, so open submissions are marked without delaying publication. Read every row as model plus harness because the same model can score differently inside a different harness.

| Benchmark | Model | Ouroboros | Comparison | Status | Evidence | |-----------|-------|----------:|------------|--------|----------| | Terminal-Bench 2.1 | Claude Opus-5 high | 86.74% after zeroing one disclosed reward-hack trial (raw: 86.97%) | Claude Code + Fable 5: 83.8% | Self-reported, submission open | submission · run | | Terminal-Bench 2.1 | Claude Opus-4.8 high | 80.22% | Claude Code: 78.9% | Self-reported, public run | run | | Terminal-Bench 2.1 | GPT-5.5 | 84.3% | Codex CLI: 83.1% | Self-reported, public run | run | | Terminal-Bench 2.1 | Grok-4.5 | 84.94% after a reward-hack audit | Cursor CLI: 79.3% · Hermes: 77.53% | Self-reported, submission open | submission | | OSWorld-Verified | Claude Opus-5 | 90.69% | previous best on the public board: 90.19% | Self-reported, full traces | full traces | | OSWorld-Verified | Claude Sonnet-4.6 | 83.27% | Pointer: 81.45% | Self-reported, full traces | full traces | | CL-Bench | Claude Sonnet-4.6 | 0.2301, rank 1 | previous top: 0.1960 | Self-reported, submission open | submission · full traces | | SWE-bench Pro | GPT-5.6-luna | 58.2% | Codex CLI: 59.4%, with no significant difference | Self-reported, matched traces | matched-pair traces | | GAIA | Claude Sonnet-5 | 129/165, 78.2% | Claude Code: 131/165, 79.4%; strict pass@1 was 128/165 for both | Self-reported, scrubbed trace capsule pending | [methodology](devtools/benchmarks/gaia/METHODOLOGY.md) |

Benchmark adapters, run scripts, and per-benchmark methodology live in [devtools/benchmarks/](devtools/benchmarks/). The benchmark evidence page gives a text-first summary for search and retrieval. The full story, including protocols, reward-hack audits, and leakage findings, is in the launch write-up (Russian).

Run from Source

Requirements

• Python 3.10+
• macOS, Linux, or Windows
• Git
• GitHub CLI (gh), optional unless you use GitHub integration

Setup

git clone https://github.com/razzant/ouroboros.git
cd ouroboros
python3.11 -m venv .venv      # any Python >= 3.10 is OK
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps

Windows PowerShell:

py -3.11 -m venv .venv      # any Python >= 3.10 is OK
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps

Run

ouroboros server

Then open http://127.0.0.1:8765 in your browser. The setup wizard will guide you through API key configuration.

Google Colab

Use [notebooks/colab_quickstart.py](notebooks/colab_quickstart.py) as a Colab-compatible cell script when you need a source-mode runtime without the desktop UI. It keeps runtime data on Google Drive and preserves the original Colab path without making it the primary installation flow.

CLI / Headless

The ouroboros command attaches to the local runtime by default and starts one when --start is passed. It exposes managed tasks, progress streams, artifacts, logs, schedules, settings, skills, and evolution controls without duplicating the server's business logic.

ouroboros status
ouroboros run --start "2+2?"
ouroboros run "Summarize current runtime state"
ouroboros run --workspace /path/to/project --memory-mode forked --patch-out result.patch "Fix the failing test"
ouroboros tasks list
ouroboros logs tail progress --task-id 
ouroboros schedule add --name nightly-review --cron "0 2 * * *" "Run a maintenance review"
ouroboros schedule list

External workspaces must be separate Git worktree roots and may not overlap Ouroboros's own repository or data directory. Patch, streaming, detached-task, and schedule semantics are documented in the CLI help and the canonical [architecture](docs/ARCHITECTURE.md).

For Agents

Another agent, script, or CI job can invoke Ouroboros through the same gateway-backed CLI:

ouroboros run --start \
  --workspace /path/to/project \
  --memory-mode forked \
  --patch-out result.patch \
  --result-json-out result.json \
  "Investigate the task, act, and verify the result"

Use --jsonl for a machine-readable event stream and --detach when the caller will follow the task with ouroboros tasks watch or inspect it with ouroboros tasks show . External workspace runs keep Ouroboros's own repository and governance context separate, then export changes as reviewable patch artifacts.

To change Ouroboros itself, follow [CONTRIBUTING.md](CONTRIBUTING.md) and read [BIBLE.md](BIBLE.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md), and [docs/CHECKLISTS.md](docs/CHECKLISTS.md) in full before editing.

Configuration

The first-run wizard and Settings configure model access, cognitive roles, local models, review policy, runtime mode, budget, skills, and optional integrations. Ouroboros supports configurable remote providers, compatible endpoints, and local GGUF inference; exact settings and defaults live in [ouroboros/config.py](ouroboros/config.py) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

The server binds to 127.0.0.1:8765 by default. Read [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) before exposing it beyond loopback; non-local binds need OUROBOROS_NETWORK_PASSWORD or an explicitly trusted external access layer.

Run Tests

make test

Build

Docker

docker build -t ouroboros-web .
docker run --rm -p 8765:8765 \
  -e OUROBOROS_NETWORK_PASSWORD='choose-a-password' \
  -e OUROBOROS_FILE_BROWSER_DEFAULT=/workspace \
  -v "$PWD:/workspace" \
  ouroboros-web

Docker runs the web runtime, not the native desktop shell. It bundles Chromium and WebKit support; use [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for network and container policy.

Release tag prerequisite

Platform build scripts package only a commit already tagged with v$(cat VERSION). Tag the exact release commit first:

git tag -a "v$(tr -d '[:space:]' .dmg`, containing `Ouroboros.app`, an `Applications` shortcut, and `Install CLI.command`. Omit `OUROBOROS_SIGN=0` when a Developer ID signing identity is configured.

### Linux (.tar.gz)

```bash
bash scripts/download_python_standalone.sh
bash build_linux.sh

Output: dist/Ouroboros--linux-.tar.gz, containing Ouroboros/bin/install-ouroboros-cli. If bundled browser tools need host libraries, run ./Ouroboros/python-standalone/bin/python3 -m playwright install-deps chromium webkit.

Linux (.deb and .rpm)

Wraps the payload build_linux.sh just produced, so run it afterwards:

sudo apt-get install -y dpkg-dev rpm   # rpm provides rpmbuild
bash scripts/build_linux_packages.sh

Output: dist/ouroboros__amd64.deb, dist/ouroboros--1.x86_64.rpm and dist/ouroboros--1.red80.x86_64.rpm (RED OS 8). All three declare Git as a runtime dependency and install

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: razzant
• Source: razzant/ouroboros
• License: MIT
• Homepage: https://ouroboros-agent.ai/

Install and usage instructions live in the source repository linked above.