Evolution Kernel CLI
Evolution Kernel loops over a git repo to improve code toward a measurable goal in a sandbox and commits accepted changes.
- 324 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The loop automatically edits and commits code, runs executors and spends the provider's paid tokens.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/evolution-kernelDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The loop automatically edits and commits code, runs executors and spends the provider's paid tokens.
This is third-party code. Review the repository files before installing.
What it does
Evolution Kernel is a small Python runtime (about 1,900 lines of core) that improves a repository's code toward a measurable goal. You set a metric, for example test results, `ruff` or a score from an HTTP endpoint, and the program repeats a loop: observe, plan, execute, evaluate. A model writes the plan from the metric and the history of past attempts. An executor, Aider or Claude Code, makes changes in an isolated git worktree inside a firejail sandbox. The metric is then measured again. An accepted change becomes a real commit on the `evolution/accepted` branch, a rejected worktree is discarded, and the experiment branch stays for audit. Every attempt is written to a ledger: goal, observation, plan, diff, evaluation, decision and reflection. The loop stops on iteration count, a `max_total_usd` limit or `max_total_tokens`. There is parallel search across k branches, an `allowed_paths` restriction and a null-model check that rejects metric gains with no real benefit.
Who it is for. Researchers and engineers who tune an agent harness or a codebase toward a metric and want an audit of every change.
Good fit when
- An agent's result on a set of checks must improve with each change kept as its own commit.
- Changes are limited to an `allowed_paths` list so the loop leaves the rest of the code alone.
- A run's budget is capped by a dollar amount and a token count.
- An accepted improvement is verified by rerunning with an empty model instead of the real one.
Not a fit when
- There is no metric or it is unstable: the loop optimises what is measured rather than the goal.
- Changes must be made by hand only with no automatic commits.
- The environment does not support the firejail sandbox.
Example request
Run the quick evolution-kernel example and show the decision ledger. Move to a real repository only after my confirmation.Limitations
The loop makes and commits changes on its own to the `evolution/accepted` branch, so pick a metric that cannot be gamed: a documented case shows the loop rewriting the task as a classical solver and bypassing the model. You need Python 3.10 or newer, `ruff` for the quick example and a provider key for a real run. The README's 85 percent SWE-bench figure is called a projection rather than a measured result. Version 1.1. The last commit dates from November 2026.
How to disable. Uninstall with the `pip uninstall` of the package you installed and delete the `evolution/*` branches and worktrees from your repository. The attempt ledger lives in the folder given by `--ledger`.
FAQ
How do I try it in ten minutes?
Install the package and `ruff`, run `examples/quickstart/setup.sh` and start `evolution-kernel --loop` with the example. Per the README the loop closes in about a second with no key and no cost.
Which executors are supported?
Aider and Claude Code. The planner and evaluator run on Anthropic and OpenAI adapters.
How is the loop stopped?
It ends on `max_iterations`, `max_total_usd`, `max_total_tokens` or after a run of consecutive failures. A verdict that the goal is reached also stops it.
What does the ledger store?
For each attempt it records goal, observation, plan, diff, evaluation, decision and reflection. The ledger survives a process restart.
Why the null-model check?
It replaces the model with an empty stub. If the metric holds, the gain came without the model and is rejected.
Discussion
No questions or reviews yet.
Related
CLI toolsAn open framework where language models and evolutionary selection find and improve code for optimization tasks
Parallel self-evolution of skills and prompts: workers propose edits and an aggregator merges them into one versioned artifact
An agent evolution framework that edits prompts and skills with parallel workers and keeps only what passes a held-out check.
Runs a coding agent over tasks with known answers, studies failures and writes new skills and prompts, versioned in Git.
cap-evolve edits an agent's prompts, tools and skills from failed traces and keeps an edit only if it wins on a held-out split
A CLI that runs your agent on tasks and revises its skills, keeping a change only when held-out tasks confirm the gain
README in short
Every step of the loop is isolated: a git worktree for edits, a firejail sandbox for the process and a ledger from which all decisions can be rebuilt without the program's memory.