# s0ld13rr/pentestcode architecture

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

- Interactive diagram: https://gitdiagram.com/s0ld13rr/pentestcode
- Repository: https://github.com/s0ld13rr/pentestcode

## Overview

PentestCode is a terminal-based autonomous penetration-testing agent. The main workflow is an operator prompt entering a session, a lead agent coordinating specialist agents and pentest tools, and parsed findings updating shared engagement state for further planning and reporting. The README documents these product capabilities; sampled source confirms the server route assembly and state-query tool, but does not expose the full agent dispatch or tool-execution path, so those documented links are cited to the README.

Main entry points: [`packages/core/src/agent.ts`](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/agent.ts) (Lead Agent), [`packages/core/src/engagement/store.ts`](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/store.ts) (Engagement State), [`packages/core/src/tool/application-tools.ts`](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/application-tools.ts) (Pentest Tools), [`packages/tui/src/app.tsx`](https://github.com/s0ld13rr/pentestcode/blob/main/packages/tui/src/app.tsx) (Terminal Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Operator Interface"]
  node_cli["CLI Commands<br/>[commands.ts]"]
  node_terminal["Terminal Session<br/>[app.tsx]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_lead["Lead Agent<br/>[agent.ts]"]
  node_specialists["Specialist Agents<br/>[agent.ts]"]
  node_taskcoord["Task Coordination<br/>[orchestrator.ts]"]
end

subgraph group_operations["Pentest Operations"]
  node_pentesttools["Pentest Tools"]
  node_toolregistry["Tool Registry<br/>[registry.ts]"]
  node_parsers["Finding Parsers"]
  node_skills["Skills<br/>[discovery.ts]"]
end

subgraph group_engagement["Engagement Memory"]
  node_engagementstate[("Engagement State<br/>[store.ts]")]
  node_statequery["State Queries<br/>[state-query.ts]"]
  node_attackpaths["Attack Paths<br/>[task-graph.ts]"]
  node_reports["Findings Reports"]
end

subgraph group_platform["Runtime Platform"]
  node_httpserver["HTTP API<br/>[routes.ts]"]
  node_providers["LLM Providers<br/>[provider.ts]"]
  node_llmrouting["LLM Routing<br/>[client.ts]"]
  node_storage[("Persistent Storage<br/>[storage.ts]")]
end

node_operator(("Operator"))
node_target(("Target Systems"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"starts session"| node_terminal
node_cli -.->|"submits prompt"| node_lead
node_terminal -.->|"submits prompt"| node_lead
node_lead -->|"plans tasks"| node_taskcoord
node_taskcoord -->|"dispatches agents"| node_specialists
node_lead -->|"uses tools"| node_pentesttools
node_pentesttools -.->|"registers tools"| node_toolregistry
node_pentesttools -->|"tests services"| node_target
node_pentesttools -->|"parses output"| node_parsers
node_parsers -->|"records findings"| node_engagementstate
node_specialists -->|"shares state"| node_engagementstate
node_lead -->|"loads knowledge"| node_skills
node_lead -.->|"requests inference"| node_llmrouting
node_llmrouting -->|"routes requests"| node_providers
node_terminal -.->|"uses API"| node_httpserver
node_statequery -->|"queries state"| node_engagementstate
node_lead -->|"suggests routes"| node_attackpaths
node_engagementstate -->|"feeds findings"| node_reports
node_engagementstate -.->|"persists state"| node_storage
node_httpserver -.->|"provides services"| node_engagementstate

click node_cli "https://github.com/s0ld13rr/pentestcode/blob/main/packages/cli/src/commands/commands.ts"
click node_terminal "https://github.com/s0ld13rr/pentestcode/blob/main/packages/tui/src/app.tsx"
click node_httpserver "https://github.com/s0ld13rr/pentestcode/blob/main/packages/server/src/routes.ts"
click node_lead "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/agent.ts"
click node_specialists "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/config/agent.ts"
click node_taskcoord "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/orchestrator.ts"
click node_pentesttools "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/application-tools.ts"
click node_toolregistry "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/registry.ts"
click node_parsers "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/application-tools.ts"
click node_skills "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/skill/discovery.ts"
click node_providers "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/plugin/provider.ts"
click node_llmrouting "https://github.com/s0ld13rr/pentestcode/blob/main/packages/llm/src/route/client.ts"
click node_engagementstate "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/store.ts"
click node_statequery "https://github.com/s0ld13rr/pentestcode/blob/main/packages/opencode/src/tool/state-query.ts"
click node_attackpaths "https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/task-graph.ts"
click node_reports "https://github.com/s0ld13rr/pentestcode/tree/main/packages/core/src/engagement"
click node_storage "https://github.com/s0ld13rr/pentestcode/blob/main/packages/opencode/src/storage/storage.ts"

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_terminal toneBlue
class node_lead,node_specialists,node_taskcoord toneAmber
class node_pentesttools,node_toolregistry,node_parsers,node_skills toneMint
class node_engagementstate,node_statequery,node_attackpaths,node_reports toneRose
class node_httpserver,node_providers,node_llmrouting,node_storage,node_operator,node_target toneIndigo
```

## Components

### Operator Interface

- [CLI Commands](https://github.com/s0ld13rr/pentestcode/blob/main/packages/cli/src/commands/commands.ts): `packages/cli/src/commands/commands.ts`
- [Terminal Session](https://github.com/s0ld13rr/pentestcode/blob/main/packages/tui/src/app.tsx): `packages/tui/src/app.tsx`

### Agent Orchestration

- [Lead Agent](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/agent.ts): `packages/core/src/agent.ts`
- [Specialist Agents](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/config/agent.ts): `packages/core/src/config/agent.ts`
- [Task Coordination](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/orchestrator.ts): `packages/core/src/engagement/orchestrator.ts`

### Pentest Operations

- [Pentest Tools](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/application-tools.ts): `packages/core/src/tool/application-tools.ts`
- [Tool Registry](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/registry.ts): `packages/core/src/tool/registry.ts`
- [Finding Parsers](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/tool/application-tools.ts): `packages/core/src/tool/application-tools.ts`
- [Skills](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/skill/discovery.ts): `packages/core/src/skill/discovery.ts`

### Engagement Memory

- [Engagement State](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/store.ts): `packages/core/src/engagement/store.ts`
- [State Queries](https://github.com/s0ld13rr/pentestcode/blob/main/packages/opencode/src/tool/state-query.ts): `packages/opencode/src/tool/state-query.ts`
- [Attack Paths](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/engagement/task-graph.ts): `packages/core/src/engagement/task-graph.ts`
- [Findings Reports](https://github.com/s0ld13rr/pentestcode/tree/main/packages/core/src/engagement): `packages/core/src/engagement`

### Runtime Platform

- [HTTP API](https://github.com/s0ld13rr/pentestcode/blob/main/packages/server/src/routes.ts): `packages/server/src/routes.ts`
- [LLM Providers](https://github.com/s0ld13rr/pentestcode/blob/main/packages/core/src/plugin/provider.ts): `packages/core/src/plugin/provider.ts`
- [LLM Routing](https://github.com/s0ld13rr/pentestcode/blob/main/packages/llm/src/route/client.ts): `packages/llm/src/route/client.ts`
- [Persistent Storage](https://github.com/s0ld13rr/pentestcode/blob/main/packages/opencode/src/storage/storage.ts): `packages/opencode/src/storage/storage.ts`

### Other components

- **Operator**
- **Target Systems**

## Connections

- Operator → CLI Commands: runs commands (evidence: `README.md`)
- Operator → Terminal Session: starts session (evidence: `README.md`)
- CLI Commands → Lead Agent: submits prompt
- Terminal Session → Lead Agent: submits prompt
- Lead Agent → Task Coordination: plans tasks (evidence: `README.md`)
- Task Coordination → Specialist Agents: dispatches agents (evidence: `README.md`)
- Lead Agent → Pentest Tools: uses tools (evidence: `README.md`)
- Pentest Tools → Tool Registry: registers tools
- Pentest Tools → Target Systems: tests services (evidence: `README.md`)
- Pentest Tools → Finding Parsers: parses output (evidence: `README.md`)
- Finding Parsers → Engagement State: records findings (evidence: `README.md`)
- Specialist Agents → Engagement State: shares state (evidence: `README.md`)
- Lead Agent → Skills: loads knowledge (evidence: `README.md`)
- Lead Agent → LLM Routing: requests inference
- LLM Routing → LLM Providers: routes requests (evidence: `packages/llm/src/route/client.ts`)
- Terminal Session → HTTP API: uses API
- State Queries → Engagement State: queries state (evidence: `packages/opencode/src/tool/state-query.ts`)
- Lead Agent → Attack Paths: suggests routes (evidence: `README.md`)
- Engagement State → Findings Reports: feeds findings (evidence: `README.md`)
- Engagement State → Persistent Storage: persists state
- HTTP API → Engagement State: provides services
