Project Structure

The swarmtest codebase is organized into a clear module structure:

swarmtest/
├── src/
│   ├── cli.ts                    # CLI entry point (commander)
│   ├── index.ts                  # Public API exports
│   ├── core/
│   │   ├── Agent.ts              # Individual bot agent
│   │   └── Swarm.ts              # Swarm orchestrator
│   ├── behaviors/
│   │   ├── BehaviorTree.ts       # Tree node implementations & hydration
│   │   ├── TreeSchema.ts         # TreeNode type, validation, hashing
│   │   └── RandomWalk.ts         # Default fallback behavior
│   ├── detection/
│   │   ├── Detector.ts           # Detector interface & Finding type
│   │   ├── CrashDetector.ts      # Unexpected disconnects & silent servers
│   │   ├── ProtocolErrorDetector.ts  # Unexpected error codes
│   │   ├── DesyncDetector.ts     # Cross-agent state inconsistencies
│   │   ├── LatencyDetector.ts    # Latency spikes & degradation
│   │   ├── InvariantDetector.ts  # Game-specific rule violations
│   │   └── MessageRateDetector.ts # Duplicate messages & floods
│   ├── generation/
│   │   ├── TreeGenerator.ts      # Claude-powered tree generation
│   │   ├── TreeLibrary.ts        # Persistent tree storage
│   │   ├── TreeRecorder.ts       # Records trees that trigger findings
│   │   └── TreeTrimmer.ts        # Deduplicates similar trees
│   ├── protocol/
│   │   ├── GameAdapter.ts        # GameAdapter interface
│   │   └── MessageLog.ts         # Per-agent message history
│   └── reporting/
│       ├── Reporter.ts           # Reporter interface & summary types
│       ├── ConsoleReporter.ts    # Terminal output
│       └── JsonReporter.ts       # JSON file output
├── adapters/
│   ├── tipo/
│   │   ├── TipoAdapter.ts       # Tipo game adapter
│   │   ├── TipoAgentState.ts    # Tipo state types
│   │   ├── TipoMessages.ts      # Tipo protocol messages
│   │   └── behaviors/
│   │       ├── TipoExplorer.ts   # Exploration behavior tree
│   │       └── TipoBattler.ts    # Battle-focused behavior tree
│   └── playertwo/
│       ├── PlayerTwoAdapter.ts   # PlayerTwo game adapter
│       └── behaviors/
│           ├── GenericExplorer.ts
│           └── LobbyStresser.ts
├── trees/                        # Saved regression trees (per game)
│   ├── tipo/
│   └── playertwo/
├── reports/                      # JSON test reports
├── package.json
└── tsconfig.json

Key Directories

src/core/

The core orchestration layer. Swarm manages the lifecycle of a test run: spawning agents, assigning behavior trees, running detection loops, and producing reports. Agent handles a single bot’s WebSocket connection, behavior tick loop, and state management.

src/behaviors/

The behavior tree engine. TreeSchema.ts defines the JSON schema for trees. BehaviorTree.ts implements all node types (sequence, selector, repeat, random_selector, action, wait, condition, probability) and the hydrateTree() function that converts JSON into executable nodes.

src/detection/

Pluggable detectors that monitor agent traffic and state for anomalies. Each detector implements the Detector interface and produces Finding objects with severity levels (crash, bug, jank, warning, info).

src/generation/

The LLM integration layer. TreeGenerator prompts Claude to generate behavior trees. TreeLibrary persists trees to disk. TreeRecorder saves trees that trigger findings. TreeTrimmer deduplicates similar trees using normalized Levenshtein distance.

src/protocol/

The adapter interface and shared protocol utilities. GameAdapter defines the contract that game-specific adapters must implement. MessageLog provides a bounded circular buffer of sent/received messages per agent.

src/reporting/

Output formatters. ConsoleReporter prints a human-readable summary to the terminal. JsonReporter writes a structured JSON file.

adapters/

Game-specific adapter implementations. Each adapter lives in its own directory with its protocol types, state management, and optional handwritten behavior trees.

trees/

Persistent storage for regression trees, organized by game name. Each file is a JSON SavedTree object containing the tree definition, metadata, and associated findings.

reports/

Output directory for JSON test reports, with timestamped filenames like swarm-report-2026-02-21T04-12-40-307Z.json.

Built with Ptero