> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# History

> Local audit log for registry dependency lifecycle events.

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

```text theme={null}
.buttons/
  buttons/
  drawers/
  history.json   # local audit log (gitignored)
```

## Event shape

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

```json theme={null}
{
  "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:

```text theme={null}
.buttons/buttons.json
.buttons/buttons-lock.json
```

Ignored (runtime and secret-bearing):

```text theme={null}
.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:

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

```bash theme={null}
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](/cli/buttons_summary) and [buttons history](/cli/buttons_history).

## Related

* [Registry](/concepts/registry)
* [Folder structure](/concepts/folder-structure)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.