Evolve Loop wraps your AI coder in a structured, self-healing pipeline: it plans the work, an independent reviewer challenges it, only safe changes merge — and every run makes the next one smarter. Nothing ships unless a test failed first.
$curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh
The bottleneck moved
AI can write a feature, fix a bug, or refactor a module on its own. Writing code isn't the bottleneck anymore — trusting it enough to merge without reading every line is.
Most tools stop at "an AI wrote it." The hard part is everything after: was it the right change, is it actually correct, and will it break something downstream?
The idea
Deciding what to build, how to build it, and what looks wrong is where AI shines — so the pipeline lets it make those calls freely.
What's safe to ship is decided by a structured, repeatable process with guardrails the AI can't talk its way past. Freedom where it helps, structure where it counts.
AI-composed pipeline
Give it a goal. The advisor runs the mandated fundamentals, picks from the common phases, and writes brand-new ones when the goal needs them — then routes each phase to the right LLM and model: Claude Code, Codex, or Gemini, per policy. The combinations are unlimited; nothing here is pre-scripted.
Per-phase LLM routing
The advisor gives each phase to an LLM and model per policy — balancing ownership across Claude Code, Codex, and Gemini, and keeping the builder and auditor on different families so the review stays honest.
Advisor ▸ reasoning
The integrity floor
Bypass mode means “don’t ask the operator” — never “skip the checks”. A compiled-in floor evaluates every cycle before anything ships. Flip the evidence and watch the verdict change.
ship ⇒ build ∧ audit ∧ ( tdd ∨ trivial ) ∧ gates
try a cycle
These are compiled Go defaults, not config you can forget to set. The floor holds even when every prompt in the pipeline is written by a model.
When things fail
Every abnormal exit is classified and routed by a failure adapter: retry, re-route to another provider, re-pin, or reconcile. The queue survives, the evidence stays honest, and the loop continues.
Caught in production: This is not hypothetical: an experiment with a new model once slipped several regressions into a single run. Not one reached a human — the pipeline's own reviews caught every one, recovered, and within two days turned each into a permanent safeguard. Runs can fail; failures become fixes that stick.
Continuous development
The queue is the steering wheel. While the loop runs, you drop a weighted JSON file into .evolve/inbox/ — triage reads the weights every cycle, picks the top of the queue, and everything else ages forward. No restart, no lost work, no waiting for a gap. And when a cycle's audit goes red — reality, not the exception — the failure is routed, not fatal: the retro classifies it, a lesson files back into the queue as its own todo, and the item returns re-weighted with its worktree preserved. Watch it happen below: every third cycle fails, and the queue only gets smarter.
compose a todo → .evolve/inbox/<ts>-<id>.json
Real schema, abbreviated: id, weight, title, kind, fix — plus acceptance[] criteria the auditor enforces.
the queue — triage picks by weight, every cycle
Built for parallelism
Give each feature its own loop and they run side by side — each in its own git worktree and branch, each on its own LLM, each composing the pipeline its goal needs. They never step on each other, and only green changes merge to main, one at a time.
Point a loop at each goal; they advance in parallel, not in a queue.
Each loop owns a worktree + branch — no crossed wires, no half-merges.
Only green work reaches main, one merge at a time.
All you need is an LLM CLI subscription. Each lane runs on a CLI you're already signed into — Claude, Codex, or Gemini.
Usage
Start with a goal. Add a flag only when you want more — here's what each does behind the scenes.
/evo:loop "add dark mode"
Just a goal. The advisor composes the whole pipeline — which phases run, which LLM runs each, and how many cycles. It stops when the work is done.
/evo:loop harden
Steer the approach. A strategy (harden · repair · innovate · balanced) shifts scope and strictness — same phase spine, different posture.
/evo:loop --cycles 3 "add dark mode"
Bound the cycles. --cycles N is a hard contract: exactly N cycles, never early-stopped.
/evo:loop --cycles 3 harden "tighten input validation"
Stack the levers. Compose them — a strategy, a hard cycle bound, and a goal in one command. This is the full-control end of the spectrum.
/evo:loop --resume
Resume. Picks a checkpointed run up exactly where it stopped — worktree and state intact, no work lost.
echo '{"id":"fix-flaky-auth-test","weight":0.9}' > .evolve/inbox/fix-flaky-auth-test.json
Queue a backlog. Drop JSON todos into .evolve/inbox/ — the loop drains them strictly by weight, batches related items into one cycle, and re-weights recurring pain automatically.
"route": "console-manual"
Route the work. One field decides ownership: console-* marks an item operator-owned — autonomous lanes structurally cannot draw it (refused at plan time AND at claim). "lane" overrides a false positive. Routing is plumbing, not a prompt.
policy.json → "fleet": {"count": 3}
Go wide. Parallel isolated lanes in their own git worktrees. Quota pressure shrinks the width gracefully — never below one isolated lane, never onto your main tree.
evolve release 22.7.0
Publish. A self-healing release pipeline: preflight gates, changelog, atomic version bump, CI-verified publish, auto-rollback on failure. One command, no ceremony.
/evo:setup
Run once: it detects your installed LLM CLIs and offers three presets. One choice writes per-phase model routing to .evolve/policy.json. Skip it entirely and the loop runs with sensible all-Claude defaults — most people never open the file.
What makes it work
How it compares
| A single-LLM loop | Evolve Loop | |
|---|---|---|
| Decides what to build | You spell out every step | It plans and scopes the work |
| Quality gate | An AI says "looks good" | An independent review has to pass |
| When something breaks | Start over | Self-heals, recovers, and learns |
| Memory | Forgets between runs | Compounds — every run teaches the next |
| Models | One vendor, one model | Any model — the best one per job |
| Best for | Quick throwaway edits | Work you actually have to merge |
Think of the agent as the developer, and Evolve Loop as the team and process around it — the planning, the review, and the discipline that make the output safe to ship.
Try it in 90 seconds
No account. No telemetry. One static binary — the installer verifies its checksum, sets up your PATH, and wires the skills into whichever AI CLI you already use.
Install Evolve Loop v22.7.0macOS & Linux · Apple Silicon + x64 · Windows via WSL2
curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh✓verified end-to-end on macOS, Debian, and Alpine
then, in your AI CLI
evolve doctor/evo:loop --cycles 3 "add dark mode"Pin a version: EVO_VERSION=v22.7.0 … | sh · opt out of PATH edits: EVO_NO_MODIFY_PATH=1
$ curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh evolve-install: trying prebuilt: …/evolve_darwin_arm64.tar.gz evolve-install: checksum verified evolve-install: detected AI CLI(s): claude codex Installation complete! evolve-install: installed: evolve 22.1.0 → ~/.local/bin/evolve evolve-install: done. Next: evolve doctor then /evo:loop --cycles 3 "your goal"
Open source. Apache-2.0. Works with Claude, Gemini, and Codex.
$curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh