CliffCompaction

Autocompaction for coding agents, as a transparent API proxy. Point an agent's base URL at it and long sessions stay under a token budget — the agent is unchanged and unaware.

Quick start

uv tool install cliffcompaction        # or: pip install cliffcompaction

Or, from a clone:

uv tool install --force --editable .   # or: pip install -e .

Then start the proxy — this adds the base-URL variables to your shell profile and installs a background service (launchd on macOS, systemd --user on Linux):

cliff enable                           # defaults to Claude Code

Open a new terminal and run your agent as usual — claude, or anything reading those variables.

Other commands:

• cliff status — health.
• cliff restart — picks up an upgrade, keeping the daemon's flags. A running daemon keeps serving the code it started with, so an upgrade changes nothing until you restart; cliff status warns when that has happened.
• cliff watch — live view of requests, matches and compactions (recommended for Claude Code and Codex CLI; other scaffolds compact normally, but the watch display may mislabel).
• cliff disable — reverses everything.

More than one daemon

For a second provider, or a different threshold per client. Each instance gets its own port, flags and log; status, restart, watch and disable all take --name:

cliff enable --name kimi --port 8305 --anthropic-upstream https://api.kimi.com/coding

Named instances don't touch your shell env — point the client at the port yourself:

ANTHROPIC_BASE_URL=http://127.0.0.1:8305 claude

Codex CLI

Codex routes by config file rather than an env var, so it needs a provider block in ~/.codex/config.toml:

cliff enable --name codex --port 8448 --openai-upstream https://chatgpt.com

model_provider = "cliff"    # top-level key: must go above the first [table] header

[model_providers.cliff]
name = "OpenAI via cliff"
base_url = "http://127.0.0.1:8448/backend-api/codex"
wire_api = "responses"
requires_openai_auth = true

One session without the proxy

Drop the env var for a single process:

env -u ANTHROPIC_BASE_URL claude    # OpenAI-side clients: -u OPENAI_BASE_URL -u OPENAI_API_BASE

Codex has no env var to unset — override the key instead:

codex -c model_provider=openai      # and again on resume: ... resume --last

Without installing a daemon

A proxy on a free port, env set for that command only, torn down after:

cliff run -- claude
cliff run --shadow -- claude        # observe-only: logs what it would compact, changes nothing

--shadow also works on cliff enable — useful to confirm a scaffold's history is prefix-stable before going active.

Or run the server yourself:

cliff serve --port 8257 --threshold 200000 --keep-recent 3
export ANTHROPIC_BASE_URL=http://127.0.0.1:8257
export OPENAI_BASE_URL=http://127.0.0.1:8257/v1

Important: disable your scaffold's own compaction. Under the proxy it sees small prompt counts, so its triggers generally won't fire anyway — but some rewrite history in place, which breaks the prefix matching CliffCompaction relies on.

uv sync
uv run pytest

Citation

CliffCompaction: Cost-Efficient Compaction for Long-Horizon Coding Agents

@article{nguyen2026cliffcompaction,
  title   = {CliffCompaction: Cost-Efficient Compaction for Long-Horizon Coding Agents},
  author  = {Nguyen, Trang and Cho, Eulrang and Chen, Bingqing and Dettmers, Tim},
  journal = {arXiv preprint arXiv:2609.26779},
  year    = {2026}
}