Skip to content
Beetl

FAQ

What is Beetl, in one sentence?

Section titled “What is Beetl, in one sentence?”

Repo-local bug memory: every bug becomes a structured session — report → reproduce → diagnose → fix → verify → resolve — stored as JSON in a committed .beetl/ directory and mined over time for root-cause patterns.

How is a bug session different from a GitHub issue or ticket?

Section titled “How is a bug session different from a GitHub issue or ticket?”

A ticket is free-form and lives outside your code, on a service you may not control. A Beetl session is structured and gated: it can’t reach resolved without the evidence that phase should produce — symptoms, a reproduction reliability, a root cause with the files it implicates, a fix summary, and verification. And it lives in the repo, so the history travels with the code and is reviewable in a pull request.

Where is the data stored? Is it really committed?

Section titled “Where is the data stored? Is it really committed?”

Yes. Sessions are JSON files under a .beetl/ directory in your repository, date-partitioned (.beetl/sessions/YYYY/MM/) and append-only. Clone the repo, get the full bug history. There’s no external database and nothing to sync.

Do I need a server, account, or network connection?

Section titled “Do I need a server, account, or network connection?”

No. Beetl is a local CLI that reads and writes files in your repo. It works offline and stores nothing off your machine. (An optional cross-repo “global layer” can aggregate patterns across your repos locally — it’s off by default.)

Can I keep some bugs private / out of version control?

Section titled “Can I keep some bugs private / out of version control?”

Yes. beetl init --private sets up a local-only store, and individual sessions can be kept out of the committed set. A privacy-scrub layer also guards against secrets leaking into session content. See the Configuration reference for details.

How do AI agents use Beetl?

Section titled “How do AI agents use Beetl?”

Agents are first-class clients. Every command supports --json with a snapshot-tested output contract, so an agent can drive the full lifecycle programmatically. beetl agent install wires the Claude Code skill and an auto-file hook into a host project. Every write is attributed to an actor — human:username or agent:tool:model — so you always know who, or what, touched a session.

What is the --json contract?

Section titled “What is the --json contract?”

--json output is the machine interface, and it’s snapshot-tested — changing its shape is treated as a semver-major break. Errors are emitted as a single JSON object on stderr; stdout is reserved for success payloads. Build on it with confidence.

What are “patterns”?

Section titled “What are “patterns”?”

beetl patterns mines the store for signal across sessions: hotspot files that keep breaking, refix chains (bugs fixed more than once), category clustering, and failure tempo. It can optionally synthesize an LLM-written root-cause report. The point is to surface why things break, not just log that they did.

What are the lifecycle stages and gates?

Section titled “What are the lifecycle stages and gates?”

Sessions move reported → reproducing → diagnosing → fixing → verifying → resolved. Each transition is gated on the evidence that phase produces. A bug can also be closed as wontfix, duplicate, or cannot-reproduce. Run beetl checklist <ref> to see exactly what’s missing before the next phase.

What Node version do I need?

Section titled “What Node version do I need?”

Node.js ≥ 22.12.0.

Is Beetl on npm yet?

Section titled “Is Beetl on npm yet?”

Not yet — Beetl is pre-release and under active development. Until it’s published, build from the source repo and link the CLI onto your PATH (see Getting Started).

Where do I go next?

Section titled “Where do I go next?”