A real-time, non-invasive tracker for agents. A Burnlist stores work in a repo-local, shrinking Markdown checklist and renders progress in a local observer dashboard. Burnlist owns task state, not implementation, testing, or delivery.
Burnlist requires Node.js 18 or newer.
npm install --global burnlistThe global package installs the burnlist command and registers the bundled Burnlist skill for Claude Code under ~/.claude/skills and Codex under ~/.agents/skills. Streaming Diff hooks are a separate, opt-in per-repository integration; see Agent integrations.
Ask your agent to create a Burnlist for a goal or continue an existing one. The skill owns that workflow; the CLI provides the dashboard and protocol helpers.
Run the dashboard from any project:
burnlistThe server binds to loopback by default and prints its local URL.
A Burnlist moves through a repo-local lifecycle:
notes/burnlists/
draft/<id>/
ready/<id>/
inprogress/<id>/
completed/<id>/
burnlist.md is the canonical shrinking queue. goal.md holds the stable contract, and completed.md can hold optional human-readable history. Ready work moves to inprogress before execution and to completed after the active queue is empty.
An active item is completed and validated before it leaves the checklist. The agent appends a terse completion record, deletes the active item, then validates the updated Burnlist. The lifecycle folder and burnlist.md remain the source of truth.
One skill owns Burnlist creation, hardening, execution, and maintenance. The project owns implementation and verification.
The dashboard scans lifecycle folders and refreshes automatically. Its progress views observe Burnlists without changing them. New Oven and Run Burn write local controller records under .local/burnlist/ by default; they do not change canonical task state.
An Oven is a declarative recipe for a Burn. Its instructions.md defines the outcome, canonical state, required inputs, and evidence rules. Its <id>.oven source declares controlled widgets and bindings used to present normalized data.
Official Oven membership is defined only by the validated, non-executable ovens/catalog.json. The catalog records each shipped definition's producer input contract, declarative render contract, route kind, maturity, and runtime compatibility. GET /api/oven-catalog exposes that official set; GET /api/ovens separately reports the official, vendored, and custom Ovens available to the observed repositories. The catalog makes no acceptance or retained-evidence claim.
Custom Ovens use the same two-file package and are scoped to the repository that owns their ignored local state; shipped official Ovens are package-wide and read-only. An Oven cannot run commands, collect or transform project data, mutate project files, import arbitrary UI, or start an agent. --ovens-dir overrides custom Oven storage only for the dashboard's launch repository, while other observed repositories continue to use their own .local/burnlist/ovens/. See the Oven contract for the complete boundary.
Projects publish a read-only comparison using burnlist-differential-testing-data@1. Small comparisons may bind that document directly. Large comparisons use the canonical burnlist-differential-testing-bundle@1 transport so Burnlist validates field records sequentially and range-reads only the visible page. The project owns capture, exact-first execution, normalization, and atomic publication.
burnlist differential-testing schema
burnlist differential-testing validate /absolute/path/to/bundle/current.json
burnlist differential-testing validate-bundle /absolute/path/to/bundle/current.json
burnlist --oven-data differential-testing=/absolute/path/to/bundle/current.jsonAggregate refresh results remain telemetry. In exact-first mode, retained exact-prefix verification is the only retention authority.
Projects that need worker orchestration can import createDifferentialTestingWorker from burnlist/differential-testing. Public payload validation, digest, and telemetry helpers are available from burnlist/differential-testing/contract; scalable bundle validation and page queries are available from burnlist/differential-testing/transport. The SDK owns generic queueing and recovery, not project evidence authority. Run burnlist differential-testing sdk to print the packaged worker module path.
See the Differential Testing data contract and adapter SDK reference for scenario bundles, exact sessions, telemetry, and worker interfaces.
Burnlist has two independent systems. You can install the skill without hooks, hooks without the skill, or both.
burnlist install registers the bundled skill for both Claude Code and Codex. Its default scope is the current repository and creates managed, untracked-local skill registrations via .git/info/exclude:
| Agent | Per-repository target | Global target (--global) |
|---|---|---|
| Claude Code | <repo>/.claude/skills/burnlist |
~/.claude/skills/burnlist |
| Codex | <repo>/.agents/skills/burnlist |
~/.agents/skills/burnlist |
# Per-repository skill only (both agents by default)
burnlist install
# Limit to one agent, or preview without writing
burnlist install --agent codex
burnlist install --dry-run
# Global skill only
burnlist install --global
# Portable per-repository copy that the team can commit
burnlist install --commit
# Remove the matching per-repository or global registration
burnlist uninstall
burnlist uninstall --global
# Also remove the global npm package (global scope only)
burnlist uninstall --global --purge--agent codex,claude restricts either install or uninstall to the selected agents. --commit is per-repository only; it makes a portable copy instead of the default local registration.
burnlist hooks install is separate from skill installation. It is per-repository only (there is no global hooks mode) and merges Burnlist's edit-capture commands without replacing unrelated hooks:
| Agent that consumes the hook | Worktree-root config |
|---|---|
| Codex | <repo>/.codex/hooks.json |
| Claude Code | <repo>/.claude/settings.json |
Codex receives SessionStart, PreToolUse, and PostToolUse hooks; Claude Code also receives PostToolUseFailure. Edit events are limited to each agent's edit/write tools and invoke burnlist streaming-diff hook. Codex needs CLI version 0.124.0 or newer to run these hooks. The host needs burnlist on PATH, and the agent remains responsible for any hook trust or consent prompt.
# Hooks only, for both agents by default
burnlist hooks install
# Limit to one agent; --untracked requests a local exclude entry
burnlist hooks install --agent claude
burnlist hooks install --untracked
# Inspect or remove Burnlist-managed hooks
burnlist hooks status
burnlist hooks uninstall
# Install or remove both independent per-repository systems
burnlist install && burnlist hooks install
burnlist uninstall && burnlist hooks uninstall
# A global skill can be combined with hooks in the current repository
burnlist install --global && burnlist hooks installUntracked hook configs are added to .git/info/exclude by default; tracked configs remain shared with the team, and --untracked cannot hide one. burnlist hooks uninstall removes only Burnlist's own hook entries and preserves the rest of the config. See the installation reference for the full CLI surface.
burnlist --plan <burnlist.md> --checkvalidates the active queue and completed ledger.burnlist --plan <burnlist.md> --digestprints a completion digest after the active queue is empty.burnlist --close-completedadds a digest when needed and moves empty in-progress Burnlists tocompleted.burnlist --stampprints a local ISO timestamp for completion records.burnlist install/burnlist uninstallmanage the independent agent-skill registrations.burnlist hooks install|uninstall|statusmanages the independent per-repository Streaming Diff hooks.
Use burnlist --help for dashboard ports, scan roots, local state paths, and Oven data bindings.
From a source checkout:
Burnlist's CLI, server, and dashboard support Node.js 18 or newer. The Storybook 10 development commands require Node.js 20.19+ or 22.12+.
npm install
npm run build:dashboard
npm run storybook
npm run build:storybook
npm run test:differential-testing
npm run verify
npm run verify:clean
npm run verify:package
npm run test:global-installverify:clean checks the source, npm payload, and isolated global install from a temporary copy.
burnlist/oven-events exposes a durable, repo-local observational event log.
After atomically publishing canonical Oven data, producers may call
publishOvenDataPublishedEvent with a stable subject and durable publication
generation. Consumers use data-published/complete only to invalidate and refetch
canonical data; events never contain or replace the snapshot or its proof. The
dashboard serves bounded JSON replay and SSE at GET /api/events.
Every live Oven uses the same canonical architecture: one process-wide event
observer, one bounded JSON snapshot service, one browser-shell snapshot client,
and the declarative OvenRuntime. A publication burst invalidates a keyed
snapshot; the next conditional request reopens canonical data. There are no
handler warm hooks, page-owned JSON pollers, or alternate live Oven routes.
Exact browser consumers use filter-scoped replay cursors. Wildcard projections
use a live server-tail subscription with internal paged watermarks, so they keep
all-Oven invalidation semantics beyond the public 64-stream replay boundary.
Differential Testing uses the same source snapshot and response-admission
boundary, retaining only a bounded query-projection LRU. Inactive browser
snapshots are bounded by entry and byte limits; transient failures visibly mark
retained data stale, while authoritative missing responses clear it.
One 30-second server reconciliation and one 30-second browser reconciliation
cover manual writes, event-publication failure, and disconnects. Streaming
Diff remains a separate ordered content SSE protocol, and Performance Tracing
deliberately revalidates external provenance on each canonical request.
Run node scripts/measure-oven-snapshot-architecture.mjs to reproduce the
empirical architecture measurement. It uses real wall-clock timers, loopback
HTTP, filesystem reads/parses, three SSE clients, and a spawned dashboard
server—never fake timers or arithmetic request counts. The retained run reduced
two executable legacy polls to zero inside a 4.2-second canonical idle window,
reduced a three-consumer publication burst from three reads/parses/responses to
one, shared two subscriber catch-up scans across three SSE clients instead of
six per-client scans, returned an unchanged generation as a zero-byte 304,
and rejected a second 4 MiB maximum response until abort released admission.
Burnlist state stays local by default. Task files live under notes/burnlists/; dashboard observer state, custom Ovens, and Run snapshots live under .local/burnlist/. Keep both paths ignored unless you deliberately want to share task state.
Burnlist is licensed under the MIT License.