# Getting Started with Burr

Burr is a local debugging memory for coding agents.

It runs completely offline with **zero cloud dependencies**, **zero external telemetry**, and **zero mandatory API keys**.

---

## 1. Installation

Requires **Node.js 22.12+**.

### Machine-Wide (Recommended)

Install user-level skills and supported hooks. Cursor and Windsurf need project setup; Pi runtime needs its package extension:

```bash
npm install -g burr-memory@latest
burr global
```

### Single Repository

Enable Burr only in the current project:

```bash
npm install -D burr-memory@latest
npm exec -- burr init
```

---

## 2. Supported Coding Agents

Burr generates owned integration files for supported agents:

### Claude Code

Burr generates slash commands under `.claude/skills/`:

- `/burr`: Show debugging memory status and mode
- `/burr-search`: Search memory before guessing fixes
- `/burr-resolve`: Store a verified playbook after solving an issue
- `/burr-capture`: Save a reusable error signal
- `/burr-audit`: Inspect usage ledger

### OpenAI Codex

Burr generates skill definitions under `.agents/skills/`:

- `@burr-search`
- `@burr-resolve`
- `@burr-help`

`burr init` and `burr global` also register native session and tool hooks. Review new hooks once in Codex `/hooks`. Hosted tools such as web search do not emit local tool hooks.

### Cursor & Windsurf

Burr generates persistent editor rules:

- `.cursor/rules/burr.mdc`
- `.windsurf/rules/burr.md`

Run `burr init` in each project for these editors. `burr global` does not activate Cursor or Windsurf rules machine-wide; configure their global instruction settings manually if needed.

### OpenCode & Pi

- `.opencode/plugins/burr.mjs`
- `pi-extension/index.ts`

With Pi installed, register Burr through Pi's package system:

```bash
pi install npm:burr-memory@latest
```

Start a new Pi session after installation. For a built local checkout, use `pi install ./path-to-burr` instead. Pi runtime events require this package extension; `burr init` copies Pi skills but does not install the extension.

---

## 3. CLI Command Reference

| Command                      | Purpose                                                  |
| :--------------------------- | :------------------------------------------------------- |
| `burr global`                | Install supported user-level integrations                |
| `burr init`                  | Initialize Burr in the current project                   |
| `burr stats`                 | View memory counts, reuse rates, and loop detections     |
| `burr compare <runA> <runB>` | Compare metrics between two runs side-by-side            |
| `burr memory list`           | List active, stale, and archived memories                |
| `burr memory inspect <id>`   | View details and evidence for a specific memory          |
| `burr memory prune`          | Apply confidence decay and clean expired sessions        |
| `burr doctor`                | Report memory directory health and storage counts        |
| `burr dashboard`             | Launch the local web dashboard (`http://127.0.0.1:4747`) |

---

## 4. Programmatic TypeScript Library

You can also import Burr directly into custom agent frameworks:

```ts
import { LoopDetector } from "burr-memory/api";

const detector = new LoopDetector({ autoRecord: false });
const args = { cmd: "npm test" };
const check = detector.evaluateAction("run_command", args);
if (check.blocked) {
  console.warn(check.reasons, check.suggestedAction);
} else {
  // Execute your tool; record its actual output and status.
  detector.recordAction("run_command", args, "12 passed", "completed");
}
```

Custom SDK integrations must wire the lifecycle functions, supply verification evidence, and enforce loop decisions. Codex native hooks and the shipped OpenCode and Pi adapters provide host wiring; rules-only hosts do not intercept tool calls.

## Compatibility evidence

Checked on 3 October 2026:

| Host               | Evidence                                                                        | Boundary                                            |
| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------- |
| Codex 0.160.0      | Native sandboxed command observation and denial                                 | Hosted tools may not emit local hooks               |
| Pi 0.80.10 / 1.0.0 | Native loader and extension lifecycle: injection, recording, blocking, off mode | Not a paid-model session                            |
| OpenCode 1.18.34   | Native project/global plugin discovery; separate callback regression tests      | Not a complete live-model session                   |
| Claude Code        | Generated skill files and preservation tests                                    | Instruction workflow; actual app session not tested |
| Cursor / Windsurf  | Generated project rules and preservation tests                                  | Instruction workflow; actual apps not tested        |

Other agents can call the CLI or use the Node API with explicit integration. Burr does not supply a universal interceptor, MCP server, hosted memory service, accounts, or team permissions. Installation does not prove an agent follows instructions.

## Updating and checking the integration

Re-run the installation command with `@latest`, then run `burr global` or the
project's installed `burr init` to refresh managed integration files. Restart or
reload the host. Review new Codex hooks in `/hooks`; Pi must load its installed
package extension. User-edited integration files are preserved, so inspect any
reported conflicts instead of overwriting them blindly.

`burr doctor` checks local storage health. It does not prove that a host loaded
Burr. Run a tool through a runtime-enabled adapter and inspect `burr stats` or
`burr dashboard` for the recorded run. Skills-only hosts need to invoke Burr's
commands explicitly. Updates do not happen automatically.