# evo-hq/evo architecture

> Architecture diagram of the GitHub repository evo-hq/evo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evo-hq/evo
- Repository: https://github.com/evo-hq/evo

## Overview

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: [`plugins/evo/src/evo/core.py`](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/core.py) (Core), [`plugins/evo/src/evo/workspace_executor.py`](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/workspace_executor.py) (Workspace exec), [`plugins/evo/src/evo/host_install`](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/host_install) (Host install), [`plugins/evo/src/evo/backends/remote.py`](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/remote.py) (Remote)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_host["Host integration"]
  node_host_install["Host install<br/>host adapters"]
  node_hosts["Hosts<br/>runtime adapters"]
  node_openclaw_plugin["OpenClaw plugin<br/>plugin bundle"]
  node_opencode_plugin["Opencode plugin<br/>plugin bundle"]
end

subgraph group_group_core["Orchestration core"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_core["Core<br/>orchestrator<br/>[core.py]"]
  node_dispatch["Dispatch<br/>coordination<br/>[dispatch.py]"]
  node_frontier["Frontier<br/>selection"]
  node_workspace["Workspace exec<br/>executor"]
  node_report["Report<br/>results<br/>[report.py]"]
end

subgraph group_group_exec["Execution backends"]
  node_worktree["Worktree<br/>local backend<br/>[worktree.py]"]
  node_pool["Pool<br/>local backend<br/>[pool.py]"]
  node_remote["Remote<br/>distributed backend<br/>[remote.py]"]
  node_providers["Providers<br/>sandbox adapters"]
  node_protocol["Protocol<br/>backend contract<br/>[protocol.py]"]
end

subgraph group_group_state["Event and state"]
  node_inject["Inject<br/>event pipeline"]
  node_registry[("Registry<br/>shared state<br/>[registry.py]")]
  node_remote_state[("Remote state<br/>persistence<br/>[remote_state.py]")]
  node_pool_state[("Pool state<br/>persistence<br/>[pool_state.py]")]
end

subgraph group_group_ui["Dashboard"]
  node_dashboard["Dashboard<br/>web ui<br/>[dashboard.py]"]
  node_supervisor["Supervisor<br/>state bridge"]
end

subgraph group_group_sdk["SDKs"]
  node_sdk_python["Python SDK"]
  node_sdk_node["Node SDK"]
end

node_cli -->|"drives"| node_core
node_cli -->|"serves"| node_dashboard
node_core -->|"coordinates"| node_dispatch
node_core -->|"selects next"| node_frontier
node_core -->|"executes in"| node_workspace
node_workspace -->|"uses"| node_protocol
node_workspace -->|"default"| node_worktree
node_workspace -->|"alternate"| node_pool
node_workspace -->|"remote"| node_remote
node_remote -->|"delegates to"| node_providers
node_remote -->|"persists"| node_remote_state
node_pool -->|"persists"| node_pool_state
node_inject -->|"records"| node_registry
node_inject -->|"feeds"| node_core
node_supervisor -->|"backs"| node_dashboard
node_supervisor -->|"reads"| node_registry
node_dashboard -->|"shows"| node_report
node_report -->|"summarizes"| node_core
node_host_install -->|"adapts"| node_hosts
node_host_install -->|"installs hooks"| node_inject
node_host_install -->|"packages"| node_openclaw_plugin
node_host_install -->|"packages"| node_opencode_plugin
node_sdk_python -->|"embeds"| node_core
node_sdk_node -->|"embeds"| node_core

click node_cli "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/cli.py"
click node_core "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/core.py"
click node_dispatch "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dispatch.py"
click node_frontier "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/frontier_strategies.py"
click node_workspace "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/workspace_executor.py"
click node_report "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/report.py"
click node_worktree "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/worktree.py"
click node_pool "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/pool.py"
click node_remote "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/remote.py"
click node_providers "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/backends/sandbox_providers"
click node_protocol "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/protocol.py"
click node_inject "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/inject"
click node_registry "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/inject/registry.py"
click node_remote_state "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/remote_state.py"
click node_pool_state "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/pool_state.py"
click node_dashboard "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dashboard.py"
click node_supervisor "https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dashboard_supervisor.py"
click node_host_install "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/host_install"
click node_hosts "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/hosts"
click node_openclaw_plugin "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/openclaw_plugin"
click node_opencode_plugin "https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/opencode_plugin"
click node_sdk_python "https://github.com/evo-hq/evo/tree/main/sdk/python/src/evo_agent"
click node_sdk_node "https://github.com/evo-hq/evo/tree/main/sdk/node/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_install,node_hosts,node_openclaw_plugin,node_opencode_plugin toneBlue
class node_cli,node_core,node_dispatch,node_frontier,node_workspace,node_report toneAmber
class node_worktree,node_pool,node_remote,node_providers,node_protocol toneMint
class node_inject,node_registry,node_remote_state,node_pool_state toneRose
class node_dashboard,node_supervisor toneIndigo
class node_sdk_python,node_sdk_node toneTeal
```

## Components

### Host integration

Plugin packaging and adapters for different agent runtimes.

- [Host install](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/host_install): host adapters · Installs evo into Claude Code, Codex, Cursor, Hermes, OpenClaw, Opencode, and Pi runtimes. · `plugins/evo/src/evo/host_install`
- [Hosts](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/hosts): runtime adapters · Host-specific runtime abstractions and variants. · `plugins/evo/src/evo/hosts`
- [OpenClaw plugin](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/openclaw_plugin): plugin bundle · Host plugin packaging and generated bundle for OpenClaw/Pi integration. · `plugins/evo/src/evo/openclaw_plugin`
- [Opencode plugin](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/opencode_plugin): plugin bundle · 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](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/cli.py): entrypoint · User-facing command entrypoint that drives install, update, optimize, and dashboard flows. · `plugins/evo/src/evo/cli.py`
- [Core](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/core.py): orchestrator · Experiment lifecycle and top-level coordination logic. · `plugins/evo/src/evo/core.py`
- [Dispatch](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dispatch.py): coordination · Routes work across runs, tasks, and execution modes. · `plugins/evo/src/evo/dispatch.py`
- [Frontier](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/frontier_strategies.py): selection · Chooses the next experiment branch using argmax, top-k, epsilon-greedy, softmax, or pareto strategies. · `plugins/evo/src/evo/frontier_strategies.py`
- [Workspace exec](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/workspace_executor.py): executor · Runs benchmarked experiments in workspaces and gathers outcomes. · `plugins/evo/src/evo/workspace_executor.py`
- [Report](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/report.py): results · 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](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/worktree.py): local backend · Default local backend using a git worktree per experiment. · `plugins/evo/src/evo/backends/worktree.py`
- [Pool](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/pool.py): local backend · Reuses a fixed pool of local workspaces. · `plugins/evo/src/evo/backends/pool.py`
- [Remote](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/remote.py): distributed backend · Remote execution backend with non-local workspace management. · `plugins/evo/src/evo/backends/remote.py`
- [Providers](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/backends/sandbox_providers): sandbox adapters · Modal, E2B, Daytona, AWS, Azure, SSH, and manual sandbox adapters. · `plugins/evo/src/evo/backends/sandbox_providers`
- [Protocol](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/protocol.py): backend contract · 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](https://github.com/evo-hq/evo/tree/main/plugins/evo/src/evo/inject): event pipeline · Captures, buffers, and drains host hook events. · `plugins/evo/src/evo/inject`
- [Registry](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/inject/registry.py): shared state · Tracks sessions, markers, and replayable event metadata across runs. · `plugins/evo/src/evo/inject/registry.py`
- [Remote state](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/remote_state.py): persistence · Persists remote execution state and run metadata. · `plugins/evo/src/evo/backends/remote_state.py`
- [Pool state](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/backends/pool_state.py): persistence · Stores fixed-pool backend state and workspace allocation data. · `plugins/evo/src/evo/backends/pool_state.py`

### Dashboard

Local observability and control surface.

- [Dashboard](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dashboard.py): web ui · Local control and observability surface for orchestration state. · `plugins/evo/src/evo/dashboard.py`
- [Supervisor](https://github.com/evo-hq/evo/blob/main/plugins/evo/src/evo/dashboard_supervisor.py): state bridge · 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](https://github.com/evo-hq/evo/tree/main/sdk/python/src/evo_agent): library · Programmatic run/backend/gate API for Python consumers. · `sdk/python/src/evo_agent`
- [Node SDK](https://github.com/evo-hq/evo/tree/main/sdk/node/src): library · Programmatic run/backend/gate API for Node consumers. · `sdk/node/src`

## Connections

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