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.
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.
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.
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 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.
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.
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.