# CliffCompaction

> Transparent API proxy that autocompacts long coding-agent sessions to keep them under a token budget.

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.

## Features
- Transparent API proxy for coding agents
- Threshold-based autocompaction of long sessions
- Hash-chain prefix matching to substitute compacted history
- Compact-and-replay on context-length errors
- Mechanical summaries by content class
- Fail-open passthrough on any error
- Shadow observe-only mode
- Background daemon via launchd or systemd --user
- Multiple named instances with separate ports and upstreams
- Live watch view of requests and compactions
- Configurable thresholds and truncation caps
- Supports Anthropic Messages, OpenAI Chat Completions and OpenAI Responses

## Integrations
Claude Code, Codex CLI, Anthropic API, OpenAI API, Kimi

## Platforms
CLI, MACOS, LINUX, API

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://github.com/nguyenvuthientrang/cliffcompaction
- Documentation: https://github.com/nguyenvuthientrang/cliffcompaction
- Repository: https://github.com/nguyenvuthientrang/cliffcompaction
- EveryDev.ai: https://www.everydev.ai/tools/cliffcompaction