# n1neman/sapper-v2 architecture

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

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

## Overview

sapper is an autonomous, multi-agent penetration-testing harness for authorized competition arenas. Its workflow is to maintain a shared fact-and-intent graph, propose and dispatch work, have agents investigate in parallel, and record results; arena operations bridge challenge lifecycle and flag submission to the competition platform. The sampled core is largely a single CLI module, with separate hook, arena-client, and knowledge-base modules. The README documents broader legion roles and tmux coordination, but those runtime implementations were not sampled, so those links are documented rather than inferred from unsampled code.

Main entry points: [`lib/sapper.py`](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py) (Sapper CLI), [`docker/commander`](https://github.com/n1neman/sapper-v2/tree/master/docker/commander) (Agent Legion), [`lib/sapper-hook.py`](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper-hook.py) (Claude Hook Bridge), [`lib/arena.py`](https://github.com/n1neman/sapper-v2/blob/master/lib/arena.py) (Arena Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Work Coordination"]
  node_sapper["Sapper CLI<br/>[sapper.py]"]
  node_dispatch["Work Dispatch<br/>[sapper.py]"]
  node_agents["Agent Legion"]
  node_watchdog["Watchdog<br/>[watchdog.sh]"]
end

subgraph group_memory["Shared Memory"]
  node_store[("Fact-Intent Graph<br/>[sapper.py]")]
  node_hook["Claude Hook Bridge<br/>[sapper-hook.py]"]
  node_knowledge[("Offline Knowledge Base<br/>[kb.py]")]
end

subgraph group_arena["Arena Operations"]
  node_arena_bridge["Arena Bridge<br/>[arena.py]"]
end

subgraph group_integration["Runtime Integrations"]
end

node_user(("Operator"))
node_platform["Competition Platform"]
node_claude["Claude Code"]
node_tmux["tmux"]

node_user -->|"runs commands"| node_sapper
node_sapper -->|"updates graph"| node_store
node_sapper -->|"starts dispatch"| node_dispatch
node_dispatch -->|"reads frontier"| node_store
node_dispatch -->|"assigns work"| node_agents
node_agents -->|"records findings"| node_store
node_watchdog -->|"keeps alive"| node_agents
node_hook -->|"renders context"| node_store
node_claude -->|"invokes events"| node_hook
node_sapper -->|"loads client"| node_arena_bridge
node_arena_bridge -->|"calls API"| node_platform
node_agents -->|"uses sessions"| node_tmux
node_sapper -.-> node_knowledge

click node_sapper "https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py"
click node_dispatch "https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py"
click node_agents "https://github.com/n1neman/sapper-v2/tree/master/docker/commander"
click node_watchdog "https://github.com/n1neman/sapper-v2/blob/master/docker/commander/watchdog.sh"
click node_store "https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py"
click node_hook "https://github.com/n1neman/sapper-v2/blob/master/lib/sapper-hook.py"
click node_knowledge "https://github.com/n1neman/sapper-v2/blob/master/lib/kb.py"
click node_arena_bridge "https://github.com/n1neman/sapper-v2/blob/master/lib/arena.py"

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_sapper,node_dispatch,node_agents,node_watchdog toneBlue
class node_store,node_hook,node_knowledge toneAmber
class node_arena_bridge toneMint
class node_user,node_platform,node_claude,node_tmux toneIndigo
```

## Components

### Work Coordination

- [Sapper CLI](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Work Dispatch](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Agent Legion](https://github.com/n1neman/sapper-v2/tree/master/docker/commander): `docker/commander`
- [Watchdog](https://github.com/n1neman/sapper-v2/blob/master/docker/commander/watchdog.sh): `docker/commander/watchdog.sh`

### Shared Memory

- [Fact-Intent Graph](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper.py): `lib/sapper.py`
- [Claude Hook Bridge](https://github.com/n1neman/sapper-v2/blob/master/lib/sapper-hook.py): `lib/sapper-hook.py`
- [Offline Knowledge Base](https://github.com/n1neman/sapper-v2/blob/master/lib/kb.py): `lib/kb.py`

### Arena Operations

- [Arena Bridge](https://github.com/n1neman/sapper-v2/blob/master/lib/arena.py): `lib/arena.py`

### Other components

- **Operator**
- **Competition Platform**
- **Claude Code**
- **tmux**

## Connections

- Operator → Sapper CLI: runs commands (evidence: `README.md`)
- Sapper CLI → Fact-Intent Graph: updates graph (evidence: `lib/sapper.py`)
- Sapper CLI → Work Dispatch: starts dispatch (evidence: `lib/sapper.py`)
- Work Dispatch → Fact-Intent Graph: reads frontier (evidence: `lib/sapper.py`)
- Work Dispatch → Agent Legion: assigns work (evidence: `README.md`)
- Agent Legion → Fact-Intent Graph: records findings (evidence: `README.md`)
- Watchdog → Agent Legion: keeps alive (evidence: `README.md`)
- Claude Hook Bridge → Fact-Intent Graph: renders context (evidence: `lib/sapper-hook.py`)
- Claude Code → Claude Hook Bridge: invokes events (evidence: `lib/sapper-hook.py`)
- Sapper CLI → Arena Bridge: loads client (evidence: `lib/sapper.py`)
- Arena Bridge → Competition Platform: calls API (evidence: `lib/arena.py`)
- Agent Legion → tmux: uses sessions (evidence: `README.md`)
- Sapper CLI → Offline Knowledge Base