Dungbeetle

The regression safety net for AI agents and the humans they work for — web, desktop, terminal, anything. Zero adoption cost, runs anywhere.

Status

🚧 Closed beta. We are busy with some testing. The CLI in this package works fully standalone; access to the hosted Dungbeetle cloud is by request — you can request access and we'll notify you by email when it's ready.

Dungbeetle is a snapshot and visual regression testing tool — a free CLI plus a self-hostable cloud — built for AI agents and the humans they work for. It captures your app's output as stable, reviewable JSON and produces semantic diffs instead of brittle pixel comparisons. Output is normalized (timestamps, UUIDs, and temp paths are masked) so baselines stay readable and survive cosmetic churn.

• 🖥️ Terminal — capture with ANSI normalization
• 🌐 Web — structured DOM snapshots (url/html fetch by default, or a playwright driver when a browser is available)
• ⚡ Performance — baselines from k6 metrics, compared with numeric tolerance
• 🪟 Desktop — accessibility-tree snapshots (role/name/state), with an experimental native macOS driver (driver: "macos-ax")
• 🔌 API — REST/GraphQL response snapshots (status, allow-listed headers, parsed JSON body) with structural diffs
• 🎮 Game — scripted walkthroughs snapshotting semantic game state at named markers, deterministic and headless (Godot 4.x first; see adapters/godot)
• 🎭 Shared masking for dynamic values, and stable JSON diffs you can review in a pull request

Baselines are committed under dungbeetle.snapshots/ so changes show up in code review. An optional Dungbeetle cloud service (a separate product) can store runs and baselines centrally when you'd rather not commit them.

📚 Documentation

Full documentation — guides, capture types, configuration, and the CLI reference — lives at the Dungbeetle docs site:

→ https://dungbeetle.dev

🤖 For AI agents

Dungbeetle treats agents as first-class users: the docs are fetchable as raw markdown (https://dungbeetle.dev/llms.txt, or any docs URL + .md), the review workflow is reachable over MCP, and agents authenticate with scoped, revocable tokens a human approves — see Docs for agents.

To make your coding agent use Dungbeetle in a repository, paste this into your AGENTS.md (or CLAUDE.md):

## Visual regression testing

This project uses Dungbeetle (https://dungbeetle.dev/llms.txt) for snapshot
and visual regression testing.

- Before committing UI changes, run `npx dungbeetle test`. It exits non-zero
  if anything visual changed.
- If a change is intentional, run `npx dungbeetle update` and commit the
  updated `dungbeetle.snapshots/` files together with your change.
- Never edit files under `dungbeetle.snapshots/` by hand.
- Config lives in `dungbeetle.config.json`
  (schema: https://dungbeetle.dev/configuration/schema.md).

Requirements

• Node.js 22.5.0 or newer.
• No native build step and no external services for the CLI.

Installation

npm install -g dungbeetle   # global `dungbeetle` binary
# or, per-project:
npm install --save-dev dungbeetle && npx dungbeetle --help

Quick start

Scaffold a config, then add at least one capture target — init writes an empty lifecycle.capture array (unless it detects a Laravel app), so you tell Dungbeetle what to snapshot:

dungbeetle init     # scaffold dungbeetle.config.json

Add a target to lifecycle.capture in dungbeetle.config.json — here a minimal terminal snapshot (see the docs for web, desktop, game, API, and check targets):

{
  "lifecycle": {
    "capture": [{ "kind": "terminal", "name": "hello", "command": "echo hello world" }]
  }
}

Then capture and compare:

dungbeetle update   # run your capture targets and write the first baselines
dungbeetle test     # compare current output against the baselines

update writes baselines under dungbeetle.snapshots/ (commit these). test compares current output to them and exits non-zero on any difference, so it drops straight into CI. Run dungbeetle doctor any time to check your config and targets. For machine-readable CI output:

dungbeetle ci --json report.json --html report.html

Run dungbeetle doctor to validate your config, paths, targets, and optional browser setup. See the documentation for the next steps.

Dungbeetle cloud

An optional Dungbeetle cloud service stores runs and baselines centrally with a review/approve UI — useful when you'd rather not commit baselines to your repo. It is a separate product (not part of this repository); see https://dungbeetle.dev for details. Production self-hosting is available to enterprise customers on request.

Contributing

npm install
npm run check           # lint + typecheck + test (run before a PR)
git commit -s           # sign off your commits (DCO — required)

We welcome contributions! Please read CONTRIBUTING.md (it covers the DCO sign-off every commit needs) and our Code of Conduct. Questions go to Discussions; bugs and features to Issues; security reports to SECURITY.md. See also SUPPORT.md and GOVERNANCE.md.

License

Dungbeetle's CLI & core engine (dungbeetle, this repository) is source-available under the Functional Source License 1.1 (LICENSE) — free for any use, including internal and commercial, except offering it to others as a competing product or service; each release converts to Apache-2.0 two years later.

The Dungbeetle cloud server is a separate product under the Business Source License 1.1 and lives in its own repository.

See LICENSING.md for the rationale and TRADEMARK.md for the brand-use policy. "Dungbeetle" and the Dungbeetle logo are trademarks of DungbeetleDev.