State Diff
Structured before/after view of state mutations.
Install
npx ax-depute@latest add state-diffpnpm dlx ax-depute@latest add state-diffyarn dlx ax-depute@latest add state-diffbunx ax-depute@latest add state-diffOverview
State Diff provides mutation visibility, turning abstract JSON payloads into human-readable proof of what changed. In high-stakes environments, humans cannot simply trust an agent's summary — they need exact before-and-after deltas.
Basic Usage
<StateDiff
title="Configuration Changes"
entries={[
{ field: 'max_instances', type: 'modified', before: '2', after: '5' },
{ field: 'region', type: 'added', after: 'us-east-1' },
{ field: 'legacy_mode', type: 'removed', before: 'true' },
]}
/>Solution Patterns
Place StateDiff inside a ToolTrace or a PlanCard to show exact intended or completed mutations. It is typically paired with BindingApproval to prove what the user is cryptographically signing off on prior to execution.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Title of the diff (e.g. "Database Mutation") |
description | string | — | Optional context |
entries | DiffEntry[] | — | Flat list of diff entries |
groups | DiffGroup[] | — | Grouped entries (takes precedence over entries) |
hideUnchanged | boolean | false | Hide unchanged fields |
defaultCollapsed | boolean | false | Start collapsed |
timestamp | string | — | Mutation timestamp |
sourceId | string | — | Tool call/step ID |
Design rationale
Why hideUnchanged? Massive JSON payloads distract from the actual mutation. Highlighting only the delta reduces cognitive load and focuses human attention exactly where the risk is.
Why structure over syntax highlighting? A human cannot easily parse a raw git-style diff of a minified JSON object. Transforming the delta into a structured, dot-notated table makes the blast radius legible to non-engineers.