# CliffCompaction

> A transparent proxy that compacts agent history by cutting, never rewriting

- Category: App Orchestration / Context Compression & Token Budgets
- Language: Python
- Licence: MIT
- Repository: https://github.com/nguyenvuthientrang/cliffcompaction
- Canonical page: https://ai-tldr.dev/tools/cliffcompaction/
- Updated: 2026-09-22

## In short

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. It sits in the Context Compression & Token Budgets category of the App Orchestration tools and is open-source, written in Python and licensed MIT.

## 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.

1. Install the tool

   The package requires Python 3.11 or newer.

```bash
uv tool install cliffcompaction
# or
pip install cliffcompaction
```

2. Enable the proxy for Claude Code

   `cliff enable` installs the background daemon with default settings and rewrites the agent configuration to route through it. `cliff status` checks the daemon is healthy and `cliff watch` prints requests and compaction events as they happen.

```bash
cliff enable
cliff status
cliff watch
```

3. Watch it first without changing anything

   Shadow mode forwards every request untouched and only reports what it would have compacted, which is the safe way to see whether the threshold is set sensibly for your workload.

```bash
cliff run --shadow -- claude
```

4. Tune the budgets

   The token threshold defaults to 200,000, three recent turn pairs are kept, and tool results are capped at 500 characters. Every setting has a flag and an environment variable.

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

5. Turn it off

   `cliff disable` removes the daemon and reverts the configuration changes that `cliff enable` made.

```bash
cliff disable
```

## 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

## Version history

- 2026-09-22 v0.1.0: First public release, alongside the arXiv paper. The proxy reports up to 50% lower cost on Terminal-Bench 2.0 and holds Kimi K2.6 at 73.27% on SWE-bench Verified with a 32K threshold, against 73.87% at full context.