Compaction
Sign in
Documentation

Get started

Compaction runs locally. Install the CLI, run compaction init once, then use your agents the way you already do. Everything — the gateway, the shaping hooks, the local summarization model — runs on your machine. This is the whole flow:

Illustrative — mirrors the real `compaction init` flow

Install

The install script places compaction on your PATH:

curl -fsSL https://cli.compaction.dev/install | sh

Prefer npm? The CLI is published as @compaction/cli:

npm install -g @compaction/cli

One command: init

compaction init detects the AI tools on your machine (Claude Code, Codex, Cursor) and how each authenticates, then sets up the right path:

  • API key → routes the tool through the local Compaction Gateway: input compaction, output shaping, and provider-reported content-free receipts.
  • Subscription → installs the tool’s native hooks: task-aware output shaping (per-prompt for Claude Code and Codex, session-level for Cursor).

Init prints exactly what it will write before it writes it, merges with (never replaces) existing settings, and everything it installs can be removed with compaction hooks uninstall or by re-running init.

compaction init

Then just work

Run claude, codex, or cursor-agent normally. Compaction optimizes in the background and writes one content-free receipt per optimized call — token counts and labels, never your content.

See what happened

Receipts accumulate locally under .compaction/:

  • compaction status — setup and routing health
  • compaction activity — recent runs, with measured token counts and the evidence label on every figure
  • Proof and receipts — what the receipts record and how every number is labeled

Turning things off

  • COMPACTION_SHAPING_HOOKS=0 — disables output shaping on the next turn (the hooks stay installed but hold).
  • compaction hooks uninstall --tool claude-code|codex|cursor — removes only Compaction’s own hooks, preserving the rest of your settings.
  • The gateway’s live apply mode is explicit opt-in and keeps the original request body for byte-exact recovery — see Apply.

Full command list: the CLI reference. Working with exported trace files: Trace tools (advanced).