How evo-hq/evo works
1. Overall shape
- This is a mono-repo for a Python-based orchestration tool plus host-specific plugin packaging.
- The main source of truth is plugins/evo, which contains the CLI, orchestration logic, hook handling, dashboard server, backend abstractions, and packaging assets.
2. Control plane: the evo CLI
- plugins/evo/src/evo/cli.py is the user entrypoint.
- It drives install/update flows, starts the dashboard, launches optimization loops, and coordinates discovery/benchmark setup.
- The core orchestration logic lives around core.py, dispatch.py, frontier_strategies.py, report.py, and workspace_executor.py.
3. Search / optimization model
- evo is organized around an experiment tree, not a single linear loop.
- Each experiment gets a workspace, a benchmark run, optional gates, and a score.
- The orchestrator keeps or discards branches based on benchmark outcomes, then chooses the next frontier using strategies like argmax, top-k, epsilon-greedy, softmax, or pareto-per-task.
4. Execution backends
- Backend abstractions are in src/evo/backends.
- worktree is the default local mode: each experiment runs in its own git worktree.
- pool reuses a fixed set of local workspaces.
- remote and remote_state cover non-local execution and state tracking.
- protocol.py and state_keys.py define the shared backend interface and persistence keys.
5. Infrastructure / sandbox providers
- Remote execution is implemented through provider adapters in src/evo/backends/sandbox_providers.
- Supported environments include Modal, E2B, Daytona, AWS, Azure, SSH, and manual setups.
- These providers are the boundary between evo’s orchestration layer and the actual compute environment where experiments run.
6. Host integration layer
- src/evo/host_install and src/evo/hosts adapt evo to different agent runtimes.
- The repo explicitly supports Claude Code, Codex, Cursor, Hermes, OpenClaw, Opencode, and Pi.
- Host-specific plugin packaging lives under plugins/evo/src/evo/openclaw_plugin, opencode_plugin, and the .claude-plugin / .codex-plugin metadata directories.
7. Hooking and event ingestion
- The inject package is the event pipeline for host-generated activity.
- queue.py, registry.py, marker.py, paths.py, and drain.py manage capture, buffering, and replay of hook events.
- hooks/hooks.json and hooks/wait_hint.sh define the host-facing hook behavior.
- The Rust helper in bin/evo-hook-drain-rs exists to reliably drain hook output when shell/Python plumbing is not enough.
8. Shared state and cross-run memory
- evo keeps failure traces, annotations, discarded hypotheses, and gate results in shared state so later agents can reuse them.
- dashboard_supervisor.py, pool_state.py, remote_state.py, and the injection registry are part of that shared-memory boundary.
- This is important architecturally: subagents are not isolated silos; they read prior evidence before deciding what to try next.
9. Dashboard / observability
- dashboard.py serves a local web UI backed by static assets in src/evo/static.
- The dashboard is a control surface for backend choice, frontier strategy, and experiment monitoring.
- It is not just a viewer; it reflects orchestration state and influences execution policy.
10. Skills and agent prompts
- The skills/ tree is the content layer used by the host plugins.
- Skills like discover, optimize, report, ship, subagent, and infra-setup encode workflow-specific instructions and reference material.
- The agents/ markdown files define specialized roles such as ideator, verifier, and benchmark reviewer.
11. SDKs and external integration
- sdk/python and sdk/node expose smaller programmatic surfaces for embedding evo behavior outside the CLI.
- These SDKs mirror the run/backend/gate concepts so external code can invoke evo-compatible flows without using the full plugin stack.
12. Build, packaging, and release flow
- JS bundles are built for host plugins and extensions via scripts like build-js-bundles.sh and sync scripts in plugins/evo/npm.
- CI and publish workflows in .github/workflows handle validation and release.
- The tests are broad and architecture-revealing: unit tests cover gates, injection, hosting, dashboards, and versioning; e2e/live tests exercise real sandboxes and host integrations.
13. What to draw in an architecture diagram
- The main flow is: host agent runtime → evo hook/plugin layer → injection/shared state → orchestrator/frontier selection → backend workspace/sandbox → benchmark and gates → report/dashboard → next round.
- The key boundaries are between host integration, orchestration logic, execution backends, and observability/state.
Main entry points: core.py Core · workspace_executor.py Workspace exec · host_install Host install · remote.py Remote
Components 23
Host integration
Plugin packaging and adapters for different agent runtimes.
- Host install · Installs evo into Claude Code, Codex, Cursor, Hermes, OpenClaw, Opencode, and Pi runtimes.
plugins/evo/src/evo/host_install - Hosts · Host-specific runtime abstractions and variants.
plugins/evo/src/evo/hosts - OpenClaw plugin · Host plugin packaging and generated bundle for OpenClaw/Pi integration.
plugins/evo/src/evo/openclaw_plugin - Opencode plugin · Host plugin packaging and generated bundle for Opencode integration.
plugins/evo/src/evo/opencode_plugin
Orchestration core
CLI, experiment control, frontier selection, reporting, and execution coordination.
- CLI · User-facing command entrypoint that drives install, update, optimize, and dashboard flows.
plugins/evo/src/evo/cli.py - Core · Experiment lifecycle and top-level coordination logic.
plugins/evo/src/evo/core.py - Dispatch · Routes work across runs, tasks, and execution modes.
plugins/evo/src/evo/dispatch.py - Frontier · Chooses the next experiment branch using argmax, top-k, epsilon-greedy, softmax, or pareto strategies.
plugins/evo/src/evo/frontier_strategies.py - Workspace exec · Runs benchmarked experiments in workspaces and gathers outcomes.
plugins/evo/src/evo/workspace_executor.py - Report · Formats experiment outcomes, scores, and summaries for humans and the dashboard.
plugins/evo/src/evo/report.py
Execution backends
Local and remote workspace execution plus sandbox providers.
- Worktree · Default local backend using a git worktree per experiment.
plugins/evo/src/evo/backends/worktree.py - Pool · Reuses a fixed pool of local workspaces.
plugins/evo/src/evo/backends/pool.py - Remote · Remote execution backend with non-local workspace management.
plugins/evo/src/evo/backends/remote.py - Providers · Modal, E2B, Daytona, AWS, Azure, SSH, and manual sandbox adapters.
plugins/evo/src/evo/backends/sandbox_providers - Protocol · Shared backend interface used by execution modes.
plugins/evo/src/evo/backends/protocol.py
Event and state
Hook ingestion, shared memory, and cross-run persistence.
- Inject · Captures, buffers, and drains host hook events.
plugins/evo/src/evo/inject - Registry · Tracks sessions, markers, and replayable event metadata across runs.
plugins/evo/src/evo/inject/registry.py - Remote state · Persists remote execution state and run metadata.
plugins/evo/src/evo/backends/remote_state.py - Pool state · Stores fixed-pool backend state and workspace allocation data.
plugins/evo/src/evo/backends/pool_state.py
Dashboard
Local observability and control surface.
- Dashboard · Local control and observability surface for orchestration state.
plugins/evo/src/evo/dashboard.py - Supervisor · Bridges orchestration state into the dashboard and shared memory view.
plugins/evo/src/evo/dashboard_supervisor.py
SDKs
Programmatic entrypoints for embedding evo behavior.
- Python SDK · Programmatic run/backend/gate API for Python consumers.
sdk/python/src/evo_agent - Node SDK · Programmatic run/backend/gate API for Node consumers.
sdk/node/src
Connections 24
- CLI → Core: drives · CLI starts and configures experiment orchestration.
- CLI → Dashboard: serves · CLI can launch or connect the dashboard.
- Core → Dispatch: coordinates · Core delegates task routing and lifecycle steps.
- Core → Frontier: selects next · Core asks frontier strategies for the next branch.
- Core → Workspace exec: executes in · Core hands experiments to the workspace executor.
- Workspace exec → Protocol: uses · Execution is mediated by the backend contract.
- Workspace exec → Worktree: default · Local experiments run in isolated git worktrees.
- Workspace exec → Pool: alternate · Some runs reuse a fixed local workspace pool.
- Workspace exec → Remote: remote · Workspace execution can be offloaded remotely.
- Remote → Providers: delegates to · Remote backend is implemented through sandbox providers.
- Remote → Remote state: persists · Remote execution updates persistent remote state.
- Pool → Pool state: persists · Pool backend tracks workspace allocation state.
- Inject → Registry: records · Hook ingestion populates shared run metadata.
- Inject → Core: feeds · Captured events inform orchestration decisions.
- Supervisor → Dashboard: backs · Supervisor bridges shared state into the UI.
- Supervisor → Registry: reads · Dashboard state is informed by the injection registry.
- Dashboard → Report: shows · Dashboard presents scores, outcomes, and summaries.
- Report → Core: summarizes · Reports are derived from orchestration results.
- Host install → Hosts: adapts · Host installers tailor evo to different agent runtimes.
- Host install → Inject: installs hooks · Host installation wires in event capture plumbing.
- Host install → OpenClaw plugin: packages · Host install includes OpenClaw/Pi plugin assets.
- Host install → Opencode plugin: packages · Host install includes Opencode plugin assets.
- Python SDK → Core: embeds · Python SDK exposes smaller evo-compatible flows.
- Node SDK → Core: embeds · Node SDK exposes smaller evo-compatible flows.