Trace tools (advanced)

Alongside the live path (gateway and hooks), the CLI includes an offline trace workflow: point it at an exported trace file and it analyzes, compacts, and packages the evidence locally. Useful for evaluating a compaction policy on captured history before trusting it live, or for auditing sessions after the fact. Most users never need this page — the live path is the product.

The workflow

compaction import ./trace.json --source agent-trace --out ./my-trace
compaction analyze ./my-trace/captured-trace.json
compaction compact ./my-trace/captured-trace.json --out .compaction/runs/first-run
compaction spend ./my-trace/captured-trace.json
compaction approve --require-safety-pass
compaction apply trace.json --policy .compaction/runs/first-run/policy.json
compaction audit

import — normalize a local trace file into the compaction trace schema. Local files only; no live provider pulls.
analyze — read-only findings: repeated tool output, stale context. Writes nothing.
compact — generate a compacted trace, state capsule, policy, and cost report (local token estimates).
spend — where context spend came from and the before/after delta, with the evidence label on every figure.
recommend / approve — an advisory recommendation backed by safety evidence, and an explicit local approval record. Approve refuses when safety or source-pointer requirements are not met.
apply — run a reviewed policy against the trace file and record the result. Live request optimization is the gateway’s own apply mode — see Apply.
audit / summary — aggregate local runs into one audit package (compaction audit) or roll all local reports into summary.json (compaction summary).

Artifacts

Every command writes its reports under .compaction/ — JSON plus a readable Markdown twin (for example report.json / report.md, spend-summary.md, audit-report.md). All figures in trace artifacts are local estimates and labeled as such; provider-reported numbers come from the live gateway path.

State capsules

When compact removes spans, the removed content is preserved in a local state capsule with source pointers, so any removed span can be restored deterministically. Recoverability — byte, hash, source pointer — is the guarantee; whether removed context mattered stays a human call.

Command flags and exact output formats: see the CLI reference.

Trace tools (advanced)

The workflow

compaction import ./trace.json --source agent-trace --out ./my-trace compaction analyze ./my-trace/captured-trace.json compaction compact ./my-trace/captured-trace.json --out .compaction/runs/first-run compaction spend ./my-trace/captured-trace.json compaction approve --require-safety-pass compaction apply trace.json --policy .compaction/runs/first-run/policy.json compaction audit

import — normalize a local trace file into the compaction trace schema. Local files only; no live provider pulls.

analyze — read-only findings: repeated tool output, stale context. Writes nothing.

compact — generate a compacted trace, state capsule, policy, and cost report (local token estimates).

spend — where context spend came from and the before/after delta, with the evidence label on every figure.

recommend / approve — an advisory recommendation backed by safety evidence, and an explicit local approval record. Approve refuses when safety or source-pointer requirements are not met.

apply — run a reviewed policy against the trace file and record the result. Live request optimization is the gateway’s own apply mode — see Apply.

audit / summary — aggregate local runs into one audit package (compaction audit) or roll all local reports into summary.json (compaction summary).

State capsules

Command flags and exact output formats: see the CLI reference.