Evolution Kernel

---

▶ Try in 10 minutes

pip install -e . && pip install ruff
bash examples/quickstart/setup.sh
evolution-kernel \
  --config examples/quickstart/evolution.yml \
  --repo /tmp/ek-quickstart-target \
  --ledger /tmp/ek-quickstart-ledger \
  --loop

Closes the full loop in ~1 second, $0, no API key. See examples/quickstart/ for what just happened. For the LLM-driven version on a real OSS target, see examples/oss_fix_demo/.

Measured, with a null-model control

A self-improving loop will happily optimize the metric instead of the goal. So before any number counts, we rerun the evolved harness with the model replaced by an empty stub.

Run	Before → after	Same harness, model replaced by empty stub	Verdict
Store-assistant agent (tool calls over a private database)	0/12 → 12/12	0/12	Real gain: the model does the work
Wordle agent	15% → 100%	still 100%	Rejected: the loop wrote a classical solver and routed the model out

The second row is why the check exists. Both runs passed the metric; only one improved the agent. Null-model ablation is now a gate on every result we report.

How the loop works

   ┌─ Observe ─┐    ┌─ Plan ─┐    ┌─ Execute ─┐    ┌─ Evaluate ─┐
   │  metrics  │ →  │  LLM   │ →  │ worktree  │ →  │   re-run   │
   │ ruff/test │    │ + hist │    │  + agent  │    │   metric   │
   └─────┬─────┘    └────────┘    └─────┬─────┘    └──────┬─────┘
         │                              │                  │
         │            ┌─────────────────┴──────────────────┘
         │            ▼
         │     ✅ accept → real git commit on evolution/accepted
         │     ❌ reject → worktree discarded, experiment branch kept for audit
         │            │
         └────────────┴────► ledger: goal · obs · plan · diff · eval · decision · reflection
                                       (every step replayable, every change rollback-able)

Each pass writes a complete forensic record to runs/<id>/. Nothing the kernel decides is held in memory; everything is reconstructable from the ledger alone.

---

Motivation

Frontier-class agent behavior is the joint product of the model and the harness that runs it — prompt structure, tool loop, sampling and best-of-N, verifier, retry policy. Today that harness is hand-tuned by senior engineers at every serious AI lab, and the resulting code is usually the actual ceiling against which the base model is judged.

Evolution Kernel makes harness tuning a reproducible runtime. Point it at a target repo with a measurable goal, walk away. Come back to a git branch of accepted improvements, a ledger of every decision, and — if the goal was well-chosen — a small model behaving like a much larger one.

What that buys you, concretely:

• Inference cost collapses. A 3 B-active model runs locally at fractions of a cent per task; the frontier APIs (GPT-5.5, Claude Opus 4.7) bill in dollars. Closing the capability gap without retraining moves an agent stack from "expensive to run at scale" to "near-zero marginal cost at scale".
• Production reliability is mechanical, not aspirational. Every decision is ledgered, every accepted change is a named git commit, every experiment runs in a git-worktree sandbox plus a firejail OS-level sandbox. The whole runtime is ~1,900 lines and was designed to be put in production, not demoed.
• A harness is a portable asset. Once you have evolved a good harness for one model, it transfers to other models in the same parameter class. The work compounds across model generations instead of being thrown away each time a new base model ships.

---

What it does

Point Evolution Kernel at any git repository and give it a measurable goal. It runs a closed loop:

Step	What happens
🔍 Observe	Run your metric command, or pull live state from an HTTP endpoint — current win rate, latency, eval score, …
🧠 Plan	LLM reads the metric + history of prior attempts, produces a concrete plan
🔨 Execute	Coding agent (Aider or Claude Code) applies the plan inside an isolated git worktree, wrapped in a firejail sandbox
⚖️ Evaluate	Re-run your metric; LLM decides accept or reject
✅ Commit / rollback	Accepted → real git commit on evolution/accepted. Rejected → worktree discarded
🔁 Loop	Repeat until max_iterations, max_total_usd, or max_total_tokens fires

Every attempt is written to a ledger: goal, observation, plan, diff, evaluation, decision, reflection. Nothing is held in memory. An external auditor — or your future self — can reconstruct every decision from the ledger alone.

---

What works today (v1.0, shipped on main)

Capability	Status
Multi-round LLM loop with memory (history injection)	✅
Budget guards: max_total_usd, max_total_tokens	✅
Iteration / consecutive-failure hard stops	✅
Full ledger audit trail (survives process restarts)	✅
Git worktree sandbox — every attempt isolated	✅
Scope enforcement — rejects changes outside allowed_paths	✅
Config-driven: swap LLM provider, model, coding agent	✅
Aider and Claude Code executor adapters	✅
Anthropic and OpenAI planner/evaluator adapters	✅
Goal evaluator — stops when mission is "won"	✅
k-branch parallel exploration (FunSearch / AlphaEvolve style)	✅
Process sandbox via firejail — executor cannot write outside its worktree	✅
Remote observer — HTTP evidence source for live dashboards / eval endpoints	✅

Numbers: 99 acceptance / unit tests · CI green on Python 3.10 + 3.12 · single runtime dependency (PyYAML) · ~1,900-line core runtime.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗