pi-evolve

Evolutionary code optimization for pi — an AI coding agent that runs in your terminal.

This is the pi extension for cevolve, which provides the genetic algorithm backend.

---

What is this?

cevolve uses genetic algorithms to explore combinations of optimization ideas. Instead of trying changes one at a time (hill-climbing), it maintains a population of configurations and evolves them through selection, crossover, and mutation.

pi-evolve integrates cevolve into pi:

• Provides tools (evo_init, evo_next, evo_eval, etc.) for the agent to drive evolution
• Adds a skill that teaches the agent the workflow
• Shows a live dashboard widget (Ctrl+Shift+E)

See the cevolve README for algorithm details and the theory behind it.

---

Installation

Requires cevolve:

uv tool install cevolve
# or: pip install cevolve

Install the extension:

pi install https://github.com/jnormore/pi-evolve

---

Usage

# Create a branch (recommended)
git checkout -b evolve/my-optimization

# Start evolve
/evolve optimize my training script for lower val_bpb

Or load the skill directly: /skill:evolve

The agent will:

1. Analyze your code and form a hypothesis
2. Create a benchmark script (evo_bench.sh)
3. Propose optimization ideas
4. Run experiments, evolving the best combinations
5. Commit the winning configuration

---

Tools

Tool	Description
evo_init	Initialize session with ideas to explore
evo_next	Get next individual to evaluate
evo_eval	Run benchmark and record result (auto-reverts)
evo_status	Get current session state
evo_rethink	Analyze results, add/remove ideas
evo_stop	Finalize session
evo_sessions	List/switch sessions

---

Commands & Shortcuts

Command	Description
/evolve	Toggle evolve mode
/evolve <goal>	Start with a goal
/evolve off	Turn off
Ctrl+Shift+E	Toggle dashboard

---

Files

Sessions stored in .cevolve/{session-name}/ (managed by cevolve).

---

See Also

• cevolve — The Python backend with algorithm details
• pi — The AI coding agent

---

License

MIT