# covibes/zeroshot architecture

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

- Interactive diagram: https://gitdiagram.com/covibes/zeroshot
- Repository: https://github.com/covibes/zeroshot

## Overview

Zeroshot is a native software-engineering agent that executes authored workflow graphs: a goal is admitted, graph transitions dispatch workers, independent reviews can trigger bounded repair, and accepted work can proceed through delivery. Runs are observable and durable, with local, self-hosted, and cloud target options; the browser UI edits profiles and inspects runs. The README documents the principal workflow and target capabilities; sampled Rust excerpts clarify admission, supervision, execution, and persistence, but do not expose every target or delivery implementation detail.

Main entry points: [`zeroshot/src/native_v2_supervisor.rs`](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_supervisor.rs) (Run supervisor), [`zeroshot/src/main.rs`](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/main.rs) (Native CLI), [`zeroshot/src/native_v2_admission.rs`](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_admission.rs) (Run admission), [`zeroshot/src/native_v2_portable_controller/controller.rs`](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_portable_controller/controller.rs) (Portable controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and clients"]
  node_cli["Native CLI<br/>[main.rs]"]
  node_ui["Workspace UI<br/>[App.tsx]"]
  node_sdk["Python client<br/>[client.py]"]
end

subgraph group_orchestration["Run orchestration"]
  node_graph["Authored graph<br/>[full_v1_reducer.rs]"]
  node_admission["Run admission"]
  node_verifier["Graph verifier<br/>[graph_verifier.rs]"]
  node_supervisor["Run supervisor"]
  node_controller["Portable controller<br/>[controller.rs]"]
  node_ledger[("Run ledger")]
end

subgraph group_execution["Worker execution and delivery"]
  node_runner["Node runner"]
  node_process["Provider processes<br/>[process.rs]"]
  node_delivery["Git delivery"]
end

subgraph group_targets["Targets and protocols"]
  node_local["Local target"]
  node_cloud["Cloud target<br/>[native_v2_cloud.rs]"]
  node_cluster["Cluster protocol<br/>[lib.rs]"]
  node_cluster_client["Cluster client<br/>[lib.rs]"]
  node_cluster_server["Cluster server<br/>[connection.rs]"]
end

node_user(("Engineer"))
node_github(("GitHub"))

node_user -->|"submits goal"| node_cli
node_user -->|"edits profiles"| node_ui
node_user -->|"submits runs"| node_sdk
node_cli -.->|"starts run"| node_admission
node_ui -.->|"uses profiles"| node_cli
node_admission -->|"validates graph"| node_verifier
node_admission -->|"admits graph"| node_graph
node_controller -->|"admits submission"| node_admission
node_controller -.->|"starts supervision"| node_supervisor
node_supervisor -->|"reduces history"| node_graph
node_supervisor -->|"reads and appends"| node_ledger
node_supervisor -->|"dispatches nodes"| node_runner
node_runner -.->|"runs providers"| node_process
node_supervisor -->|"dispatches delivery"| node_delivery
node_local -.->|"hosts runs"| node_controller
node_cloud -->|"hosts runs"| node_controller
node_cloud -->|"stores run state"| node_ledger
node_delivery -->|"delivers changes"| node_github
node_cli -.->|"connects to target"| node_cluster_client
node_cluster_client -.->|"exchanges messages"| node_cluster
node_cluster_server -.->|"handles messages"| node_cluster

click node_cli "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/main.rs"
click node_ui "https://github.com/covibes/zeroshot/blob/main/ui/src/App.tsx"
click node_sdk "https://github.com/covibes/zeroshot/blob/main/sdks/python/src/zeroshot/client.py"
click node_graph "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/full_v1_reducer.rs"
click node_admission "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_admission.rs"
click node_verifier "https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-server/src/graph_verifier.rs"
click node_supervisor "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_supervisor.rs"
click node_controller "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_portable_controller/controller.rs"
click node_ledger "https://github.com/covibes/zeroshot/tree/main/zeroshot/src/v2_run_ledger"
click node_runner "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_runner.rs"
click node_process "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/execution/process.rs"
click node_delivery "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_delivery.rs"
click node_local "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_portable_controller.rs"
click node_cloud "https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_cloud.rs"
click node_cluster "https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-protocol/src/lib.rs"
click node_cluster_client "https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-client/src/lib.rs"
click node_cluster_server "https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-server/src/connection.rs"

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_cli,node_ui,node_sdk toneBlue
class node_graph,node_admission,node_verifier,node_supervisor,node_controller,node_ledger toneAmber
class node_runner,node_process,node_delivery toneMint
class node_local,node_cloud,node_cluster,node_cluster_client,node_cluster_server toneRose
class node_user,node_github toneIndigo
```

## Components

### Authoring and clients

- [Native CLI](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/main.rs): `zeroshot/src/main.rs`
- [Workspace UI](https://github.com/covibes/zeroshot/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Python client](https://github.com/covibes/zeroshot/blob/main/sdks/python/src/zeroshot/client.py): `sdks/python/src/zeroshot/client.py`

### Run orchestration

- [Authored graph](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/full_v1_reducer.rs): `zeroshot/src/full_v1_reducer.rs`
- [Run admission](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_admission.rs): `zeroshot/src/native_v2_admission.rs`
- [Graph verifier](https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-server/src/graph_verifier.rs): `crates/openengine-cluster-server/src/graph_verifier.rs`
- [Run supervisor](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_supervisor.rs): `zeroshot/src/native_v2_supervisor.rs`
- [Portable controller](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_portable_controller/controller.rs): `zeroshot/src/native_v2_portable_controller/controller.rs`
- [Run ledger](https://github.com/covibes/zeroshot/tree/main/zeroshot/src/v2_run_ledger): `zeroshot/src/v2_run_ledger`

### Worker execution and delivery

- [Node runner](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_runner.rs): `zeroshot/src/native_v2_runner.rs`
- [Provider processes](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/execution/process.rs): `zeroshot/src/execution/process.rs`
- [Git delivery](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_delivery.rs): `zeroshot/src/native_v2_delivery.rs`

### Targets and protocols

- [Local target](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_portable_controller.rs): `zeroshot/src/native_v2_portable_controller.rs`
- [Cloud target](https://github.com/covibes/zeroshot/blob/main/zeroshot/src/native_v2_cloud.rs): `zeroshot/src/native_v2_cloud.rs`
- [Cluster protocol](https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-protocol/src/lib.rs): `crates/openengine-cluster-protocol/src/lib.rs`
- [Cluster client](https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-client/src/lib.rs): `crates/openengine-cluster-client/src/lib.rs`
- [Cluster server](https://github.com/covibes/zeroshot/blob/main/crates/openengine-cluster-server/src/connection.rs): `crates/openengine-cluster-server/src/connection.rs`

### Other components

- **Engineer**
- **GitHub**

## Connections

- Engineer → Native CLI: submits goal (evidence: `README.md`)
- Engineer → Workspace UI: edits profiles (evidence: `README.md`)
- Engineer → Python client: submits runs (evidence: `sdks/python/src/zeroshot/client.py`)
- Native CLI → Run admission: starts run
- Workspace UI → Native CLI: uses profiles
- Run admission → Graph verifier: validates graph (evidence: `zeroshot/src/native_v2_admission.rs`)
- Run admission → Authored graph: admits graph (evidence: `zeroshot/src/native_v2_admission.rs`)
- Portable controller → Run admission: admits submission (evidence: `zeroshot/src/native_v2_portable_controller/controller.rs`)
- Portable controller → Run supervisor: starts supervision (evidence: `zeroshot/src/native_v2_portable_controller/controller.rs`)
- Run supervisor → Authored graph: reduces history (evidence: `zeroshot/src/native_v2_supervisor.rs`)
- Run supervisor → Run ledger: reads and appends (evidence: `zeroshot/src/native_v2_supervisor.rs`)
- Run supervisor → Node runner: dispatches nodes (evidence: `zeroshot/src/native_v2_supervisor.rs`)
- Node runner → Provider processes: runs providers
- Run supervisor → Git delivery: dispatches delivery (evidence: `zeroshot/src/native_v2_supervisor.rs`)
- Local target → Portable controller: hosts runs (evidence: `zeroshot/src/native_v2_portable_controller.rs`)
- Cloud target → Portable controller: hosts runs (evidence: `zeroshot/src/native_v2_cloud.rs`)
- Cloud target → Run ledger: stores run state (evidence: `zeroshot/src/native_v2_cloud.rs`)
- Git delivery → GitHub: delivers changes (evidence: `README.md`)
- Native CLI → Cluster client: connects to target
- Cluster client → Cluster protocol: exchanges messages
- Cluster server → Cluster protocol: handles messages
