evo — Summary

evo is a Python CLI + multi-host plugin that turns any codebase into an autonomous optimization loop: it discovers what to measure, instruments the benchmark, then runs a parallel tree-search with semi-autonomous subagents, each in an isolated git worktree (or remote sandbox), each reading shared failure traces before deciding what to try. The orchestrator uses configurable frontier strategies (argmax, top_k, epsilon_greedy, softmax, pareto_per_task) to select which branch to extend next, while cross-cutting scan subagents run RLM-inspired analysis to surface compound failure patterns. Gates (pass/fail checks) prevent the search from finding degenerate solutions. A web dashboard at http://127.0.0.1:8080 shows real-time experiment status. Runs on Claude Code, Codex, Cursor, Pi, Hermes, Opencode, and OpenClaw. Remote backends include Modal, E2B, Daytona, AWS, and Azure. evo is uniquely the only framework in this batch (and arguably in the entire catalog) designed for code optimization via tree search rather than feature development — its use case is "make this faster/better" rather than "build this feature." Compared to seeds, evo is closest to superpowers in its skills-only architecture, but with a radically different purpose: superpowers is behavioral scaffolding for developers, while evo is an autonomous research loop for optimizing code performance.

evo — Overview

Origin

evo was built by evo-hq (2 contributors). Apache-2.0 license. 770 stars. Published to PyPI as evo-hq-cli. Last pushed 2026-05-26 (active).

Philosophy

From the README:

"A plugin for your agentic framework that optimizes code through experiments. You give it a codebase. It discovers metrics to optimize, sets up the evaluation, and starts running experiments in a loop — trying things, keeping what improves the score, throwing away what doesn't."

Inspired by Karpathy's autoresearch (pure hill climb). evo adds:

• Tree search over greedy hill climb. Multiple directions can fork from any committed node
• Parallel semi-autonomous agents. Spawn multiple subagents simultaneously, each in its own git worktree
• Shared state. Failure traces, annotations, and discarded hypotheses accessible to every agent
• Gating. Regression tests or safety checks wired as gates; experiments failing a gate are discarded
• Observability. A dashboard to monitor experiments

Key Design Opinions

• Main stays clean: No evo-specific artifacts committed to main
• Baseline is a worktree: First experiment (exp_0000) is where benchmark and instrumentation live; main is untouched
• Ask the user as little as possible: Minimize friction; one question for benchmark selection
• Directive injection: User can send [EVO DIRECTIVE] messages mid-run via any hook channel; these are honored as authoritative
• Gates are mandatory for reliable search: Without gates, the optimizer finds degenerate solutions (return a constant, skip work, trade correctness for speed)

Supported Hosts

Claude Code, Codex, Cursor, Pi, Hermes, Opencode, OpenClaw

evo — Architecture

Distribution & Install

• Distribution type: cli-tool (Python, PyPI) + claude-plugin (skill-pack)
• CLI install: uv tool install evo-hq-cli
• Plugin install: evo install <host> (claude-code | codex | cursor | hermes | opencode | openclaw | pi)
• Version: 0.4.x (analyzed from skills and README)
• License: Apache-2.0
• Required runtime: Python (via uv), host CLI (claude-code, codex, etc.)

Directory Tree (repo)

evo/
├── sdk/                    # Python SDK for evo experiment management
├── plugins/
│   └── evo/
│       ├── .claude-plugin/ # Claude Code marketplace manifest
│       ├── .codex-plugin/  # Codex plugin manifest
│       ├── hooks/
│       │   └── hooks.json  # PreToolUse, UserPromptSubmit, SessionStart hooks
│       ├── skills/
│       │   ├── discover/   # SKILL.md — codebase exploration + benchmark setup
│       │   ├── optimize/   # SKILL.md — parallel subagent optimization loop
│       │   ├── subagent/   # SKILL.md — subagent execution protocol
│       │   ├── infra-setup/ # SKILL.md — remote backend setup
│       │   └── references/ # CLI quick reference, provider matrix
│       ├── bin/
│       │   └── evo-hook-drain  # Hook drain binary (receives hook events)
│       └── src/            # Plugin Python source
├── scripts/                # Developer utilities
└── tests/                  # Test suite

Target AI Tools

Claude Code (/evo:), Codex ($evo), Cursor (/), Pi (extension via pi-subagents), Hermes, Opencode, OpenClaw

Experiment Workspace Backends

Hook Architecture

The evo-hook-drain binary runs on all three hook events (PreToolUse, UserPromptSubmit, SessionStart). It drains the evo message queue into the agent's context, enabling the orchestrator to send directives to in-flight subagents via the hook channel.

evo — Components

CLI Commands (evo-hq-cli)

Skills

Hooks

All three hooks run the same drain binary, which delivers queued directives from the orchestrator to the current agent session.

Frontier Strategies

Web Dashboard

Starts automatically with /evo:discover at http://127.0.0.1:8080. Features:

• Experiment tree visualization
• Frontier strategy configuration
• Backend selection
• Scan results and failure patterns

evo — Uniqueness & Positioning

Differs from Seeds

evo is unlike any of the 11 seeds in its core use case: all seeds are about building features or enforcing development methodology, while evo is about optimizing existing code through autonomous tree-search experimentation. The closest seed is superpowers in its skills-only behavioral architecture (no slash commands, autonomous activation), but superpowers is a developer workflow framework while evo is an optimization research tool. The gate mechanism (auto-discard experiments failing pass/fail checks) has no analog in any seed. The [EVO DIRECTIVE] banner injection via hooks for mid-run orchestrator→subagent communication is a novel architectural pattern not seen in any seed. The multiple remote execution backends (Modal, E2B, Daytona, AWS, Azure) for running experiments in cloud sandboxes make evo the most infrastructure-connected framework in the catalog. claude-flow is the only seed approaching evo's operational complexity, but uses SQLite/vector memory while evo uses git-worktree isolation with shared state.

Positioning

evo targets ML engineers and performance engineers who want to automate the "try something, measure, keep or revert" research cycle. It is not a general-purpose development framework. The discover skill's ability to build a benchmark from scratch when none exists makes it accessible to projects without existing evaluation infrastructure.

Observable Failure Modes

• Gate degeneration: Without good gates, the optimizer finds shortcut solutions (constant return, skip computation). The quality of optimization is directly proportional to gate quality.
• Pool exhaustion: Failed experiments retain pool slots until discarded; evo discard <exp_id> is required to free capacity.
• CLI/plugin version drift: evo install updates the host plugin but doesn't update the global CLI; evo-version-check fails silently if not monitored.
• Remote backend cost: Modal/E2B/AWS backends incur cloud compute costs per experiment. High subagents counts on expensive benchmarks can run up bills quickly.
• Benchmark quality dependency: The entire search is only as good as the benchmark. A poorly designed benchmark optimizes the wrong thing.

Explicit Antipatterns (from SKILL.md)

• Committing evo artifacts to main (use worktrees)
• Skipping gates (degenerate solutions found without gates)
• Auto-installing CLI from agent context (use user-executed install commands)
• Running evo new when an experiment is already active in remote mode (use evo run <exp_id> for recovery)