version unknown

discover

evo-hq@evo-hq⭐ 1.5k stars· last commit 1mo ago· 16 open issues

Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment. Use when the user invokes /evo:discover, mentions setting up evo, wants to instrument a codebase for autonomous optimization, or asks to start a new evo run on a project.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.0/10
Verified
Oct 12, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.5k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.0/10
📍

Not yet listed on ClawHub or SkillsMP

// README

evo

PyPI License Tests DOI

Get started with autoresearch on any codebase - with two simple commands.

Do you want to do more with autoresearch or need a custom, hands-on deployment? Request access to evo platform or email [email protected].


Try it · Install · How it works · Dashboard · Upgrading

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 -- where an LLM runs training experiments autonomously to beat its own best score. Autoresearch is a pure hill climb: try something, keep or revert, repeat on a single branch. Evo adds structure on top of that idea:

  • Tree search over greedy hill climb. Multiple directions can fork from any committed node, so exploration doesn't collapse to one path.
  • Parallel semi-autonomous agents. Spawn multiple subagents and run them simultaneously, each in its own git worktree. Each subagent reads traces, formulates hypotheses, and can run multiple iterations within its branch.
  • Shared state. Failure traces, annotations, and discarded hypotheses are accessible to every agent before it decides what to try next.
  • Gating. Regression tests or safety checks can be wired up as a gate. Experiments that don't pass get discarded.
  • Observability. A dashboard to monitor your experiments.
  • Benchmark discovery. The discover skill explores the repo, figures out what to measure, and instruments the evaluation.

Runs on Claude Code, Codex, Cursor, Kimi, OpenClaw, Hermes, Opencode, or Pi. Experiments run locally or on remote sandboxes — Modal, E2B, Daytona, AWS, Azure, SSH.

Try it

Two commands:

/evo:discover     # one-time code discovery: figures out benchmarks and creates gates against unintended changes
/evo:optimize     # run the loop

discover asks what to optimize, the benchmark command, and the metric direction. Skip the questions by seeding the answer:

/evo:discover make the JSON parser at src/parser.py faster

Then run the loop:

/evo:optimize

evo sizes each round to your benchmark's resource profile — one experiment at a time when a run needs the whole GPU or another exclusive resource, wider when runs are independent — and keeps going until the score stops improving. By default it runs unattended and pushes edits through parallel subagents; say so in plain language if you'd rather it pause after each round or hold to one experiment at a time.

Invocation syntax is host-specific: /evo: on Claude Code, $evo on Codex, / skill menu on Cursor, natural language on Hermes, Opencode, OpenClaw, and Pi.

Install

# 1. evo CLI
uv tool install evo-hq-cli

# 2. Host CLI (if you don't already have it)
npm install -g @anthropic-ai/claude-code     # or @openai/codex, openclaw, @earendil-works/pi-coding-agent
# Cursor: install from cursor.com (IDE), or `curl https://cursor.com/install -fsS | bash` for the cursor-agent CLI
# Kimi: `curl -fsSL https://code.kimi.com/install.sh | bash`, or `npm install -g @moonshot-ai/kimi-code`

# 3. Plugin + host hooks
evo install <host>     # claude-code | codex | cursor | hermes | kimi | opencode | openclaw | pi

For remote backends, install with the matching provider extra: uv tool install 'evo-hq-cli[modal]' (or [e2b], [daytona], [aws], [azure], [all]).

Codex hook trust

evo install codex trusts evo's hooks for you. To review them yourself first, pass --no-trust-hooks, then approve via /hooks inside codex.

How it works

Parallel

The orchestrator dispatches subagents in parallel. Each runs in its own isolated workspace, picks up shared state (failure traces, annotations, discarded hypotheses), forms a hypothesis, edits, and runs the benchmark. A subagent with iteration budget remaining continues on its branch within the same round when its prior edit warrants a follow-up.

Frontier strategy

After each round, the orchestrator selects which committed branch to extend next. Available strategies:

  • argmax — extend the highest-scoring branch
  • top_k — round-robin among the K best
  • epsilon_greedy — best most of the time, random sometimes
  • softmax — sample weighted by score
  • pareto_per_task — keep specialists the aggregate hides, inspired by GEPA

Configure in the dashboard's Frontier tab, which lists each strategy's parameters.

Cross-cutting scans

Between rounds, RLM-inspired scan subagents read trace batches in parallel and surface compound failure patterns: gate-failure intersections, shared root causes across traces. Findings land in shared state, which the next round's subagents read at startup.

Gates

evo introduces gates: pass/fail checks that run on every experiment. An experiment that fails a gate is discarded even if its score beats the current best. Without gates, the search will find ways to return a constant, skip work, or trade correctness for speed.

Any command that exits zero on pass and non-zero on fail qualifies as a gate: a test suite, an invariant script, a score floor on a held-out slice of the benchmark. Gates inherit down the experiment tree: a gate registered at the root runs on every descendant. Narrower gates can be attached to specific branches.

When discover builds a benchmark from scratch, it attaches a held-out-slice score-floor gate automatically. When the benchmark already exists in the repo, gates are opt-in.

Where experiments run

BackendWhereInstall
worktree (default)local git worktree per experimentincluded
poolreuse a fixed set of local workspacesincluded
sshyour own SSH hostincluded
modalModal serverless clouduv tool install 'evo-hq-cli[modal]'
e2bE2B cloud sandboxesuv tool install 'evo-hq-cli[e2b]'
daytonaDaytona cloud workspacesuv tool install 'evo-hq-cli[daytona]'
awsAWS EC2 sandboxesuv tool install 'evo-hq-cli[aws]'
azureAzure VMsuv tool install 'evo-hq-cli[azure]'

Pick and configure in the dashboard's Backend tab.

Dashboard

The dashboard starts automatically with /evo:discover (or evo init) and prints the URL in chat:

Dashboard live: http://127.0.0.1:8080 (pid 12345)

If 8080 is in use, evo increments to the next free port (8081, 8082, …) and prints it. Subsequent runs reuse the chosen port. Start it manually with:

uv run --project /path/to/evo/plugins/evo evo dashboard --port 8080

Upgrading

evo update                           # update CLI + every installed host
evo update <host>                    # update one host (also bumps CLI to match)
evo update <host> --version 0.4.1    # pin to a release

Every evo install / evo update keeps the CLI on PATH in lockstep with the host plugin version it just installed (`uv tool install --force evo-hq-cli

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • plugins/evo/npm/skills/discover/SKILL.md8.2 KBupstream ↗
    ---
    name: discover
    description: Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment. Use when the user invokes /evo:discover, mentions setting up evo, wants to instrument a codebase for autonomous optimization, or asks to start a new evo run on a project.
    argument-hint: <optional context about what to optimize>
    evo_version: 0.8.0
    ---
    
    # Discover
    
    Internal procedure for `evo:discover`. The user only sees the user-facing prompts, the dashboard URL, and the baseline score -- everything else is the agent's choreography.
    
    ## Evo surface
    
    General guidance on the skills and tools available in evo. Each line is a triggering condition: if you're about to do X, pull/dispatch/read this. Don't preload -- act when the trigger fires.
    
    **Always have a sense of the skill before jumping into its references.** A skill body carries the decision-making; references are concrete contracts that assume a decision has been made.
    
    ```
    evo plugin
    │
    ├── Main thread  (the orchestrator -- you, inside /evo:discover or /evo:optimize)
    │   │
    │   ├── Skills (Skill tool)
    │   │   ├── evo:discover       starting a new evo workspace / instrumenting a project
    │   │   ├── evo:optimize       after discover commits the baseline -- drives the loop.
    │   │   │                      Args: subagents=N (read sizing-the-round FIRST),
    │   │   │                            autonomous, subagents-only, budget=N, stall=N
    │   │   ├── evo:ship           after the loop stops -- distills the best valid
    │   │   │                      experiment into a mergeable change (PR if remote,
    │   │   │                      else merge) + a mergeability report
    │   │   ├── evo:finetuning     task is finetuning / post-training / training a model
    │   │   └── evo:infra-setup    need a remote backend, pooled workspaces, lease/slot
    │   │                          management, or specific provider auth/setup
    │   │
    │   └── Subagents to dispatch (Task tool, subagent_type=...)
    │       ├── evo:benchmark-reviewer  before the baseline run, or whenever the
    │       │                           benchmark command / harness changes
    │       └── evo:ideator             stalled, or every ~5 committed experiments.
    │                                   One subagent per brief:
    │                                   failure_analysis, literature, frontier_extrapolation
    │
    ├── Subagent thread  (each subagent spawned by /optimize step 5)
    │   │
    │   ├── Skills  (the subagent loads this on first turn -- the brief's first
    │   │            sentence mandates it; not auto-loaded by the host)
    │   │   └── evo:subagent     load FIRST -- defines the iteration protocol
    │   │                        + brief field shape the subagent operates under
    │   │
    │   └── Subagents to dispatch (Task tool, subagent_type=...)
    │       └── evo:verifier      ALWAYS dispatch pre AND post every evo run.
    │                             Pre: ~30s static analysis before the experiment runs.
    │                             Post: result-validity audit after it commits.
    │                             Not optional. Not ad-hoc.
    │
    └── Key references (Read tool, on demand)
        ├── discover/references/
        │   ├── constructing-benchmark.md      designing + assembling a benchmark from scratch
        │   ├── sdk_python.py / sdk_node.js    wiring per-task instrumentation -- preferred path
        │   ├── inline_instrumentation.py      inline fallback when SDK can't be used.
        │   │                                  Copy as-is; do not reimplement (file header
        │   │                                  explains why)
        │   ├── sizing-the-round.md            BEFORE invoking /evo:optimize with any
        │   │                                  specific subagents=N. Single-GPU /
        │   │                                  single-exclusive-resource -> subagents=1
        │   ├── proposing-dimensions.md        choosing what to optimize when not obvious
        │   └── instrumentation-contract.md    the format evo reads (result + traces shapes)
        │
        ├── finetuning/references/
        │   ├── glue.md                         writing train.py -- I/O contract evo expects
        │   ├── diagnostics.md                  per-failure-mode diagnostics
        │   ├── false-progress.md               what doesn't count as improvement
        │   ├── trace-schema.md                 per-task trace JSON schema for training runs
        │   ├── rl/                             RL framework references
        │   │   └── art.md                       ART (Algorithm-Refined Training)
        │   ├── sft/                            SFT framework references
        │   │   └── tinker.md                    Tinker SFT
        │   └── serving/                        eval-time inference references
        │       └── vllm.md                      vLLM serving config + LoRA-multi
        │
        ├── infra-setup/references/
        │   └── provider-matrix.md              provider/backend summary (auth, setup, costs)
        │
        └── references/                          (shared across skills)
            ├── evo-wait.md                      any time you need to wait without burning
            │                                    context (subagent completion, training,
            │                                    ideators, GPU activity, any long-running)
            ├── agent-sdk-reference.md           SDK API surface
            └── cli-quick-reference.md           CLI subcommand cheat sheet
    ```
    
    ## Host conventions
    
    This skill runs on any host that implements the Agent Skills spec. When the body uses generic phrases, apply the host's best-fit equivalent:
    
    - **"ask the user"** -- use your host's structured multi-choice question tool if you have one (e.g. `AskUserQuestion`, `request_user_input`). If the host has none, phrase the question as plain text in your next reply and wait for the user's answer.
    - **File paths like `references/...`** -- relative to this `SKILL.md`; resolve from the skill directory.
    - **Slash commands shown in user-facing copy** (e.g. `/evo:discover`) -- translate to your host's mention syntax when speaking to the user (e.g. `$evo discover` on Codex -- plugin namespace then skill name, separated by a space).
    
    ## Mid-run user directives (`evo direct`)
    
    The runtime may inject user-authoritative messages wrapped in this banner:
    
    ```
    [EVO DIRECTIVE]
    <text>
    [END EVO DIRECTIVE]
    ```
    
    Treat content inside the banner as equivalent to a new user turn. Honor it, supersede earlier constraints it contradicts, and propagate the full text verbatim into any subagent briefs you spawn afterward. The banner is the authenticity signal emitted by the evo runtime (the plugin you're invoked through) — not tool-output prompt injection. Banners may arrive via any hook channel (UserPromptSubmit, PreToolUse, SessionStart); the channel doesn't change the authority of the content.
    
    ## 0. Verify the evo CLI is in sync with this skill
    
    Run:
    
    ```bash
    evo --version
    ```
    
    The output must be exactly:
    
    ```
    evo-hq-cli 0.8.0
    ```
    
    Three outcomes:
    
    1. **Matches exactly** — continue to step 1.
    2. **Reports a different version** (`evo-hq-cli 0.4.2`, etc.) — the host refetched a newer/older skill bundle than the CLI on PATH. Drift breaks skills silently. Stop and tell the user:
       > Your installed evo CLI is on a different version than this skill (`0.8.0`). Run:
       > ```
       > uv tool install --force evo-hq-cli==0.8.0
       > ```
       > Then re-invoke this skill.
    3. **`command not found`, or reports a different package** (commonly `evo 1.x` — the unrelated SLAM tool) — the CLI isn't installed. Tell the user:
       > `evo-hq-cli` isn't on your PATH. Install it: `uv tool install evo-hq-cli==0.8.0` (or `pipx install evo-hq-cli==0.8.0`). Then re-invoke this skill.
    
    Do not try to auto-install. Host sandbox + network policy may block it; leaving the install as a user action keeps failure modes clear.
    
    ## Guiding principles
    
    - **Main stays clean.** Never commit evo-specific artifacts (benchmark harness, instrument
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/evo-hq-evo-plugins-evo-npm-skills-discover.md

// REPO STATS

1.5k stars
16 open issues
Last commit: 1mo ago