gemini-evolve

What is gemini-evolve?

gemini-evolve is an optimization loop for Gemini CLI users that stops you hand-tuning GEMINI.md: it mutates your instructions, commands, or skills, grades each variant by actually running the Gemini CLI on real eval tasks, and only writes back when a holdout set (examples it never trained on) shows the new version is genuinely better. It uses GEPA (via DSPy) as its default engine with a lighter built-in tournament GA as an alternative, enforces hard apply gates (non-empty, size cap, growth cap, minimum 2% holdout improvement), and shells out every model call to your local 'gemini' CLI — same auth, tools, skills, and MCP servers as your real sessions, with no separate API key.

Key features

• Evolves four target types: global ~/.gemini/GEMINI.md (15KB cap), per-project .gemini/GEMINI.md (15KB), custom commands/*.toml (5KB), and skills/**/*.md (15KB)
• Two engines: GEPA (Generative Evolutionary Prompt Adaptation, reflection-driven, via DSPy — the default) and a lighter built-in tournament GA (--engine ga)
• Five hard apply gates: non-empty content, per-target size cap, growth within max_growth_pct (default 20%), holdout improvement ≥ min_improvement_pct (default 2%), and content actually differs — fail any one and nothing is written
• Three eval sources: synthetic (Gemini generates tasks from your instructions, the default), session (mines real user messages from ~/.gemini/tmp session logs, skipping secret-looking content), and golden (your own JSONL)
• No SDK or API-key handling — every model call shells out to the local gemini CLI, reusing your existing auth, tools, skills, and MCP servers
• --apply backs up the original as GEMINI.md.<timestamp>.bak; rollback is a single cp
• Automation triggers: 'trigger watch' (evolve when a session goes quiet, cross-platform), macOS launchd cron every N hours, and a git post-commit hook that fires only on commits touching GEMINI.md/.gemini/
• Variant evaluation runs in Gemini plan mode (--approval-mode plan), which blocks tool execution; a light GEPA run is roughly 20 gemini calls and 3–5 minutes

Who it's for

• Gemini CLI users whose GEMINI.md has grown vague, duplicated, or stale after months of hand edits
• Developers who want measured, A/B-tested instruction improvements — evidence instead of vibes — with overfitting caught by a holdout comparison
• Teams maintaining custom Gemini CLI slash commands (commands/*.toml) and skill definitions who want them optimized against real usage
• Users who want continuous background improvement via session watching, macOS launchd scheduling, or git hooks

When not to use it

For things you already know are wrong in your GEMINI.md, just edit them by hand — the tool targets what you don't know, like which phrasing of a rule actually changes Gemini's behavior. It also requires Python 3.11+, a working logged-in Gemini CLI, and macOS or Linux (Windows is untested; the launchd cron trigger is macOS-only), and it's Gemini-CLI-native rather than a general prompt-eval harness like promptfoo.

FAQ