# muxuejc/sapper-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/muxuejc/sapper-v2
- Repository: https://github.com/muxuejc/sapper-v2

## Overview

sapper-v2 is a multi-agent pentest orchestration harness. Its documented campaign workflow is a commander reading the competition board, dispatching agents to work in parallel, and coordinating their findings through shared memory; a watchdog supports long unattended runs. The sampled CLI implements a filesystem-backed fact/intent graph, dispatch operations, and an arena bridge. The README also describes agent creation and communication, but those runtime details are not shown in the sampled source. Edges reflect explicit README statements or visible source references; uncertain integration links are omitted.

Main entry points: [`lib/sapper.py`](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py) (Commander), [`lib/arena.py`](https://github.com/muxuejc/sapper-v2/blob/master/lib/arena.py) (Arena bridge), [`lib/sapper-hook.py`](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper-hook.py) (Claude hook bridge), [`lib/_settings_patch.py`](https://github.com/muxuejc/sapper-v2/blob/master/lib/_settings_patch.py) (Hook registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_campaign["Campaign orchestration"]
  node_commander["Commander<br/>[sapper.py]"]
  node_scheduler["Work scheduler<br/>[sapper.py]"]
  node_reason["Reason dispatch<br/>[sapper.py]"]
  node_explore["Explore dispatch<br/>[sapper.py]"]
  node_verify["Verify dispatch<br/>[sapper.py]"]
  node_arena_bridge["Arena bridge<br/>[arena.py]"]
end

subgraph group_memory["Shared memory"]
  node_fact_graph[("Fact graph<br/>[sapper.py]")]
  node_knowledge_base[("Knowledge base<br/>[kb.py]")]
  node_hook_bridge["Claude hook bridge<br/>[sapper-hook.py]"]
  node_settings_patch["Hook registration<br/>[_settings_patch.py]"]
end

subgraph group_agents["Agent runtime"]
  node_agent_cli["Agent CLI"]
  node_tmux_runtime["tmux runtime<br/>[tmux-drive.sh]"]
  node_watchdog["Watchdog<br/>[watchdog.sh]"]
end

subgraph group_integrations["External integrations"]
  node_claude_code["Claude Code"]
  node_arena_service["Competition platform"]
end

node_operator(("Operator"))

node_operator -.->|"starts campaign"| node_commander
node_commander -->|"dispatches work"| node_scheduler
node_commander -->|"proposes work"| node_reason
node_commander -->|"dispatches agents"| node_explore
node_commander -->|"dispatches checks"| node_verify
node_commander -.->|"uses memory"| node_fact_graph
node_hook_bridge -->|"reads and renders"| node_fact_graph
node_settings_patch -->|"registers hooks"| node_claude_code
node_claude_code -->|"invokes hooks"| node_hook_bridge
node_commander -.->|"dispatches agents"| node_agent_cli
node_agent_cli -.->|"runs in"| node_tmux_runtime
node_watchdog -.->|"keeps alive"| node_commander
node_commander -->|"uses arena"| node_arena_bridge
node_arena_bridge -->|"calls API"| node_arena_service

click node_commander "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_scheduler "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_reason "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_explore "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_verify "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_arena_bridge "https://github.com/muxuejc/sapper-v2/blob/master/lib/arena.py"
click node_fact_graph "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py"
click node_knowledge_base "https://github.com/muxuejc/sapper-v2/blob/master/lib/kb.py"
click node_hook_bridge "https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper-hook.py"
click node_settings_patch "https://github.com/muxuejc/sapper-v2/blob/master/lib/_settings_patch.py"
click node_tmux_runtime "https://github.com/muxuejc/sapper-v2/blob/master/docker/tmux-drive.sh"
click node_watchdog "https://github.com/muxuejc/sapper-v2/blob/master/docker/commander/watchdog.sh"

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_commander,node_scheduler,node_reason,node_explore,node_verify,node_arena_bridge toneBlue
class node_fact_graph,node_knowledge_base,node_hook_bridge,node_settings_patch toneAmber
class node_agent_cli,node_tmux_runtime,node_watchdog toneMint
class node_claude_code,node_arena_service toneRose
class node_operator toneIndigo
```

## Components

### Campaign orchestration

- [Commander](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Work scheduler](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Reason dispatch](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Explore dispatch](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Verify dispatch](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Arena bridge](https://github.com/muxuejc/sapper-v2/blob/master/lib/arena.py): `lib/arena.py`

### Shared memory

- [Fact graph](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Knowledge base](https://github.com/muxuejc/sapper-v2/blob/master/lib/kb.py): `lib/kb.py`
- [Claude hook bridge](https://github.com/muxuejc/sapper-v2/blob/master/lib/sapper-hook.py): `lib/sapper-hook.py`
- [Hook registration](https://github.com/muxuejc/sapper-v2/blob/master/lib/_settings_patch.py): `lib/_settings_patch.py`

### Agent runtime

- **Agent CLI**
- [tmux runtime](https://github.com/muxuejc/sapper-v2/blob/master/docker/tmux-drive.sh): `docker/tmux-drive.sh`
- [Watchdog](https://github.com/muxuejc/sapper-v2/blob/master/docker/commander/watchdog.sh): `docker/commander/watchdog.sh`

### External integrations

- **Claude Code**
- **Competition platform**

### Other components

- **Operator**

## Connections

- Operator → Commander: starts campaign (evidence: `README.md`)
- Commander → Work scheduler: dispatches work (evidence: `README.md`)
- Commander → Reason dispatch: proposes work (evidence: `README.md`)
- Commander → Explore dispatch: dispatches agents (evidence: `lib/sapper.py`)
- Commander → Verify dispatch: dispatches checks (evidence: `lib/sapper.py`)
- Commander → Fact graph: uses memory (evidence: `README.md`)
- Claude hook bridge → Fact graph: reads and renders (evidence: `lib/sapper-hook.py`)
- Hook registration → Claude Code: registers hooks (evidence: `lib/_settings_patch.py`)
- Claude Code → Claude hook bridge: invokes hooks (evidence: `lib/sapper-hook.py`)
- Commander → Agent CLI: dispatches agents (evidence: `README.md`)
- Agent CLI → tmux runtime: runs in (evidence: `README.md`)
- Watchdog → Commander: keeps alive (evidence: `README.md`)
- Commander → Arena bridge: uses arena (evidence: `lib/sapper.py`)
- Arena bridge → Competition platform: calls API (evidence: `lib/arena.py`)
