Configuring swarmtest

swarmtest is configured primarily through CLI flags passed to the swarmtest run command. For programmatic use, the SwarmConfig interface provides the same options.

Behavior Mix

The most important configuration is the behavior mix, which controls what proportion of agents use each behavior source:

Override the mix with CLI flags:

# Only run saved regression trees
swarmtest run --game tipo --url ws://localhost:5001 --regression-only

# Only generate fresh LLM trees (exploration mode)
swarmtest run --game tipo --url ws://localhost:5001 --explore-only

# Disable LLM entirely (50% regression, 50% handwritten)
swarmtest run --game tipo --url ws://localhost:5001 --no-llm

Agent Count and Timing

swarmtest run --game tipo --url ws://localhost:5001 \
  --agents 20 \
  --duration 120 \
  --tick 100 \
  --stagger 200

• --agents (default: 10) – Number of concurrent agents to spawn
• --duration (default: 60) – Test duration in seconds
• --tick (default: 100) – Milliseconds between behavior tree ticks per agent
• --stagger (default: 200) – Milliseconds between each agent’s connection to avoid thundering herd

Tree Library

Behavior trees that trigger meaningful findings (crash, bug, or jank severity) are automatically saved to disk. By default, trees are stored in ./trees/<game>/.

# Use a custom tree directory
swarmtest run --game tipo --url ws://localhost:5001 --tree-dir ./my-trees/tipo/

# Skip post-run tree trimming
swarmtest run --game tipo --url ws://localhost:5001 --no-trim

After each run, swarmtest trims similar trees from the library using normalized Levenshtein edit distance. Trees with more than 80% similarity are deduplicated, preferring to keep trees with more findings and higher source priority (handwritten > recorded > llm).

LLM Configuration

When LLM generation is enabled (the default), swarmtest uses the Anthropic SDK to generate behavior trees. The default model is claude-haiku-4-5-20251001.

Set the API key via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

During a run, LLM regeneration happens periodically (every 30 seconds by default). A random 10% of playing agents may receive a fresh behavior tree from Claude at each regeneration interval.

Reporting

By default, swarmtest prints a console report. Add --json to also write a JSON report to ./reports/:

swarmtest run --game tipo --url ws://localhost:5001 --json

The JSON report contains the full SwarmSummary object, including per-agent statistics and all findings.

Programmatic Configuration

When using swarmtest as a library, pass a SwarmConfig object:

import { Swarm } from 'swarmtest';
import { TipoAdapter } from 'swarmtest/adapters/tipo/TipoAdapter';

const swarm = new Swarm();
await swarm.run({
  serverUrl: 'ws://localhost:5001',
  agentCount: 20,
  adapter: new TipoAdapter(),
  tickIntervalMs: 100,
  connectStaggerMs: 200,
  durationMs: 120_000,
  behaviorMix: { regression: 40, llmGenerated: 40, handwritten: 20 },
  llm: { regenerateIntervalMs: 30_000 },
  trimAfterRun: true,
});