CLAUDE.md · s0ld13rr/pentestcode

Sections

1. What This Is
2. Project Structure
3. Multi-Agent Architecture
4. Key Files
5. Commands
6. What Was Done (Phase 1-3)
7. What Was Done (Phase 3 cleanup + Phase 4 partial + Phase 5)
8. What Was Done (Quality Plan — dapper-percolating-badger.md)
9. What Was Done (Architecture Roadmap — Waves 1-2)
10. What Was Done (Competitive Gap Closure — 2026-07-09)
11. What Was Done (Community Feedback UX — 2026-07-12)
12. What Was Done (CyberStrike Competitive Analysis — 2026-08-15)
13. What Was Done (Self-Improvement System — 2026-08-17)
14. What Remains (TODO)
15. Design Decisions
16. Architecture Notes (gotchas)

First lines (shown under the repo's MIT license)

# CLAUDE.md

## What This Is

PentestCode — AI pentesting agent, hard fork of [OpenCode](https://github.com/anomalyco/opencode) (dev branch, MIT).
OpenCode — coding agent (183k stars). We stripped code-editing focus and rebuilt it for penetration testing.

**Stack**: TypeScript, Bun, Effect library, Turbo monorepo.
**TUI**: React/Ink (via @opentui). **LLM**: ai-sdk (20+ providers). **DB**: SQLite (drizzle-orm).

## Project Structure

```
opencode-fork/                    # Will be renamed to pentestcode
├── packages/
│   ├── core/src/                 # Domain logic, tools, sessions
│   │   ├── engagement/           # NEW: pentest state (schema, store, context)
│   │   ├── session/              # Session management (runner, compaction)
│   │   ├── tool/                 # Tool registry + built-in tools
│   │   ├── system-context/       # Context sources injected into prompts
│   │   ├── skill/                # Skill discovery + loading
│   │   └── agent.ts              # Agent schema, default ID = "pentest"
│   ├── opencode/src/             # Main application package
│   │   ├── agent/agent.ts        # Agent definitions (pentest/recon/scanner/...)
│   │   ├── session/prompt/*.txt  # System prompts per agent
│   │   ├── session/system.ts     # Prompt assembly (uses pentest.txt)
│   │   ├── session/prompt.ts     # Session runner loop
│   │   ├── tool/                 # Tool implementations (registry.ts is master)
│   │   ├── skill/                # Skill discovery paths
│   │   └── cli/                  # CLI commands (yargs)
│   ├── llm/                      # LLM client abstraction (ai-sdk)
│   ├── tui/                      # Terminal UI (React/Ink)
│   ├── server/                   # HTTP server + SSE events
│   ├── schema/                   # Shared type definitions
│   ├── protocol/                 # HTTP API contracts
│   ├── plugin/                   # Plugin system
│   └── client/                   # Generated SDK client
├── skills/
│   ├── phases/                   # Phase checklists (6 files)
│   ├── services/                 # Service knowledge packs (9 files)
│   └── playbooks/                # Methodology playbooks (4 files)
└── ...
```

## Multi-Agent Architecture

| Agent | Type | Description |
|-------|------|-------------|
| **pentest** | primary (default) | Strategist-coordinator. Plans, spawns subagents, can execute directly. |
| **recon** | primary | Reconnaissance (passive/active by user choice). |
| **scanner** | subagent | Port/vuln scanning. Spawned for parallel host scanning. |
| **enumerator** | subagent | Deep service enumeration (SMB/LDAP/web/etc). |
| **exploiter** | subagent | Exploitation of specific vulnerabilities. |
| **reporter** | subagent | Report generation from engagement state. No bash. |
| **identity** | subagent | AD, LDAP, Kerberos, IAM, NTLM, certificate-based auth attacks. |
| **infrastructure** | subagent | Network services, SNMP, IPMI, RDP, SSH, FTP, databases, misconfigs. |
| **post_exploit** | subagent | Lateral movement, privesc, persistence, credential harvesting, pivoting. |
| **exploit_dev** | subagent | Custom exploits, payload generation, PoC development, bypass techniques. |
| **critic** | subagent | Finding validator. Checks false positives, validates evidence. Read-only. |
| **webapp** | subagent | Web application specialist. OWASP Top 10, API security, XSS, SQLi, SSRF. |
| **reflector** | subagent | Post-engagement reflection. Analyzes outcomes, generates learned skills, records knowledge. Read-only state. |
| compaction | hidden | Context compression (inherited from OpenCode). |
| title | hidden | Session title generation. |
| summary | hidden | Session summary. |

Agents defined in: `packages/opencode/src/agent/agent.ts`
Prompts in: `packages/opencode/src/session/prompt/*.txt` and `packages/opencode/src/agent/prompt/*.txt`

## Key Files

- **Agent loop**: `packages/opencode/src/session/prompt.ts` → `runLoop()` (line ~1081)
- **LLM call**: `packages/core/src/session/runner/llm.ts`
- **Tool registry**: `packages/opencode/src/tool/registry.ts` (master registry)
- **Tool definitions (core)**: `packages/core/src/tool/builtins.ts`
- **System prompt assembly**: `packages/opencode/src/session/system.ts`
- **Agent definitions**: `packages/opencode/src/agent/agent.ts`
- **Engagement schema**: `packages/core/src/engagement/schema.ts` (Effect Schema, State/Host/Vuln/Cred types)
- **Engagement store**: `packages/core/src/engagement/store.ts` (global Ref + JSON persistence)
- **Engagement context (V2)**: `packages/core/src/engagement/context.ts` (SystemContext source, V2 only)
- **Reflection schema**: `packages/core/src/engagement/reflection.ts` (TechniqueOutcome, FPPattern, LearnedTechnique, EngagementReflection)
- **Knowledge store**: `packages/core/src/knowledge/store.ts` (global cross-engagement memory, `~/.pentestcode/knowledge/global.json`)
- **Knowledge schema**: `packages/core/src/knowledge/schema.ts` (ToolEffectiveness, FPSignature, KnowledgeState)
- **Pentest tools**: `packages/opencode/src/tool/state-query.ts`, `state-update.ts`, `nmap-parse.ts`, `nuclei-parse.ts`, `gobuster-parse.ts`, `cme-parse.ts`, `bloodhound-parse.ts`, `cred-spray.ts`, `scope-check.ts`, `phase-control.ts`, `report-gen.ts`, `sqlmap-parse.ts`, `xss-detect.ts`, `jwt-analyze.ts`, `tunnel-manage.ts`, `attack-path-suggest.ts`, `ensure-tools.ts`, `os-hook.ts`, `inject-probe.ts`, `knowledge.ts`
- **App runtime (V1)**: `packages/opencode/src/effect/app-runtime.ts` (LayerNode graph)
- **Location services (V2)**: `packages/core/src/location-services.ts` (V2 layer graph)
- **Config**: `.pentestcode/pentestcode.jsonc`
- **Skills**: `skills/` directory, discovered via `**/SKILL.md` glob

## Commands

```bash
# Install dependencies
bun install

# Run (dev mode)
bun run dev

# Run TUI directly
bun run --cwd packages/opencode --conditions=browser src/index.ts

# Typecheck
bun turbo typecheck
```

## What Was Done (Phase 1-3)

### Phase 1: Fork & Strip
- Removed 12 packages: codemode, desktop, enterprise, storybook, docs, console, slack, stats, web, sdks, infra, artifacts
- Removed translated READMEs, SST config, Nix files
- Updated package.json: name→pentestcode, description→pentesting
- Removed edit/apply-patch/todowrite from core builtins
- Removed GitHub Copilot integration from core
- 178M → 109M

### Phase 2: Pentest Domain + Wiring
- **Agents rewritten**: build/plan/general/explore → pentest/recon/scanner/enumerator/exploiter/reporter
- **Default agent**: "pentest" everywhere (was "build")
- **Prompts created**: pentest.txt, recon.txt, scanner.txt, enumerator.txt, exploiter.txt, reporter.txt + mode switching prompts
- **system.ts**: Always uses pentest.txt (bypasses model-specific coding prompts)
- **Engagement state module**: schema.ts (Effect Schema models), store.ts (file persistence), context.ts (SystemContext source)
- **19 skill files**: 6 phases, 9 services, 4 playbooks
- **Global engagement store**: `~/.pentestcode/engagements/` — NOT per-directory (security work isn't tied to a cwd)
- **EngagementStore.node** registered in V1 app-runtime (`app-runtime.ts`) and V2 location-services (`location-services.ts`)
- **Engagement context injected** into V1 system prompt (`prompt.ts`) — compact JSON with phase, mode, hosts, vulns
- **Auto-load**: session start loads last engagement from `.last` file
- **Skills config**: `.pentestcode/pentestcode.jsonc` has `skills.paths: ["./skills"]`. Relative skill paths resolve against the session cwd, each config-dir project root, and the global `~/.pentestcode/skills` home — so bundled skills load regardless of cwd (see `packages/opencode/src/skill/index.ts` `discoverSkills`)

### Phase 3: Pentest Tools (6 tools, 12 files)
- **state_query** — query engagement state (11 query types: summary, hosts, vulns, creds, scope, phase, flags, tasks, host, full, engagements)
- **state_update** — structured mutations (20+ actions: CRUD for hosts/vulns/credentials/access, phases, modes, scope, flags, notes, attack steps, domain, objectives)
- **nmap_parse** — parse nmap XML/greppable output via htmlparser2 SAX, auto-updates engagement state
- **nuclei_parse** — parse Nuclei JSON output, auto-create vulns with severity
- **gobuster_parse** — parse gobuster/feroxbuster output, classify sensitive files/admin panels/backups
- **cme_parse** — parse CrackMapExec/NetExec output, auto-update creds/access/hosts
- **bloodhound_parse** — parse SharpHound JSON, populate AD domain model
- **cred_spray** — credential reuse planning (plan/suggest spray commands across discovered services)
- **scope_check** — CIDR containment, wildcard domain matching, excludes priority
- **phase_control** — status/next/set phase management
- **report_gen** — markdown/JSON reports with 6 sections (executive_summary, scope, findings, attack_path, credentials, recommendations)
- **task_graph** — Pentesting Task Tree (PTT) management
- All tools registered in `packages/opencode/src/tool/registry.ts`
- Agent permissions configured per-agent in `packages/opencode/src/agent/agent.ts`

## What Was Done (Phase 3 cleanup + Phase 4 partial + Phase 5)

### Phase 3 Cleanup
- [x] Deleted stale test files: `code-mode.test.ts`, `code-mode-integration.test.ts`, `apply_patch.test.ts`, `lsp.test.ts`
- [x] Cleaned `parameters.test.ts` — removed apply_patch/lsp/todo imports, schemas, and describe blocks
- [x] Deleted orphaned snapshot file `__snapshots__/parameters.test.ts.snap`
- [x] Verified `@opencode-ai/codemode` dependency already removed
- [x] Deleted orphaned description `todowrite.txt`

### Phase 4: Code-Editing Remnant Removal (partial)
- [x] Removed `LspTool` from registry init and builtin array (kept `LSP.node` in deps — EditTool depends on LSP.Service)
- [x] Deleted `src/tool/lsp.ts` and `src/tool/lsp.txt` (tool file + description)
- [x] Cleaned CLI tool rendering (`cmd/run/tool.ts`) — removed ApplyPatchTool, LspTool, TodoWriteTool imports, types, render functions, TOOL_RULES entries (~300 lines)
- [x] Kept LSP/Format/Worktree service modules intact (deeply integrated, removal breaks types)

### Phase 5: Flow System
- [x] 8 slash commands: `/status`, `/targets`, `/vulns`, `/creds`, `/scope`, `/phase`, `/mode`, `/report`