Burnlist

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.

Installation

Burnlist requires Node.js 18 or newer.

npm install --global burnlist

The global package installs the burnlist command and registers the bundled Burnlist skill for Claude Code under ~/.claude/skills and Codex under ~/.agents/skills. Native observability 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.

From any repository, the intended first interaction is simply:

Set up Burnlist in this repo.

The globally installed skill initializes and registers the repository, briefly explains the workflow, and asks what you want to burn.

Run the dashboard from any project:

burnlist

The server binds to loopback by default and prints its local URL. A global installation starts one persistent shared observer and burnlist prints its discovered URL; burnlist service start|stop|restart|status exposes its lifecycle. Use burnlist serve for an explicitly foreground server.

How It Works

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 optional top-level Default Oven: <oven-id> line selects the first detail view opened from both the Web dashboard and burnlist -i. If it is absent, or the named Oven is unavailable, both surfaces open Checklist. The setting only chooses the landing lens; it does not change canonical progress or prevent switching to another compatible Oven.

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.

Operational contract

Start with the thinnest working end-to-end path, prove it, then refine—unless the repository or user has already chosen another architecture. Burnlist coordinates task, execution, proof, and observation contracts; it does not dictate project structure.

Per-item control recommendations are optional:

burnlist recommend <id>#<item>
burnlist recommend <id>#<item> --json

They suggest the lightest fitting direct/gate/review/branch workflow, a provider-neutral model class and effort, P0-P4 review handling, and an honest metric or task-fit Oven when one adds value. The user remains authoritative.

The Checklist labels items PENDING, ACTIVE, WAITING, BLOCKED, or COMPLETED from canonical Burnlist and Run/claim state—never checklist position. Recent correlated hooks may only refine an active item to progressing and show bounded observational facts. The Loop Progress lens separates canonical checks/gates/reviews and blockers from observational agent/model/effort, file activity, timing, usage, and bounded forecasts. Missing facts stay unavailable.

Creation, registration, assignment, and Oven commands print the next useful action and canonical dashboard URL. See the operational UX contract for coarse-to-fine guidance, P0-P4 policy, provenance, optimization measures, and the required browser inspection of every task-fit Oven.

Ovens

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.

Differential Testing

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.json

Aggregate 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.

Agent integrations

Burnlist has two independent systems. You can install the skill without hooks, hooks without the skill, or both.

Skills: make Burnlist discoverable

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.

Hooks: capture Streaming Diff edits

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 and Loop observation 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 and Claude receive native session, subagent, tool, and stop lifecycle hooks; Claude also receives PostToolUseFailure. Edit events remain limited to each agent's edit/write tools and invoke burnlist streaming-diff hook. Advisory burnlist hooks observe entries publish bounded, correlated Loop activity through ignored local event state without reporting outcomes or changing canonical Run state. A native PreToolUse for an exact burnlist loop next|claim command prepares a short-lived session/tool/Run tuple; the matching PostToolUse binds it only after that Run's claim is durable. An unmatched native session stays unbound, and Burnlist never assigns the only live claim by process-of-elimination. 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 install

Untracked 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.

Command Line

• burnlist --plan <burnlist.md> --check validates the active queue and completed ledger.
• burnlist --plan <burnlist.md> --digest prints a completion digest after the active queue is empty.
• burnlist --close-completed adds a digest when needed and moves empty in-progress Burnlists to completed.
• burnlist --stamp prints a local ISO timestamp for completion records.
• burnlist install / burnlist uninstall manage the independent agent-skill registrations.
• burnlist hooks install|uninstall|status manages the independent per-repository native observability hooks.

Use burnlist --help for dashboard ports, scan roots, local state paths, and Oven data bindings.

Terminal UI

The experimental terminal observer lives in tui/. Its landing page is a responsive full-width Burnlist list. Burnlist detail exposes navigable active and completed items, marks the latest completion, and opens item-specific Oven views. OpenTUI React owns layout and input; glyphcss from the adjacent ../../glyphcss checkout renders the animated fire and effects. Visual Parity PNGs use the native image layer in the Burnlist OpenTUI fork on VS Code, iTerm, and WezTerm, with the 2×2 RGBA glyph renderer retained underneath as a portable fallback. In VS Code, enable terminal.integrated.enableImages. Backgrounds remain transparent and dividers adapt to the host terminal palette, including VS Code themes. The visual-review TUI is currently built from a source checkout rather than embedded in the universal npm package. This avoids sending large Darwin-only binaries to every host. Use npm --prefix tui install && npm run build:tui, then open it through the regular CLI with burnlist -i. The CLI validates the shared observer recorded in ~/.burnlist/server.json and restores it when needed; burnlist -i --local instead owns one ephemeral observer for the TUI session. Screen layouts are declarative .glyph documents under tui/screens/. Pass an explicit dashboard with burnlist -i --server http://127.0.0.1:4510.

Use up/down to navigate Burnlists and inspect their items. o opens the global generic Oven catalog; installed repository-specific Ovens remain scoped to their Burnlists. In a Burnlist, [ and ] move between compatible Oven lenses. q always goes back, and escape goes back from nested views or exits only from the main landing page. r refreshes the current data.

Built-in Loops (Stage 1)

Items may use direct execution or one of exactly three built-in Loops:

direct  Start -> Implement -> Burn
review  Start -> Implement -> Check -> Review -> Burn
gate    Start -> Implement -> Check -> Burn
branch  Start -> Plan -> N host-orchestrated branches -> Merge -> Check -> Review -> Burn

Inspect and explicitly trust the repository check with burnlist loop capability inspect|trust, then assign an item with burnlist loop assign. Burnlist stores no agent profile, provider route, subscription, or login. Run burnlist loop view <item-ref> and paste its complete ASCII output into the work handoff; it is the frozen graph, pin, and completion-path record for that item. Create a Run with loop create; for each agent node, use loop next, invoke a native subagent or external provider CLI from the host with its small task, and use loop submit for the semantic result. Burnlist automatically advances its trusted checks and gates to the next agent or terminal node. Inspect with loop status|inspect; pause and stop are idle-Run controls, proof-gated reconcile handles a demonstrably lost claim, and loop prune --retain <count> archives only non-current failed/stopped/exhausted/needs-human histories. loop list keeps a bounded newest-history public window even when more history is retained. Only a converged Run can be applied by loop complete; the command is idempotent and performs the normal shrinking-list completion.

The host owns every provider invocation. Codex and Claude can use native subagents; any host can deliberately harness Codex CLI, AGY, Grok, or another CLI through the installed skill's explicit recipes. Before the first Loop, the skill inventories available native agents, CLIs, live access, and subscriptions without reading credentials, shows the result, and asks which providers the user wants to use or set up. Burnlist never installs, authenticates, configures, or launches an agent provider. Host execution remains independent from Streaming Diff hooks.

The Checklist UI is read-only and shows the active node, attempt, results, transition history, recent correlated hook activity, and a local forecast range with confidence and provenance. Forecasts are bounded private history learned only after accepted semantic completion; missing token facts remain missing and subscription pricing never becomes an invented cost. Burnlist enforces the graph, claim identity, trusted checks, budgets, closed outcomes, and atomic CLI writes. Provider permissions remain host-supervised, not an OS sandbox. Burnlist-native parallel scheduling, Docker isolation, metrics gates, worktrees, and background execution are deliberately unsupported in Stage 1. The Branch host uses native or CLI subagents when available and falls back to the same slices sequentially. Items with no Loop assignment keep the ordinary direct burnlist burn workflow.

See the Loop CLI reference for the exact setup and recovery commands. Installing the Burnlist skill (burnlist install) does not install Streaming Diff hooks (burnlist hooks install), and neither is required to use the Loop.

Build and Verify

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 build:tui
npm run storybook
npm run build:storybook
npm run test:differential-testing
npm run test:tui
npm run verify:fast
npm run verify
npm run verify:clean
npm run verify:package
npm run test:global-install

verify:fast is the non-mutating inner loop for TUI types, tests, generated-frame freshness, and prototype coverage audits; it intentionally does not claim final 100% coverage. verify remains the required full gate (verify:gate is an alias). verify:clean checks the source, npm payload, and isolated global install from a temporary copy.

Oven events

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.

Local State

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.

License

Burnlist is licensed under the MIT License.