Ouroboros

Claude Code that improves itself

Ouroboros runs silently in the background of every Claude Code session. When significant code changes happen, it debates itself — Proposer/Critic/Judge — and refines its own working rules based on what actually works.

No configuration. No commands. It just runs.

What it does

Debate Engine

Every significant code change triggers a three-way critique:

1. Proposer — makes the case for the approach
2. Critic — challenges it, finds weaknesses
3. Judge — synthesizes into a concrete recommendation

The outcome updates the adversarial rulebook. Better decisions compound over time.

Adversarial Rulebook

A self-modifying set of code quality rules. Rules that lead to good outcomes get reinforced. Rules that don’t get flagged for revision. The system learns what works in this codebase.

Amnesia Manager

Strategic memory compression. Ouroboros tracks what context is worth keeping across sessions and what can be safely dropped. Signal-to-noise stays high even in long-running projects.

Fork Manager

Parallel approach comparison. When there are multiple valid solutions, Ouroboros can spin up isolated forks, compare outcomes, and recommend the winner.

Installation

Ouroboros is installed per-project, not globally. It integrates with Claude Code’s settings system.

1
2
3

git clone https://github.com/headlessmode/ouroboros
cd ouroboros
python run_ouroboros.py --install /path/to/your/project

This:

1. Copies the system prompt to .claude/
2. Registers session hooks in .claude/settings.json
3. Initializes state files in .ouroboros/

From that point on, every Claude Code session in that project has Ouroboros active.

Architecture

.ouroboros/
├── config.json              # System bounds
├── system_prompt.md         # Always-active context
├── observer/                # Central state + task queue
├── scripts/                 # Debate, rules, amnesia, forks
├── debate/                  # Debate engine state
├── adversarial/             # Self-improving critique rules
├── amnesia/                 # Memory compression policies
├── telemetry/               # Outcomes and metrics
└── forks/                   # Parallel strategy comparisons

Free and open source

Ouroboros is MIT licensed. Install it, fork it, modify it.

Development notes and architecture decisions documented at headlessmode.com/journal.

Source on GitHub →