Compaction
Sign in
Documentation

CLI reference

The CLI is local-first: every command runs on your machine and writes its artifacts under .compaction/. Nothing requires a server or a dashboard.

Live path

compaction init

compaction init

One-command setup: detects installed tools and how each authenticates, then configures the right path (gateway for API keys, native hooks for subscriptions). Prints exactly what it will write before writing; everything is reversible. See Get started.

compaction gateway

compaction gateway                 # start (record mode by default)
compaction gateway run -- <cmd>    # wrap a single command
compaction gateway status          # running state + receipt rollup
compaction gateway recover <id>    # byte-exact original of an applied request
compaction gateway verify-cache    # provider-reported cache verification

The local reverse proxy: record / apply / dry-run modes, content-free receipts. See Gateway and Apply.

compaction hooks

compaction hooks install --tool codex
compaction hooks status
compaction hooks uninstall --tool codex

Native output-shaping hooks for subscription tools (Claude Code, Codex per-prompt; Cursor session-level). Install prints what it will write, merges with existing settings, and supports --dry-run. See Output shaping and hooks.

compaction status · compaction activity

compaction status      # setup and routing health
compaction activity    # recent runs, from the local receipts

Both read only the local, content-free receipts — measured counts with their evidence labels.

Trace tools (offline)

The offline workflow for analyzing and optimizing exported trace files — covered on Trace tools (advanced):

compaction import <trace> --source agent-trace --out <dir>
compaction analyze <trace>       # read-only findings
compaction compact <trace> --out <dir>
compaction spend <trace>         # spend breakdown + delta (local estimates)
compaction recommend <trace>     # advisory recommendation + safety evidence
compaction approve --require-safety-pass
compaction apply <trace> --policy <policy.json>
compaction audit                 # aggregate local runs
compaction summary               # roll up all local reports

Trace figures are local estimates and labeled as such; provider-reported numbers come from the live gateway path. See Proof and receipts.

Kill-switches and removal

  • COMPACTION_SHAPING_HOOKS=0 — disables output shaping on the next turn.
  • compaction hooks uninstall --tool <tool> — removes only Compaction’s own hooks.
  • Re-running compaction init reconfigures or reverses the launcher setup.