# greydgl/pentestgpt architecture

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

- Interactive diagram: https://gitdiagram.com/greydgl/pentestgpt
- Repository: https://github.com/greydgl/pentestgpt

## Overview

PentestGPT offers two workflows: an autonomous staged pipeline for CTF and penetration-test runs, and an interactive legacy mode that maintains a Pentesting Task Tree (PTT). The newer agent package separates LLM decisions, planning, execution, and durable run state; `unified_agent` supplies interchangeable Claude Code and Codex backends. The README documents the autonomous stages and session persistence, but the sampled excerpts do not establish all orchestration links. The legacy orchestrator and provider client wiring are more directly evidenced by the sampled source.

Main entry points: [`pentestgpt_agent/src/pentestgpt_agent/loop.py`](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/loop.py) (Run Loop), [`pentestgpt_legacy/utils/pentest_gpt.py`](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/utils/pentest_gpt.py) (PTT Orchestrator), [`unified_agent/agent.py`](https://github.com/greydgl/pentestgpt/blob/main/unified_agent/agent.py) (Unified Agent), [`pentestgpt_legacy/llm/client.py`](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/client.py) (Session Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_autonomous["Autonomous Pipeline"]
  node_loop["Run Loop<br/>[loop.py]"]
  node_agents["Decision Agents<br/>[agents.py]"]
  node_plan["Task Planning<br/>[plan.py]"]
  node_memory[("Session State<br/>[memory.py]")]
  node_execution["Task Execution<br/>[execution.py]"]
  node_trial["Run Trial<br/>[trial.py]"]
  node_audit["Audit Trail<br/>[audit.py]"]
  node_trace["Run Trace<br/>[trace.py]"]
  node_penteststages["Asset Discovery → Vulnerabilities → Report"]
  node_ctfstages["Recon → Exploit → Walkthrough"]
end

subgraph group_runtime["Agent Runtime"]
  node_unified["Unified Agent<br/>[agent.py]"]
  node_backend["Claude / Codex<br/>[base.py]"]
  node_tools["Tool Registry<br/>[tools.py]"]
  node_toolserver["MCP Tool Server<br/>[tool_server.py]"]
end

subgraph group_legacy["Interactive Legacy"]
  node_legacycli["Legacy CLI<br/>[main.py]"]
  node_interactive["PTT Orchestrator<br/>[pentest_gpt.py]"]
  node_taskinput["Task Commands<br/>[task_handler.py]"]
  node_prompt["Role Prompts<br/>[prompt_class.py]"]
end

subgraph group_providers["LLM Providers"]
  node_client["Session Client<br/>[client.py]"]
  node_factory["Provider Factory<br/>[factory.py]"]
  node_registry["Model Registry<br/>[registry.py]"]
  node_compat["OpenAI-Compatible"]
end

node_operator(("Operator"))
node_target(("Pentest Target"))
node_provider(("LLM Provider"))
node_backendcli(("Agent CLI"))

node_operator -->|"starts run"| node_loop
node_target -->|"sets target"| node_loop
node_loop -->|"requests decisions"| node_agents
node_loop -->|"persists state"| node_memory
node_agents -->|"proposes tasks"| node_plan
node_loop -->|"dispatches work"| node_execution
node_execution -->|"runs agent"| node_unified
node_unified -->|"selects backend"| node_backend
node_backend -.->|"drives CLI"| node_backendcli
node_unified -->|"configures tools"| node_tools
node_tools -->|"serves tools"| node_toolserver
node_loop -->|"records trial"| node_trial
node_loop -->|"audits run"| node_audit
node_loop -->|"traces run"| node_trace
node_legacycli -->|"starts session"| node_interactive
node_interactive -->|"accepts commands"| node_taskinput
node_interactive -->|"uses prompts"| node_prompt
node_interactive -->|"sends role prompts"| node_client
node_client -->|"uses provider"| node_factory
node_factory -->|"resolves model"| node_registry
node_client -->|"requests completions"| node_provider
node_provider -.->|"uses compatible API"| node_compat
node_loop -->|"runs pentest stages"| node_penteststages
node_loop -->|"runs CTF stages"| node_ctfstages

click node_loop "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/loop.py"
click node_agents "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/agents.py"
click node_plan "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/plan.py"
click node_memory "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/memory.py"
click node_execution "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/execution.py"
click node_trial "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/trial.py"
click node_audit "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/audit.py"
click node_trace "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/trace.py"
click node_unified "https://github.com/greydgl/pentestgpt/blob/main/unified_agent/agent.py"
click node_backend "https://github.com/greydgl/pentestgpt/blob/main/unified_agent/backends/base.py"
click node_tools "https://github.com/greydgl/pentestgpt/blob/main/unified_agent/tools.py"
click node_toolserver "https://github.com/greydgl/pentestgpt/blob/main/unified_agent/tool_server.py"
click node_legacycli "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/main.py"
click node_interactive "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/utils/pentest_gpt.py"
click node_taskinput "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/utils/task_handler.py"
click node_prompt "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/prompts/prompt_class.py"
click node_client "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/client.py"
click node_factory "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/factory.py"
click node_registry "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/registry.py"
click node_compat "https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/providers/openai_compatible.py"
click node_penteststages "https://github.com/greydgl/pentestgpt/tree/main/pentestgpt_agent/src/pentestgpt_agent"
click node_ctfstages "https://github.com/greydgl/pentestgpt/tree/main/pentestgpt_agent/src/pentestgpt_agent"

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_loop,node_agents,node_plan,node_memory,node_execution,node_trial,node_audit,node_trace,node_penteststages,node_ctfstages toneBlue
class node_unified,node_backend,node_tools,node_toolserver toneAmber
class node_legacycli,node_interactive,node_taskinput,node_prompt toneMint
class node_client,node_factory,node_registry,node_compat toneRose
class node_operator,node_target,node_provider,node_backendcli toneIndigo
```

## Components

### Autonomous Pipeline

- [Run Loop](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/loop.py): `pentestgpt_agent/src/pentestgpt_agent/loop.py`
- [Decision Agents](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/agents.py): `pentestgpt_agent/src/pentestgpt_agent/agents.py`
- [Task Planning](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/plan.py): `pentestgpt_agent/src/pentestgpt_agent/plan.py`
- [Session State](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/memory.py): `pentestgpt_agent/src/pentestgpt_agent/memory.py`
- [Task Execution](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/execution.py): `pentestgpt_agent/src/pentestgpt_agent/execution.py`
- [Run Trial](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/trial.py): `pentestgpt_agent/src/pentestgpt_agent/trial.py`
- [Audit Trail](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/audit.py): `pentestgpt_agent/src/pentestgpt_agent/audit.py`
- [Run Trace](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_agent/src/pentestgpt_agent/trace.py): `pentestgpt_agent/src/pentestgpt_agent/trace.py`
- [Asset Discovery → Vulnerabilities → Report](https://github.com/greydgl/pentestgpt/tree/main/pentestgpt_agent/src/pentestgpt_agent): `pentestgpt_agent/src/pentestgpt_agent`
- [Recon → Exploit → Walkthrough](https://github.com/greydgl/pentestgpt/tree/main/pentestgpt_agent/src/pentestgpt_agent): `pentestgpt_agent/src/pentestgpt_agent`

### Agent Runtime

- [Unified Agent](https://github.com/greydgl/pentestgpt/blob/main/unified_agent/agent.py): `unified_agent/agent.py`
- [Claude / Codex](https://github.com/greydgl/pentestgpt/blob/main/unified_agent/backends/base.py): `unified_agent/backends/base.py`
- [Tool Registry](https://github.com/greydgl/pentestgpt/blob/main/unified_agent/tools.py): `unified_agent/tools.py`
- [MCP Tool Server](https://github.com/greydgl/pentestgpt/blob/main/unified_agent/tool_server.py): `unified_agent/tool_server.py`

### Interactive Legacy

- [Legacy CLI](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/main.py): `pentestgpt_legacy/main.py`
- [PTT Orchestrator](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/utils/pentest_gpt.py): `pentestgpt_legacy/utils/pentest_gpt.py`
- [Task Commands](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/utils/task_handler.py): `pentestgpt_legacy/utils/task_handler.py`
- [Role Prompts](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/prompts/prompt_class.py): `pentestgpt_legacy/prompts/prompt_class.py`

### LLM Providers

- [Session Client](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/client.py): `pentestgpt_legacy/llm/client.py`
- [Provider Factory](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/factory.py): `pentestgpt_legacy/llm/factory.py`
- [Model Registry](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/registry.py): `pentestgpt_legacy/llm/registry.py`
- [OpenAI-Compatible](https://github.com/greydgl/pentestgpt/blob/main/pentestgpt_legacy/llm/providers/openai_compatible.py): `pentestgpt_legacy/llm/providers/openai_compatible.py`

### Other components

- **Operator**
- **Pentest Target**
- **LLM Provider**
- **Agent CLI**

## Connections

- Operator → Run Loop: starts run
- Pentest Target → Run Loop: sets target
- Run Loop → Decision Agents: requests decisions
- Run Loop → Session State: persists state
- Decision Agents → Task Planning: proposes tasks
- Run Loop → Task Execution: dispatches work
- Task Execution → Unified Agent: runs agent
- Unified Agent → Claude / Codex: selects backend
- Claude / Codex → Agent CLI: drives CLI
- Unified Agent → Tool Registry: configures tools
- Tool Registry → MCP Tool Server: serves tools
- Run Loop → Run Trial: records trial
- Run Loop → Audit Trail: audits run
- Run Loop → Run Trace: traces run
- Legacy CLI → PTT Orchestrator: starts session
- PTT Orchestrator → Task Commands: accepts commands
- PTT Orchestrator → Role Prompts: uses prompts
- PTT Orchestrator → Session Client: sends role prompts
- Session Client → Provider Factory: uses provider
- Provider Factory → Model Registry: resolves model
- Session Client → LLM Provider: requests completions
- LLM Provider → OpenAI-Compatible: uses compatible API
- Run Loop → Asset Discovery → Vulnerabilities → Report: runs pentest stages
- Run Loop → Recon → Exploit → Walkthrough: runs CTF stages
