Bug memory that lives in your repo

The bug you’re fixing today, someone already fixed

Bug knowledge evaporates. It lives in a closed ticket on a server you no longer use, in a Slack thread nobody can find, or in a teammate’s head. Six months later the same class of bug resurfaces and the investigation starts from zero.

Beetl keeps that knowledge where the code is — committed alongside it. Clone the repo, get the full bug history. No external service, no account, no integration to wire up. Just JSON files your team already trusts to review.

Bug sessions, not tickets

A session moves through a gated lifecycle — reported, reproducing, diagnosing, fixing, verifying, resolved — and each transition requires the evidence that makes the history useful later. No more resolved bugs with an empty root-cause field.

Lives in your repo

Sessions are JSON under a committed .beetl/ directory, date-partitioned and append-only. Version-controlled, reviewable in a PR, and offline by default. Clone the repo, get the bug history.

Agents are first-class

Every command supports --json with a snapshot-tested output contract, so AI agents are real clients, not an afterthought. beetl agent install wires the Claude Code skill and auto-file hook into a host project.

Patterns over time

beetl patterns mines the store for hotspot files, refix chains, category clustering, and failure tempo — pointing at the root causes behind the symptoms, with optional LLM-synthesized reports.

How it works

Every bug is a session that walks a lifecycle, gated so the record is actually complete when it closes:

1. Report
2. Reproduce
3. Diagnose
4. Fix
5. Verify
6. Resolve

Each transition demands the evidence that phase should produce — symptoms, a reproduction reliability, a root cause with the files it implicates, a fix summary, and verification. The result is a bug history you can mine, not just read.

beetl new                          # file a bug session
beetl list                         # see what's open
beetl checklist BTL-20260723-a4f2  # what's missing before the next phase
beetl resolve BTL-20260723-a4f2    # close it out with the evidence gate
beetl patterns                     # what keeps breaking, and where

Built for humans and agents together

Beetl is designed so a developer and an AI coding agent work the same store. Humans get a clean terminal UI; agents get a stable --json contract and a drop-in Claude Code skill. Every write is attributed to an actor (human:username or agent:tool:model), so you always know who — or what — touched a session.

Get started →Install Beetl, initialize a repo, and run the core bug-session loop in a couple of minutes.

CLI referenceEvery command, flag, and exit code — including the --json agent contract.