# Audit log

Record what the agent and the people did, searchable, exportable, and with retention that says what is kept.

For: Admins, security and compliance.

Web page: https://candor.themethodic.com/screens/audit-log

## Layouts

### Filterable table

Pick it when: The default: people look up events by who, what and when.

Layout: A filter bar over a table of events: time, who, what, and the thing it touched.

Items:

- **Audit log** (`audit-log`, Pro; https://candor.themethodic.com/docs/audit-log.md): The account's audit log.
- **Filter chips** (`filter-chips`, Pro; https://candor.themethodic.com/docs/filter-chips.md): Active filters as removable chips, with a clear-all.
- **Data table** (`data-table`, Pro; https://candor.themethodic.com/docs/data-table.md): Rows with search, sort and pages.
- **Relative time** (`relative-time`, free; https://candor.themethodic.com/docs/relative-time.md): Times people read, with the exact time on hover.

```bash
npx candor-ui add audit-log filter-chips data-table relative-time
```

### Timeline around one thing

Pick it when: Investigating one record, run or agent: everything that touched it in order.

Layout: A vertical rail of events with who did each and what changed.

Items:

- **Audit log** (`audit-log`, Pro; https://candor.themethodic.com/docs/audit-log.md): The events.
- **Version history** (`version-history`, Pro; https://candor.themethodic.com/docs/version-history.md): Live, draft and past versions, newest first.
- **Change hash** (`change-hash`, Pro; https://candor.themethodic.com/docs/change-hash.md): The hash an approval was made against, so an event can be checked against the change it records.

```bash
npx candor-ui add audit-log version-history change-hash
```

### With export and retention

Pick it when: The owner needs to export, keep or delete what's recorded.

Layout: The log on the left and data controls on the right: export, how long it's kept, delete.

Items:

- **Data controls** (`data-controls`, Pro; https://candor.themethodic.com/docs/data-controls.md): How data is used, an export, deleting history, deleting the account.
- **Data retention** (`data-retention`, Pro; https://candor.themethodic.com/docs/data-retention.md): How long each kind of data is kept, and what happens after.
- **Type to confirm** (`type-to-confirm`, Pro; https://candor.themethodic.com/docs/type-to-confirm.md): Deleting is confirmed by typing a name.

```bash
npx candor-ui add data-controls data-retention type-to-confirm
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): An event the log couldn't record shows as a gap with the reason, not as nothing happening.
- **The agent is always named, by the app** (https://candor.themethodic.com/principles#agents-are-named): Each row names the actor, an agent or a person, from your records.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Deleting history says that it can't be undone and what it removes.

## Patterns that cover part of it

- Audit log UI for AI agents: https://candor.themethodic.com/patterns/ai-audit-log.md

A full-stack block builds this with an agent route and a store: `audit-data-controls` (https://candor.themethodic.com/docs/audit-data-controls.md). Each block has a `-claude` twin for the Claude Agent SDK.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build an audit log with Candor UI: AuditLog over a filterable table of events (who, what, when, the thing it touched).
Use FilterChips for the active filters and RelativeTime for times, with the exact time on hover.
Name the actor on each row from your records: an agent by its role and name, a person by their account.
A period the log has no records for shows as a gap with the reason, not as an empty period.
For export, retention and deletion use DataControls and DataRetention; deleting uses TypeToConfirm and says that it can't be undone.
Start from the audit-data-controls block (audit-data-controls-claude for the Claude Agent SDK) for the routes and the store.
Read the ai-audit-log pattern for what to record.

Start from the "Filterable table" layout: A filter bar over a table of events: time, who, what, and the thing it touched.
Candor items: audit-log (https://candor.themethodic.com/docs/audit-log.md), filter-chips (https://candor.themethodic.com/docs/filter-chips.md), data-table (https://candor.themethodic.com/docs/data-table.md), relative-time (https://candor.themethodic.com/docs/relative-time.md).
Install: npx candor-ui add audit-log filter-chips data-table relative-time
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```