Skip to content
Beetl

Getting Started

Install

Section titled “Install”

Beetl is pre-release and not yet published to npm. Once it is, install will be:

Terminal window
npm install -g beetl

Until then, work from the source repo and link the built CLI onto your PATH:

Terminal window
pnpm install && pnpm build
cd packages/cli && npm link   # `beetl` now runs the local build

(Or invoke it directly: node packages/cli/dist/index.mjs.)

Initialize a repo

Section titled “Initialize a repo”
Terminal window
beetl init

Creates a .beetl/ directory in your repo and writes config. Interactive prompts cover the privacy mode, config format, and the opt-in global layer; --yes accepts defaults (JSON config, committed mode, global layer off). --private sets up a local-only store. Your identity is established from git config.

The core loop

Section titled “The core loop”

File a bug as a session, then walk it through the lifecycle:

Terminal window
beetl new                          # file a bug session (interactive on a TTY)
beetl list                         # see open sessions
beetl checklist BTL-20260723-a4f2  # what's missing before the next phase

Sessions move reported → reproducing → diagnosing → fixing → verifying → resolved. Each transition is gated on the evidence that phase should produce — symptoms, a reproduction reliability (which may be not-reproduced with a stated reason), a root cause with implicated files, a fix summary and approach, and tests (or an explicit, logged no-test reason). Advance with move, supplying gate fields as flags:

Terminal window
beetl move a4f2 reproducing --symptoms "..." --reliability always
beetl move a4f2 diagnosing
beetl move a4f2 fixing --root-cause "..." --files src/foo.ts
beetl move a4f2 verifying --fix-summary "..." --approach "..."
beetl resolve a4f2 --tests "..."

move chains through intermediate statuses when the gates are satisfied, and beetl resolve <ref> is shorthand for moving all the way to resolved. Sessions that will never be fixed close terminally:

Terminal window
beetl close a4f2 --as wontfix --reason "..."

Sessions can be referenced by canonical ID (BTL-20260723-a4f2), a unique fragment (a4f2), or display ordinal (#3).

Before debugging something new, check whether it has happened before:

Terminal window
beetl search "flaky websocket reconnect"

Agent setup

Section titled “Agent setup”
Terminal window
beetl agent install

Writes the Beetl Claude Code skill and auto-file hook into the host project’s .claude/ directory — so agents search past sessions before debugging and file sessions for the bugs they find. Pass --claude-md to also append a two-line pointer to CLAUDE.md (opt-in, not automatic).

Agents are first-class clients: every command supports --json (a snapshot-tested output contract) and agents identify themselves with --actor agent:<tool>:<model> on every command.

Next steps

Section titled “Next steps”
  • CLI reference — every command at a glance.
  • Subsystem pages in the sidebar — store layout, lifecycle gates, patterns, privacy, and more.