CliffCompaction

CliffCompaction is an open-source Python tool that sits between a coding agent and its model provider as a transparent API proxy. Pointing the agent's base URL at it keeps long sessions under a configurable token budget while the agent itself stays unchanged. The latest release listed is v0.1.0, and the project is MIT licensed.

What It Is

CliffCompaction provides autocompaction for coding agents such as Claude Code and Codex CLI. It runs locally, either as a background service (launchd on macOS, systemd --user on Linux) or as a one-off proxy, and forwards requests to an upstream provider. Supported API dialects are Anthropic Messages, OpenAI Chat Completions and OpenAI Responses with native tool calling; other traffic passes through verbatim.

How Compaction Works

Each request is history plus the latest step. The proxy hashes messages into a chain. When the outgoing size exceeds the threshold, it rebuilds the history as the verbatim head, one summary message, and the last few turns verbatim. Later requests carrying the original history are matched to the longest stored prefix and swapped for the compacted version. If the provider still returns a context-length error, the proxy compacts and replays once.

The summary is mechanical, built by content class. Tool results of 500 characters or fewer are kept and longer ones dropped, tool calls become one-line signatures, assistant text and thinking are kept by default, and images are dropped from summaries. Re-compaction drops the previous summary. Any failure falls back to verbatim passthrough.

Setup and Operation

Install with uv or pip, then run cliff enable to add base-URL variables to the shell profile and install the daemon. Commands include cliff status, restart, watch and disable. Multiple named instances can use different ports, upstreams or thresholds. cliff run -- claude runs a single command through a temporary proxy, and --shadow mode logs what would be compacted without changing anything. Codex CLI needs a provider block in its config file. The scaffold's own compaction should be disabled.

Configuration

Flags and environment variables control the token threshold (default 200000), recent turns kept (default 3), character caps for assistant text, thinking and tool results, thinking exclusion, custom Anthropic and OpenAI upstreams, strict mode, and a debug dump directory.