Polite Compaction for Claude Code

Nowadays I work with my Claude Code agents mainly through Slack and Discord (for work), and on GitHub and /dev/null (for open source). That means most of the planning and management work happens in a single long-running session.

This note describes Polite Compaction, a technique where you tell your agent that you’re going to /compact soon and ask if it needs to save anything to persistent memory first. The agent gets a chance to keep more information while generating shorter summaries, so it performs better over long sessions. I automated this by building the polite-compaction plugin.

After testing this for a while, I did not notice any performance drop, but the usage cost went down by 55%.

The chart above shows the average cost per API call. The left half is 3,000 API calls before I enable the plugin, and the right half is 3,000 API calls after.

Although cache reads cost just 2.5%–10% of the base input price, it still domainates the session cost. On agentic workflows where a turn requires multiple model calls, the cost grows quadratically with the context size. After I enable the plugin, average context size per message went down from 509k to 208k.

Impolite compaction

In Claude Code, /compact forces the agent to generate a summary right then and there.

Whatever the agent thinks is useful stays in the summary, and the rest is discarded. Unfortunately, the agent doesn't always get this right — sometimes it discards small but important details. For example, when I give my agents feedback, it only obeys until compaction, and then it forgets.

I think Claude’s default compaction mechanism is too forceful, because the agent has no chance to save anything to persistent memory first. Everything in the context either goes to compaction summary, or goes forgotten.

Compacting politely

So, before auto-compact kicks in, I tell the agent:

I'm going to compact your context soon. Anything to flush?

This gives the agent a chance to save some info in persistent memory. Persistent memory can refer to:

The agent saves what it needs, then tells me to go ahead. Then I run /compact. This brings 2 main benefits:

  1. Shorter summaries. As some knowledge are persisted, the agent doesn't have to repeat them in the summary.
  2. More information is retained. This means less performance loss after compaction.

At first, I do this manually whenever I remember, but I often forget when I'm focused.

Automating it with a mod

Claude Code's mods feature lets me write TypeScript plugins that integrate deeply with Claude Code. A mod can read the state of the conversation and trigger compaction. So I build a small polite-compaction plugin that does this:

Screenshot of a polite-compaction plugin working in action

The polite-compaction plugin automatically tells Claude Code to prepare for compaction after context grows larger than 300k tokens. Claude then saves things to memory and tells the plugin that it’s ready for compaction, and the plugin triggers a compaction.

  • It waits for a turn to finish first. So for really complex task, the plugin will let the agent finish the work at hand first. (From my experience, sometimes this can go up to 450k.)
  • This works separately from Claude’s auto-compact (which triggers at 967k of context).

You can install it by running this in Claude Code:

/plugin marketplace add dtinth/claude-code-mods
/plugin install polite-compaction@dtinth-mods