History - Buttons

history.json is the local audit log for a Buttons workspace. It records workspace mutations:

registry dependency changes from buttons add
manifest installs from buttons install

It is a single top-level file and is gitignored — auditability is per-machine.

.buttons/
  buttons/
  drawers/
  history.json   # local audit log (gitignored)

Event shape

The file has a schema version and an ordered events array:

{
  "schema_version": 1,
  "events": [
    {
      "action": "add",
      "occurred_at": "2026-07-01T12:00:00Z",
      "package_name": "@autono/hello",
      "requested": "latest",
      "installed": ["hello"],
      "dependencies": [
        {
          "name": "@autono/hello",
          "kind": "button",
          "requested": "latest",
          "version": "1",
          "content_hash": "4f8c...",
          "installed_name": "hello"
        }
      ]
    }
  ]
}

Actions

History records:

Action	Cause
`add`	A registry dependency is added to `.buttons/buttons.json` and installed.
`install`	Manifest dependencies are installed from the configured registry.

What’s tracked

Lifecycle events are local audit records. They are not the source of truth for dependency resolution; the source of truth is:

.buttons/buttons.json
.buttons/buttons-lock.json

Ignored (runtime and secret-bearing):

.buttons/history.json
.buttons/buttons/*/pressed/**
.buttons/drawers/*/pressed/**
.buttons/batteries.json
.buttons/webhook.json
.buttons/idempotency/**
.buttons/queues/**

Commit policy

Commit:

your authored button and drawer specs — button.json, drawer.json, the code file, and AGENTS.md
.buttons/buttons.json and .buttons/buttons-lock.json when your project depends on registry buttons

Do not commit:

.buttons/history.json
pressed run history (buttons/*/pressed/, drawers/*/pressed/)
batteries.json, webhook.json, idempotency/, queues/

Registry dependencies are pinned in .buttons/buttons-lock.json, not inside each installed button.json. Committing the manifest and lockfile lets a teammate materialize the same versions with buttons install. history.json stays local — it is each machine’s own audit trail.

Press failures & replay

history.json above tracks dependency lifecycle events. A target’s run history is separate: one JSON file per press under buttons/<name>/pressed/ (and drawers/<name>/pressed/), each recording the args, exit code, output, and status. There is no dead-letter queue — a failed press is just a run record with a non-ok status. That makes triage a short loop an agent runs entirely from the CLI:

Spot failures — buttons summary --json aggregates recent failures across the workspace under recent_failures.
Drill in — buttons history <name> (or buttons drawer <name> --json) shows that target’s recent runs, including the exact args each was pressed with.
Replay — once the cause is fixed, re-press with those same args:

buttons press deploy --arg env=staging --arg version=v1.4.2

Because the args live in the run record, replay is just reading them back and pressing again — no queue to drain, no separate replay command. See buttons summary and buttons history.

​Event shape

​Actions

​What’s tracked

​Commit policy

​Press failures & replay

​Related

Event shape

Actions

What’s tracked

Commit policy

Press failures & replay

Related