CLI Reference

swarmtest provides three commands: run, trim, and list-trees.

swarmtest run

Run a swarm test against a game server.

swarmtest run --game <game> --url <url> [options]

Required Options

OptionDescription
--game <game>Game adapter to use. Available: tipo, playertwo
--url <url>WebSocket server URL (e.g., ws://localhost:5001)

Optional Flags

OptionDefaultDescription
--agents <count>10Number of agents to spawn
--duration <seconds>60Test duration in seconds
--tick <ms>100Tick interval in milliseconds (how often each agent’s behavior tree is evaluated)
--stagger <ms>200Delay between agent connections in milliseconds
--regression-onlyoffOnly run saved regression trees (100% regression, 0% LLM, 0% handwritten)
--explore-onlyoffOnly generate fresh LLM trees (0% regression, 100% LLM, 0% handwritten)
--no-llmoffDisable LLM tree generation (50% regression, 50% handwritten)
--no-trimoffSkip post-run tree trimming
--jsonoffWrite a JSON report to ./reports/ in addition to console output
--tree-dir <dir>./trees/<game>/Directory for the tree library

Examples

# Basic test: 10 agents, 60 seconds, default behavior mix
swarmtest run --game tipo --url ws://localhost:5001

# Stress test: 50 agents for 5 minutes
swarmtest run --game tipo --url ws://localhost:5001 --agents 50 --duration 300

# Exploration: only LLM-generated trees, with JSON output
swarmtest run --game tipo --url ws://localhost:5001 --explore-only --json

# Regression-only: replay saved trees without LLM
swarmtest run --game tipo --url ws://localhost:5001 --regression-only

# Offline mode: no LLM, no API key needed
swarmtest run --game playertwo --url ws://localhost:3000 --no-llm

# Fast tick rate for timing-sensitive tests
swarmtest run --game tipo --url ws://localhost:5001 --tick 50 --stagger 100

Behavior Mix

The behavior mix determines what proportion of agents use each behavior source:

ModeRegressionLLMHandwritten
Default40%40%20%
--regression-only100%0%0%
--explore-only0%100%0%
--no-llm50%0%50%

Graceful Shutdown

Press Ctrl+C (SIGINT) or send SIGTERM to gracefully stop a running test. The swarm will:

  1. Stop all agent behavior loops
  2. Send disconnect messages to the server
  3. Close all WebSocket connections
  4. Drain remaining findings
  5. Save recorded trees
  6. Print the final report

swarmtest trim

Trim similar trees from the tree library. Trees with action sequences that are more than 80% similar (by default) are deduplicated.

swarmtest trim --game &lt;game&gt; [options]

Options

OptionDefaultDescription
--game <game>(required)Game name (tipo, playertwo)
--threshold <number>0.2Similarity threshold (0-1). Lower values = more aggressive trimming. 0.2 means trees with >80% similarity are candidates for removal.
--tree-dir <dir>./trees/<game>/Tree library directory

Example

# Trim tipo trees with default threshold
swarmtest trim --game tipo

# Aggressive trimming (remove trees with &gt;60% similarity)
swarmtest trim --game tipo --threshold 0.4

# Trim from a custom directory
swarmtest trim --game tipo --tree-dir ./backup-trees/tipo/

When two trees are similar, the trimmer keeps the one with more findings. Ties are broken by source priority: handwritten > recorded > llm.

swarmtest list-trees

List all saved regression trees in the library.

swarmtest list-trees --game &lt;game&gt; [options]

Options

OptionDefaultDescription
--game <game>(required)Game name (tipo, playertwo)
--tree-dir <dir>./trees/<game>/Tree library directory

Example

swarmtest list-trees --game tipo

Output:

2 trees in ./trees/tipo/:

  tree-1771647225060-tgbfcs
    Source: recorded | Created: 2026-02-21T04:13:45.060Z
    Tags: crash, desync
    Findings: 3
    Hash: 8f2a1b

  tree-1771647265849-6h2srx
    Source: llm | Created: 2026-02-21T04:14:25.849Z
    Tags: protocol
    Findings: 1
    Hash: c4e7d3
Built with Ptero