HivemindOS manual

Evo Optimization Runtime

Evo (Apache-2.0) is an experimental, benchmark-driven optimization tool. Parallel agents try improvements in separate copies of a repository, keep what scores better, and must pass safety checks you set. HivemindOS runs Evo as a background runtime and shows its progress.

Install

uv tool install evo-hq-cli       # installs `evo`, `evo-dashboard`, `evo-drain`
evo install <host>               # register the evo plugin with an orchestrator host
evo doctor <host>                # verify

The host is the agent framework that drives the loop: Hermes, OpenClaw, Claude Code, Codex, OpenCode, or Pi. evo install claude-code changes Claude Code’s own settings, so run it yourself where you want the /evo: commands; do not ask an agent to do it for you.

Once installed, HivemindOS detects Evo, shows each workspace’s target, best score, and experiment tree as runtime runs, and links to Evo’s web dashboard when it is running. Scheduled jobs and skills can run evo commands such as evo status and evo dispatch.

Set up a workspace

In any git repository with something measurable to improve:

evo init --name "<project>" \
  --target "<what to optimize and what must not regress>" \
  --benchmark "<command that measures it deterministically>" \
  --metric min|max --host <host> --per-exp-timeout <seconds>

Pick a benchmark that runs in seconds and prints a stable number. Add checks so experiments cannot cheat or make things worse. Checks added to root apply to every experiment, and --phase pre checks run before any benchmark cost:

evo gate add root --name benchmark-untouched --phase pre \
  --command "git diff --quiet HEAD -- <benchmark script>"

Add .evo/ to the repository’s .gitignore. Follow progress with evo status, evo tree, evo report --watch, or the web dashboard.

The loop runs from the host and spends agent tokens. Start it on purpose.

Evo and skill autoresearch

You do not need Evo for HivemindOS’s built-in skill autoresearch. When a skill keeps failing, HivemindOS creates a review proposal and uses its own Work Board optimizer by default.

It uses Evo only when Evo is installed, the skill lives in a git repository, and a benchmark command exists. If that repository has no .evo/ folder yet, the approved task may create one. Nothing runs until you approve the review, and an installed skill is never replaced automatically.

Run experiments on other machines

Evo can run experiments on remote SSH hosts (Evo dashboard → Backend tab), as well as locally or in cloud sandboxes (Modal, E2B, Daytona, AWS, Azure). Your fleet machines reachable over Tailscale SSH work as ready-made workers. Use their tailnet machine names, never raw IP addresses, and keep them private to your tailnet.