Full ledger
Every decision is written down — observation, plan, diff, evaluation, verdict, reflection. Reconstruct the run from the ledger alone.
Project brief · Infrastructure
Evolution Kernel
A soul plugin for any code. Drop the kernel into any git repository, give it a measurable goal, and the codebase begins to perceive its environment, judge its own output, and rewrite itself toward the goal.
01 / LOOP
Observe, plan, act, judge, commit.
Mechanism
Each iteration runs your metric command — or pulls live state from an HTTP endpoint — then lets the planner read the metric plus the history of prior attempts and produce a concrete plan. A coding agent applies the plan inside a git worktree wrapped in firejail; the metric is re-run, and the change is accepted or rejected.
Accepted changes land as real git commits on an evolution branch; rejected worktrees are discarded. The loop runs until max_iterations, max_total_usd or max_total_tokens fires.
02 / GUARANTEES
Built to be distrusted.
Real commits
Every accepted change is a named git commit. One git reset rolls back to any prior point.
Path guard
Edits outside allowed_paths are auto-rejected before the diff is applied.
OS sandbox
firejail wraps the executor process; the rest of the filesystem is read-only.
Hard budgets
max_total_usd, max_total_tokens, max_iterations — durable across restarts. The budget actually halts the loop.
Swappable roles
Planner, executor and evaluator are decoupled processes that talk through files. Aider, Claude Code, Anthropic, OpenAI — swap by config.
03 / STATUS
A small core, a worked example.
Open source
The kernel is MIT-licensed and pip-installable, with a small Python core built on a single dependency (PyYAML) and CI green on Python 3.10 and 3.12. The README walks through a worked example on SWE-bench Verified.
VISIT
evolution-kernel.joulebeat.com
Plug it in.
Read the protocol on the live site, or go straight to the source.