CliffCompaction

// Overview

CliffCompaction is a proxy you run between a coding agent and its model provider. When the conversation it is forwarding crosses a token threshold, it rewrites the request with a shorter history and passes it upstream. The agent is not modified and never learns that anything was removed, so the same proxy works for Claude Code, Codex CLI and anything else speaking the Anthropic Messages or OpenAI Chat Completions and Responses APIs.

The design rests on one rule: only truncate or drop, never rephrase. Summarising earlier context into new prose is what most harnesses do, and it lets errors compound, because each pass is a summary of a summary. CliffCompaction instead keeps system prompts, task descriptions and the most recent turns byte-for-byte, caps assistant reasoning and tool-call signatures to a character budget, and discards long tool results outright on the grounds that the files behind them are still readable with another tool call.

The second rule follows from the first: a compaction is never compacted. Each time the threshold is crossed the proxy throws away the previous compacted history and recompresses the live session from its original content, so no piece of text is ever passed through the shrinking process twice. The method is described in arXiv:2609.26779 by Trang Nguyen, Eulrang Cho and Tim Dettmers of Carnegie Mellon University with Bingqing Chen of the Bosch Center for AI, which reports up to 50% lower cost on Terminal-Bench 2.0 at a slightly higher success rate.

// What it does

• Transparent proxy for Anthropic Messages, OpenAI Chat Completions and OpenAI Responses — the agent runs unchanged behind it
• Truncate-and-drop compaction that never rephrases text, and never compacts an already-compacted history
• System prompt, task description and the most recent turn pairs are forwarded verbatim
• Per-field character budgets for tool results, assistant text and thinking blocks, each settable by flag or environment variable
• Shadow mode that reports what would be compacted while leaving the real requests untouched
• Background daemon with status, restart, live-watch and disable commands, or a one-off proxy scoped to a single command

// Getting started

CliffCompaction installs as a Python tool and exposes a single `cliff` command. Enabling it installs a background daemon and points your agent's configuration at the proxy.

uv tool install cliffcompaction
# or
pip install cliffcompaction

cliff enable
cliff status
cliff watch

cliff run --shadow -- claude

cliff serve --threshold 32000 --keep-recent 3 --result-max-chars 500
CLIFF_THRESHOLD_TOKENS=32000 cliff run -- codex

cliff disable

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Hold a multi-hour coding-agent run inside a fixed token budget without editing the agent or its scaffold
• Cut the input-token bill of a long session, where the whole history is re-sent on every single turn
• Run a small-context or cheaper model on a long task that would otherwise overflow its window
• Measure what compaction would remove from your own traffic, via shadow mode, before switching it on

// How CliffCompaction compares

CliffCompaction alongside other open-source context compression & token budgets tools AI/TLDR tracks, ranked by GitHub stars.