evo — Autoresearch Orchestrator for Codebases
Turns your codebase into an autoresearch loop that discovers what to measure, sets up the benchmark, and runs tree search with parallel subagents.
- Source repo
- evo-hq/evo
- Stars
- ★ 1.5k
- Last updated
- 14d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer wanting to automatically optimize a codebase's performance before committing, without manually managing experiments.
- Not a fit if
- Users unwilling to install uv plus a host CLI and cloud credentials
- Teams locked to one agent framework that won't adapt host-specific syntax
- Source review
- 51/100 · Major gaps
What does this agent do, and when should you use it?
evo is an open-source (Apache-2.0) autoresearch orchestrator that takes a codebase, automatically discovers metrics to optimize, sets up the evaluation, and runs a loop of experiments to improve the code. It extends Karpathy's autoresearch concept with tree search, parallel semi-autonomous subagents, shared state, gating, and observability. It is designed as a plugin for agentic frameworks including Claude Code, Codex, Cursor, Kimi, OpenClaw, Hermes, Opencode, and Pi. Experiments run locally in git worktrees or on remote backends like Modal, E2B, Daytona, AWS, Azure. evo provides a dashboard for monitoring experiments and can be installed and updated via the evo CLI. The project is hosted on GitHub at evo-hq/evo, with a DOI and citation info.
evo operates through two main commands: /evo:discover and /evo:optimize. The discover command identifies optimization goals, benchmark commands, and metric direction, either interactively or via seed input. It creates gates to protect against unintended changes and starts the dashboard. The optimize command runs the loop: the orchestrator launches parallel subagents, each in a separate workspace (git worktree), that read shared state (failure traces, annotations, discarded hypotheses), form hypotheses, edit, run benchmarks, and keep or discard changes based on scores. The orchestrator selects which branches to extend after each round using strategies like argmax, top_k, epsilon_greedy, softmax, or pareto_per_task. Cross-cutting scans inspired by RLM analyze traces and identify compound failure patterns. Gates act as pass/fail checks that discard experiments failing even if scores improve. The dashboard provides configuration and monitoring.
- A developer wanting to automatically optimize a codebase's performance before committing, without manually managing experiments.
- A team looking to explore multiple optimization directions without converging on a single greedy path.
- Researchers wanting to integrate code optimization with regression tests and safety checks to avoid breaking functionality.
- Engineering managers who need to monitor ongoing optimization experiments and tweak strategy parameters like argmax or softmax.
- Users who want to parallelize experiments across remote cloud resources like Modal or AWS without local GPU resources.
- Developers with an existing benchmark in the repo, wanting to see which changes actually improve scores.
How do you install or deploy this agent?
- Install the evo CLI:
uv tool install evo-hq-cli. 2. Install a host CLI if needed: e.g.,npm install -g @anthropic-ai/claude-codefor Claude Code, ornpm install -g @openai/codexfor Codex. 3. Install the plugin and host hooks:evo install <host>where <host> can be claude-code, codex, cursor, hermes, kimi, opencode, openclaw, or pi. 4. For remote backends, install with extras:uv tool install 'evo-hq-cli[modal]'or similar.
How do you use this agent?
After installation, run /evo:discover (or equivalent syntax) in your repo to discover benchmarks. You can seed the target, e.g., /evo:discover make the JSON parser at src/parser.py faster. Then run the optimization loop with /evo:optimize. A dashboard starts automatically and prints a URL (often http://127.0.0.1:8080). You can start it manually: uv run --project /path/to/evo/plugins/evo evo dashboard --port 8080. Update with evo update.
What are this agent's strengths and limitations?
- Automatically discovers benchmarks and creates gates to prevent correctness regressions, enhancing experiment safety.
- Explores more directions than greedy hill climbing due to tree search and parallel subagents.
- Supports multiple hosts (Claude Code, Codex, Cursor, etc.) and remote backends (Modal, E2B, AWS, Azure) offering flexibility.
- Provides a dashboard for real-time monitoring and strategy configuration.
- Installation requires uv and host CLI, plus network access for packages.
- Remote backends need extra cloud credentials and setup, increasing adoption cost.
- Experiments may be resource-intensive depending on benchmark, requiring appropriate compute.
- Dependence on specific agent framework hooks; syntax differences across hosts may require user adaptation.
How does this agent compare with similar options?
evo extends Karpathy's autoresearch, which is a simple greedy hill climb. evo adds tree search, parallel subagents, shared state, and gating. It is also inspired by GEPA and RLM papers for pareto strategy and cross-cutting scans.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| evo — Autoresearch Orchestrator for Codebases This agent | 51 · Major gaps | Agent plugin / skillFree + model costs | ★ 1.5k | 14d ago | Python | Codex · Claude Code |
| Weco Autoresearch | 63 · Some gaps | CLIFree + model costs | ★ 117 | 2d ago | Python | Codex · Claude Code · OpenAI API |
| Parallel Code | 53 · Major gaps | Desktop appFree + model costs | ★ 1.1k | today | TypeScript | Codex · Claude Code |
| Yardsort | 70 · Some gaps | Desktop appFree | ★ 11 | 8d ago | Rust | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README mentions telemetry (can be disabled), code review hook trust (--no-trust-hooks), gating mechanism to prevent unintended changes. But no detailed least-privilege description, user confirmation only mentioned as pausable, data flow transparency partially described, sensitive data handling not explicit, dependency security lacks specific versions or vulnerability scanning, external effects (e.g., remote sandboxes) not fully explained, rollback only via git worktree and revert, source attribution only via README and LICENSE. Deductions: lack of implementation details and evidence.
Evidence shows: CI workflows include unit tests, SDK tests, build and release processes, tests cover basic SDK functionality, but no full test results or coverage. Dependency availability lists multiple backends (Modal, E2B, etc.) but not verified. Failure messages: tests have error handling but no user-facing failure message examples. Deductions: tests not executed, dependency availability not verified, failure messages not fully demonstrated.
Evidence shows: README describes multiple usage scenarios (different hosts, remote backends), capability boundaries via gates and strategies, trigger precision via commands and natural language examples, environment fit via support for multiple OS and Python versions. But no detailed configuration options or limitations. Deductions: some descriptions are brief, lack specific configuration examples.
Evidence shows: README structure is clear, includes install, usage, upgrade, telemetry sections, install notes detailed, naming stable (evo commands), examples and FAQ section has examples but no FAQ, known limitations not explicitly listed, license Apache-2.0, versioning via CI and release process, maintenance responsibility not explicit. Deductions: missing known limitations and explicit maintenance responsibility.
Evidence shows: output usability via SDK and CLI, marginal value via tree search and parallel subagents, cost-benefit lacks specific data. Deductions: cost-benefit lacks quantitative evidence.
Evidence shows: README claims partially supported by tests and CI, but no independent verification sources, facts and inferences not clearly separated. Deductions: lack of cross-validation and clear separation.
- Publisher identity is unverified; treat as unknown and do not rely on brand trust.
- Static review cannot verify actual runtime behavior; all conclusions about functionality, security, and reliability are based on source code and documentation, with low confidence.
- Remote sandbox backends (e.g., Modal, E2B) involve external code execution; carefully review their permissions and data flow.
- Telemetry is enabled by default, though can be disabled; users should be aware of data collection scope.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
evo now runs on Kimi Code. From inside a Kimi session, point evo at a repo and it discovers what to optimize, builds the evaluation, and runs structured experiments in a loop, the same flow evo already supports on Claude Code, Codex, and Cursor. Install Kimi joins the host list: ``` uv tool install evo-hq-cli evo install kimi ``` …View on GitHub ↗ -
Release notes excerpt
evo now runs inside locked-down sandboxes, most notably the Claude Science kernel. Until now evo assumed it could create .git directories, write to your home folder, and bind a local port for the dashboard. Hardened sandboxes block all three, so evo couldn't start there. This release removes those assumptions. Run evo where .git is forbidden …View on GitHub ↗
FAQ
Does evo support using my existing benchmarks?
discover detects it and gates are opt-in. If not, discover helps create one and automatically attaches a held-out-slice score-floor gate.Can I limit the parallelism of experiments?
What telemetry does evo collect?
evo telemetry off, or per command with EVO_TELEMETRY=0.