Lewati ke konten
TakoAPI
Kembali ke skill

evolution-kernel

oleh Protocol-zero-0

Aider
โ€”Belum ada penilaian
Penilaian Anda

Ringkasan

Self-improving code for any git repo: give it a measurable goal, a coding agent (Claude Code or Aider) proposes changes, the kernel scores them, keeps winners and rolls back failures. Open-source AlphaEvolve / FunSearch-style evolution loop, sandboxed, with an auditable ledger.

Deskripsi

# Evolution Kernel

<p align="center">
  <strong>A soul plugin for any code.</strong><br>
  Drop it into any git repository, give it a measurable goal, and the
  codebase begins to perceive its own environment, judge its own
  output, and rewrite itself toward the goal โ€” sandboxed, ledgered,
  every change a real git commit you can roll back.
</p>

<p align="center">
  <em>Code on disk does not evolve. But once a codebase can read its own
  outputs, hold a conversation with its own past, and shed failed
  experiments without leaving scars โ€” it stops being a body of text and
  becomes a process.</em>
</p>

<p align="center">
  <a href="README.zh.md">ไธญๆ–‡</a>
  ยท
  <a href="docs/protocol.md">Protocol</a>
</p>

<p align="center">
  <a href="https://github.com/Protocol-zero-0/evolution-kernel/actions/workflows/tests.yml">
    <img src="https://github.com/Protocol-zero-0/evolution-kernel/actions/workflows/tests.yml/badge.svg" alt="tests">
  </a>
  <img src="https://img.shields.io/badge/status-v1.1-brightgreen" alt="v1.1">
  <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python โ‰ฅ 3.10">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
  <img src="https://img.shields.io/badge/dep-PyYAML%20only-lightgrey" alt="Single dependency">
</p>

---

> ### โ–ถ Try in 10 minutes
>
> ```bash
> 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/](examples/quickstart/) for what just happened. For the LLM-driven version on a real OSS target, see [examples/oss_fix_demo/](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.

---

## A projected walkthrough: SWE-bench Verified

> ๐Ÿ“‹ The walk-through below sketches an end-to-end overnight evolution on SWE-bench Verified to illustrate what the runtime actually does: which model goes in, what kinds of moves the planner converges on, what the final ledger looks like. **The ~85% figure below is a projected target, not a measured result.** Reproducible v1.0 artifacts live in [`examples/sandbox_demo/`](examples/sandbox_demo/) and the 99-test suite in [`tests/`](tests/).

### Target: take Qwen3.6-35B-A3B (3B active params, released April 2026) from 73.4% to ~85% on SWE-bench Verified โ€” closing most of the gap to GPT-5.5, overnight, hands-off, fully audited.

```
                                  SWE-bench Verified (500 real GitHub bug-fixes ยท May 2026)
  GPT-5.5                       โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘  88.7%  โ† OpenAI, Apr 23 2026
  Claude Opus 4.7               โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘  87.6%  โ† Anthropic, current prod
  Gemini 3.1 Pro                โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘  80.6%
  Kimi K2.6                     โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘  80.2%
  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
  Qwen3.6-35B-A3B + us          โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘  ~85%   โ† projected target, not yet measured
  Qwen3.6-35B-A3B (vanilla)     โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘  73.4%  โ† public baseline
  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
  Gemma 4-31B (dense)           โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘  52.0%
```

**Why this benchmark.** SWE-bench Verified is the de-facto industry standard for evaluating coding agents in 2026 โ€” every frontier-lab release reports its score on it. 500 real GitHub bug-fix tasks, vetted by human annotators. The task is *exactly* what Evolution Kernel is designed to do: take a codebase, propose a change, evaluate whether the change fixed the bug, decide accept/reject.

**Why this model.** [Qwen3.6-35B-A3B](https://qwen.ai/blog?id=qwen3.6-35b-a3b) is Alibaba's flagship open-weight model (Apache 2.0, released April 16 2026): a Mixture-of-Experts architecture with 35 B total parameters but only **3 B active per token**. It runs on a single consumer GPU. At a 3 B active-parameter footprint โ€” roughly **30ร— smaller** than a frontier-class dense model โ€” it already lands at 73.4 % on SWE-bench Verified, **within 15 points of GPT-5.5 while costing fractions of a cent per task to run locally**.

**Why this gap is closable.** That 73.4 % already represents months of hand-tuned harness engineering by the Qwen team. The remaining gap to GPT-5.5 (88.7 %) is more of the same work โ€” better tool selection, parallel sampling, tighter verifier loops, error-pattern recovery โ€” and that is exactly what Evolution Kernel automates. Same model, same weights, an evolved harness.

**What the loop will do, generation by generation** (illustrative โ€” these are the *kinds* of moves the planner has historically converged to during internal prototyping):

```
Model: Qwen3.6-35B-A3B (frozen weights ยท 3B active params ยท Apache 2.0)
Benchmark: SWE-bench Verified ยท 500 real GitHub bug-fix tasks
Baseline: 73.4 %   Reference: GPT-5.5: 88.7 %   Claude Opus 4.7: 87.6 %

[gen 02] plan   โ†’ "Failures cluster on multi-file refactors. Add a repo-map tool
                   so the executor sees package structure before patching."
         executeโ†’ aider adds harness/repo_map.py
         eval   โ†’ 77.2 %  โ–ฒ+3.8 pts โ€” ACCEPT

[gen 05] plan   โ†’ "20% of remaining failures are 'patch breaks adjacent test'.
                   Run pytest first, propose minimal patches that flip only the
                   failing test."
         executeโ†’ aider rewrites harness/test_first_loop.py
         eval   โ†’ 79.6 %  โ–ฒ+2.4 pts โ€” ACCEPT

[gen 09] plan   โ†’ "Hard issues (multi-hunk) still fail. Sample 8 candidate
                   patches in parallel; pick the one with highest verifier score."
         executeโ†’ aider adds harness/best_of_n.py (parallel)
         eval   โ†’ 82.4 %  โ–ฒ+2.8 pts โ€” ACCEPT

[gen 14] plan   โ†’ "Verifier passes some wrong patches. Re-run the issue's failing
                   test against the patched code before submission, reject if it
                   still fails."
         executeโ†’ aider adds harness/strict_verifier.py
         eval   โ†’ 84.3 %  โ–ฒ+1.9 pts โ€” ACCEPT

[gen 19] plan   โ†’ "Combine best-of-8 with the strict verifier as the final filter.
                   Drop the cheap single-shot fallback."
         executeโ†’ aider integrates the two components
         eval   โ†’ ~85 %  โ–ฒ+0.7 pts โ€” ACCEPT  (within 4 pts of GPT-5.5)

[gen 25] STOP โ€” 4 generations with no significant improvement

{"halted": true, "reason": "max_consecutive_failures reached (4)"}
```

```
Final:  73.4 % โ†’ ~85 %   within 4 points of GPT-5.5 ยท within 3 of Claude Opus 4.7
        ~25 git commits ยท all changes in src/harness/
        Active params: 3 B (vs. ~175 B+ dense for frontier-class)
        Model weights: 0 bytes changed   Harness: ~800 lines of Python
        Spend on planner/evaluator LLM calls: target โ‰ค $80
        Inference cost on the target model: ~$0 (runs locally on a single GPU)
```

> **What this example shows.** A 3 B-active open-weight model plus an automatically evolved harness can close most of the gap to today's largest closed-source frontier โ€” at one-thirtieth the active-parameter footprint and near-zero inference cost. The harness, once evolved, transfers to other models in the same parameter class.

---

## Ledger: the complete audit trail

```
ledger/
  .evolution_state.json       โ† hard-stop state: iterations, failures, usd, tokens; survives restarts
  runs/
    0001/
      config.json             โ† full snapshot of your evolution.yml
      observation.json        โ† raw output of your evidence_sources commands
      planner_input.json      โ† goal + observation + history fed to planner
      plan.json               โ† LLM plan: summary ยท steps ยท expected_improvement
      executor_input.json     โ† plan + worktree path fed to executor
      executor_output.json    โ† executor result
      evaluator_input.json    โ† goal + patch + observation fed to evaluator
      patch.diff              โ† exact diff the executor applied
      candidate_commit.txt    โ† git SHA of the sandbox commit
      evaluation.json         โ† verdict + metrics + cost_usd + tokens_used
      decision.json           โ† accept / reject + reason
      reflection.json         โ† one-line summary injected into the next round
    0002/  ...
  halted/
    20260501T120000Z.json     โ† full run stats (iterations, usd, tokens) written when any hard stop fires
```

To undo every change from a session:

```bash
git checkout evolution/accepted
git reset --hard <baseline-sha>   # every accepted change is a named commit
```

---

## Architecture

```mermaid
flowchart LR
    Config[evolution.yml] --> Governor

    subgraph loop ["โ†ป  Loop until hard stop fires"]
        direction LR
        Governor -->|"planner_input.json\ngoal ยท observation ยท history"| Planner["๐Ÿง  Planner\nLLM"]
        Planner -->|plan.json| Executor["๐Ÿ”จ Executor\nAider / Claude Code\n(firejail-wrapped)"]
        Executor -->|patch in git worktree| Evaluator["โš–๏ธ Evaluator\nLLM + shell"]
        Evaluator -->|evaluation.json| Governor
    end

    Governor -->|"accept โ†’ git commit"| Branch["evolution/accepted"]
    Governor -->|"reject โ†’ discard"| Ledger[๐Ÿ“ Ledger]
    Governor --> Ledger
```

**The Governor is intentionally dumb.** It is pure orchestration โ€” zero LLM calls. All intelligence lives in the three role scripts. Swap any role for your own implementation; the Governor only cares about the JSON each role reads and writes.

**Roles communicate through files, not shared memory.** The planner never talks to the executor. The evaluator never sees the executor's self-assessment. The only shared state is the ledger.

---

## Quick Start

```bash
# 1. Install
pip install evolution-kernel

# 2. Describe your goal
cat > evolution.yml << 'EOF'
mission: "Evolve the harness so Qwen3.6-35B-A3B scores 85%+ on SWE-bench Verified"

evidence_sources:
  - type: shell
    command: "python3 scripts/run_swebench_verified.py --model qwen3.6-35b-a3b --json"

mutation_scope:
  allowed_paths: ["src/harness/"]

hard_stops:
  max_iterations: 30
  max_consecutive_failures: 4
  max_total_usd: 80.00

llm:
  provider: anthropic
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY

coding_agent:
  tool: aider

history:
  max_entries: 10

sandbox:
  enabled: true
  backend: firejail

roles:
  planner:   ["python3", "bundled:planner.py"]
  executor:  ["bash",    "bundled:executor.sh"]
  evaluator: ["python3", "bundled:evaluator.py"]
EOF

# 3. Run overnight
evolution-kernel --config evolution.yml --repo /path/to/project --ledger /tmp/ledger --loop
```

---

## Configuration reference

> All paths (`scripts/run_swebench_verified.py`, `src/harness/`) refer to **your target project**, not this repo. Replace them with your own benchmark command and source directory.

```yaml
# Required โ€” what "better" means for your project
mission: "Evolve the harness so Qwen3.6-35B-A3B scores 85%+ on SWE-bench Verified"

# How to measure the current state
evidence_sources:
  - type: shell         # stdout goes into observation.json
    command: "python3 scripts/run_swebench_verified.py --model qwen3.6-35b-a3b --json"
  - type: file          # file contents go into observation.json
    path: "metrics.json"
  - type: http          # GET a live endpoint; status, headers and body recorded
    url: "https://evals.example.com/run/latest"
    headers:
      Accept: application/json
    timeout: 10         # seconds (default 10)

# Only files under these paths may be changed
mutation_scope:
  allowed_paths:
    - "src/harness/"               # changes outside this list are auto-rejected

# When to stop
hard_stops:
  max_iterations: 30            # total rounds
  max_consecutive_failures: 4   # consecutive rejections before halt
  max_total_usd: 80.00          # 0 = unlimited
  max_total_tokens: 0           # 0 = unlimited

# LLM for planner and evaluator
llm:
  provider: anthropic           # anthropic | openai
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY

# Coding agent for executor
coding_agent:
  tool: aider                   # aider | claude-code

# How many past rounds the planner sees
history:
  max_entries: 10

# Population-level search: per round, spawn k independent worktrees, score
# each branch's fitness, promote the best, demote the rest to ledger/failed/.
# k=1 (default) is plain single-branch run_once behavior.
parallel:
  k_branches: 1

# Process sandbox: when enabled, the executor's argv is wrapped with firejail
# so the rest of the filesystem is read-only and only the worktree + the
# run's ledger directory are writable. Planner and evaluator are read-mostly
# and run unsandboxed.
sandbox:
  enabled: false                # set to true on machines with firejail installed
  backend: firejail
  extra_args: []                # appended verbatim before `--`

roles:
  # `bundled:` resolves to evolution_kernel/roles/<filename> inside the installed
  # wheel โ€” works for both `pip install evolution-kernel` and git-clone setups.
  # Or replace any entry with your own argv (`["python3", "myplanner.py"]`).
  planner:   ["python3", "bundled:planner.py"]
  executor:  ["bash",    "bundled:executor.sh"]
  evaluator: ["python3", "bundled:evaluator.py"]
```

**Switch to OpenAI:**
```yaml
llm:
  provider: openai
  model: gpt-5.5
  api_key_env: OPENAI_API_KEY
```

**Switch to Claude Code:**
```yaml
coding_agent:
  tool: claude-code
```

---

## CLI

```bash
# Loop until a hard stop fires  (recommended)
evolution-kernel --config evolution.yml --repo /path/to/repo --ledger /tmp/ledger --loop

# Single round
evolution-kernel --config evolution.yml --repo /path/to/repo --ledger /tmp/ledger

# Reset all hard-stop state (iterations, failures, budget) for a fresh session
evolution-kernel --ledger /tmp/ledger --reset
```

Exit codes: `0` clean finish ยท `3` halted by a hard stop.

---

## Install

```bash
pip install evolution-kernel
```

From source (only runtime dependency: PyYAML):

```bash
git clone https://github.com/Protocol-zero-0/evolution-kernel.git
cd evolution-kernel
pip install -e .
```

Python 3.10 or later.

---

## Tests

```bash
python3 -m pytest tests/ -v
```

**99 tests** ยท no network calls in CI ยท LLM roles replaced by lightweight fixture scripts ยท CI installs `firejail` so the sandbox E2E test runs against the real OS-level mount.

---

## Writing your own roles

Each role is an executable that receives:

```
--input    <path>    JSON the governor wrote for this role
--output   <path>    JSON the role must write before exiting
--worktree <path>    path to the isolated git sandbox checkout
```

The bundled `evolution_kernel/roles/planner.py`, `executor.sh`, and `evaluator.py` are the reference implementation, shipped inside the wheel โ€” reference them in your `evolution.yml` as `bundled:<name>`. Copy, modify, or replace them entirely โ€” with a shell script, a Docker call, or anything that reads `--input` and writes `--output`.

---

## Known limitations

Being honest about where v1.0 is *not* yet.

- **The evaluator is an LLM.** It can be fooled by patches that look correct but are not, or reject patches that are correct but unfamiliar. Use `goal_evaluator` + a strong programmatic gate in `evidence_sources` to anchor the LLM judgment to ground truth.
- **The sandbox is filesystem-only.** firejail blocks out-of-worktree writes. It does **not** block network access, fork bombs, or process injection. For untrusted executors, layer a network namespace or a VM on top.
- **History is summary, not replay.** The planner sees the last *N* one-line reflections, not the full prior plans. Long-horizon strategies need the planner to encode state into `plan.json` summaries itself.
- **Cost can compound.** A 30-round loop with Claude Sonnet planning + Claude Code execution can cost $40โ€“$100. The hard-stop budget is real โ€” set it lower than you think.
- **Real-provider integration is not in CI.** The 99 tests use fixture scripts in `tests/fixtures/`. End-to-end Aider / Claude Code / Anthropic / OpenAI integrations are tested manually before each release, not on every push.

---

## Project layout

```
evolution_kernel/        ~1,900-line runtime (Governor ยท Observer ยท HardStops ยท Sandbox ยท Config ยท CLI ยท Scope)
evolution_kernel/roles/  reference planner, executor, evaluator, goal_evaluator, strategist โ€” bundled in wheel, addressable as `bundled:<name>`
examples/                demo target + sandbox demo + working evolution.yml
docs/                    protocol spec + first-task spec
tests/                   99 unit + acceptance tests ยท 14 fixture role scripts
evidence/                checked-in artifacts of runs anyone can reproduce
```

---

## License

MIT โ€” see [LICENSE](LICENSE).

---

Evolution Kernel is a [JouleBeat](https://joulebeat.com/) project โ€” landing page at [evolution-kernel.joulebeat.com](https://evolution-kernel.joulebeat.com/), project brief at [joulebeat.com/projects/evolution-kernel](https://joulebeat.com/projects/evolution-kernel/).

Instalasi

Pasang skill dari https://github.com/Protocol-zero-0/evolution-kernel

Skill ini belum dipublikasikan di registri ClawHub. Tempel prompt ke coding agent Anda โ€” Claude Code, Cursor, Codex โ€” dan skill-nya akan dipasang langsung dari repositori sumbernya.

Buka repositori

Tautan