Skip to main content
This guide runs a small, deterministic agent against one synthetic Tool. You will validate the repository source, execute a passing drill, and open a self-contained report.

​
Prerequisites

  • Node.js 20.19 or later
  • pnpm 9.15 through 10
  • Git
Public package installation is not available yet. These steps build the current release candidate from source, which currently requires repository access. Once the repository and packages are public, the normal path will be npm install --save-dev @firedrill/cli and npx firedrill init.
1

Build the release candidate

The shell function keeps the built CLI available while you work through this guide.
2

Create a runnable example

From the Firedrill checkout:
The template creates a Tool, baseline data, one target, and one drill. Generated runtime data and reports go under .firedrill/, which the initializer adds to .gitignore.
3

Check what will run

validate checks the source without writing a build. plan shows the semantic world that Firedrill would compile.
4

Run the drill

Firedrill creates an isolated SQLite-backed world, starts the Tool interfaces, invokes the example target, evaluates the assertions, and writes terminal, JSON, JSONL, JUnit, and HTML results.
5

Open the results

Use the inspector to move between Tools, starting data, drill definitions, runs, assertions, state changes, and attachments. You can also open .firedrill/reports/index.html directly for a static report index that needs no server.

​
Read the project

The files under firedrill/ describe the controlled environment and its tests. The agent remains separate. YAML, YML, and JSON resource files are supported, and Firedrill discovers them recursively beneath the configured source root.

​
Connect your own agent

Replace the example target with one boundary your agent already exposes: Then map the synthetic Tool connection into the configuration that your agent already reads. Firedrill supports direct, HTTP, MCP, and spawned CLI Tool bindings.
Firedrill cannot transparently intercept every hardcoded dependency. Keep production logic unchanged, but provide a configurable endpoint, client factory, module mock, or another test-side seam.

​
Make the result fail on purpose

Open firedrill/drills/changes-resource.drill.yaml. Change only one assertion’s expected value while leaving the task input unchanged, then rerun:
The command exits with code 1, and the report shows expected and actual values together. Restore the assertion when you finish reviewing the failure.

​
Next steps

Connect an existing agent

Choose the correct target and Tool-binding seam.

Build a Tool

Define operations, state, behavior, faults, events, and an optional UI.

Use your test runner

Call runDrills() from Jest, Vitest, Mocha, or application tests.

Understand reports

Read verdicts, causal evidence, state differences, and reproduction data.