Docs for agents

This page lists every machine-readable surface dungbeetle.dev exposes for AI agents, coding assistants, and bots. Dungbeetle treats agents as first-class users: the docs are fetchable as raw markdown, the API is specified in OpenAPI, the review workflow is reachable over MCP, and agents authenticate with scoped tokens a human approves — never a copy-pasted secret.

Machine surfaces

Surface	URL	What it is
Docs index for LLMs	/llms.txt	Curated, annotated index of the docs — each link points at a raw-markdown page
Full docs, one file	/llms-full.txt	The entire documentation concatenated as a single markdown file
Markdown docs pages	any docs URL + .md	Raw-markdown twin of every page, e.g. /guide/quick-start.md
OpenAPI spec	/openapi.yaml	OpenAPI 3.1 description of the HTTP API
Agent skill	/.well-known/skills/default/skill.md	Installable task recipe (npx skills add dungbeetle.dev)
MCP server	dungbeetle-mcp	Triage runs, read diffs, review — from Claude Code, Cursor, Codex, Gemini CLI
Crawl policy	/robots.txt	AI crawlers and fetchers are deliberately allowed

Read the docs as markdown

Every docs page serves a raw-markdown twin at the same URL plus .md — a fraction of the tokens of the HTML page. Clients that send Accept: text/markdown (Claude Code, Cursor, OpenCode) get markdown from the clean URL directly:

curl https://dungbeetle.dev/guide/quick-start.md
curl -H "Accept: text/markdown" https://dungbeetle.dev/guide/quick-start

Directory-style URLs work too: /mcp/ twins at /mcp/index.md.

Authenticate as an agent

Agents never receive an account password or a copy-pasted secret. The CLI's device flow prints a one-time code that a human approves in the browser; the agent receives a scoped, revocable dbat_ token:

dungbeetle login --label "My agent"

The default Triage preset can read runs, baselines, and analytics and write reviews — but promoting a baseline requires the separate baselines:write scope. That click deliberately stays with a human unless one explicitly grants it. Actions are attributed as "<label> (agent, on behalf of <owner>)", and tokens are revocable at any time from the dashboard.

Set up visual regression testing (deterministic quickstart)

npm i -g dungbeetle    # or: npx dungbeetle <command>
dungbeetle init        # scaffolds dungbeetle.config.json — add capture targets
dungbeetle update      # captures targets, writes baselines to dungbeetle.snapshots/
dungbeetle test        # re-captures and compares; exits non-zero on any diff

Expected behavior on first run: dungbeetle test fails with missing results until dungbeetle update has created baselines — that is not an error in your setup. Report statuses are updated, passed, failed, missing, and error. Commit dungbeetle.snapshots/. Configuration schema: /configuration/schema.

Tell your agent about Dungbeetle (AGENTS.md snippet)

The most reliable way to make any coding agent use Dungbeetle in a repository is an explicit instruction in the repo. 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).

MCP

The MCP server lets agents list runs, read low-token semantic diffs, and record reviews without leaving their tool loop. Per-client setup: Claude Code, Cursor, Codex, Gemini CLI.

Self-hosted servers

Everything above ships with the server: a self-hosted Dungbeetle exposes the same surfaces on its own origin. Point the CLI and MCP server at it with --server <url> / DUNGBEETLE_SERVER_URL.