conPACT

conPACT

CONtext comPACT. Lets your coding agent compact its own context when a piece of work is done, and offers to compact idle sessions before their prompt cache expires. For Claude Code Desktop and ChatGPT Desktop (Codex).

Why

Long agent sessions get expensive in two ways:

• The context keeps growing long after the work that needed it is finished.
• An idle session goes cold. Come back after its prompt cache has expired and the next message re-reads the whole context uncached.

/compact fixes both, but only if someone types it at the right moment. conPACT does it for you, for real:

• At the end of a piece of work, the agent queues a compaction of its own session. It runs after the final answer, as a genuine /compact: your chat history stays visible, and only the live context is summarised. With the conPACT mod, Claude Code does it from inside the session; without it, it travels over Remote Control.
• When a big session sits idle, a small toast appears shortly before the cache expires and offers to compact it now, or always to do so for that session.
• In ChatGPT Desktop, the same two things, through an optional sidecar.

What it is not: a token-threshold trigger, a reminder for you to type /compact, /clear, or a fake "I compacted" message.

Requirements

• Python 3.11 or later. No other dependencies; everything is standard library.
• Claude Code Desktop. With the conPACT mod (Claude Code 2.1.284 or later) a session compacts itself, for the agent and for the idle toast, and needs nothing else. Without the mod, Remote Control must be on for the sessions you want compacted: it is the route the /compact travels.
• Windows, Linux or macOS. The whole test suite runs on Windows 11, Linux and macOS, and conPACT has been used live on Windows. Only the Claude Code integration reads a macOS Keychain login; ChatGPT Desktop and Codex CLI use Codex's own authenticated process and conPACT never reads their credentials. See what each platform supports.

Quick start (Claude Code)

1. Get the code. Nothing to build; the tools run straight from the checkout.

git clone https://github.com/st0nebridge/conPACT.git conpact

2. Add the Stop hook. This is what sends the /compact at the end of a turn. In ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "/path/to/conpact/tools/stop_compact.sh", "timeout": 90 } ] }
    ]
  }
}

That is macOS and Linux. On Windows the command is C:/path/to/conpact/tools/stop_compact.cmd. It works from the next turn end, in every session, including ones already open.

3. Register the MCP server, so the agent can queue a compaction with a tool call. Use the full path to the Python executable, not a wrapper script such as pyenv-win's python.bat:

claude mcp add --scope user conpact -- "/path/to/python3" "/path/to/conpact/tools/mcp_server.py"

Sessions pick it up when they next start.

4. Install the mod. With it, a queued compaction is carried out inside the session at the end of the turn, with no Remote Control:

claude plugin marketplace add st0nebridge/conPACT
claude plugin install conpact@conpact

It needs Claude Code 2.1.284 or later; before 2.1.287 mods are in early access and need one environment variable. Where the mod does not load, the Stop hook and the MCP server carry on without it. Details, and how to load it from your checkout instead: docs/claude-code-mod.md.

5. Turn on Remote Control in each session's toolbar, or wait for the first idle toast to offer to turn it on for every new session. Only a session the mod is not loaded in needs it, for the idle toast and for a queued compaction.

6. Check what each open session still needs:

python tools/session_ready.py

More detail, including uninstalling: docs/setup.md.

Using it

Let the agent do it

With the MCP server loaded, the agent gets four tools, and the server tells it when to use them: after verified, saved implementation work, such as a feature, fix or build, or when you explicitly ask to compact. Routine questions, read-only investigations, status reports and intermediate answers do not queue compaction, even when the context is large. It never queues in a throwaway worktree session (one Claude Code started in a .claude/worktrees/... checkout, which is merged and discarded rather than resumed). You can also just ask it to compact.

To make it a dependable step of your own workflow, with a block to paste into CLAUDE.md or AGENTS.md and advice on the focus and the minimum size, see Telling your agent when to compact.

Tool	What it does
queue_compaction	Compact this session when the turn ends. Optional focus (what the summary should keep) and min_context_tokens (skip it if the context is smaller).
cancel_compaction	Withdraw it.
compaction_status	What is queued, and how big the context is now.
hold_idle_toast	Hold the early idle toast while waiting on a long build or test run.

The tool only records the request, and the compaction happens when the turn ends, so it always lands after the final answer, and at most once. With the mod loaded, the mod answers the tools and compacts the session itself; without it, the Stop hook sends /compact over Remote Control.

With the mod, one row above the prompt follows the request: queued (with what it will keep and cancel), compacting, then what it came to, with a meter of what was kept and a × to dismiss it. An idle-toast compaction shows there too. In the Desktop app the mark at the start is drawn: a pulsing dot, a turning ring, a check or a cross.

The same row in the Desktop app's Code tab:

More on the row: docs/claude-code-mod.md.

Or from the shell

python tools/bridge_send.py --self --request                            # compact at the end of this turn
python tools/bridge_send.py --self --request --min-context-tokens 150k  # ...only if it is worth it

Every option: docs/commands.md.

The idle toast

It turns up by itself for sessions of 100,000 tokens or more, five minutes before a 1-hour cache expires, in the bottom-right corner, without taking focus.

• Compact now: compact it while the cache is still warm.
• Always compact: do this for that session from now on, without asking.
• Silence 24 h or Not now: leave it.

Using the session again cancels it, and nothing is ever sent to a busy session. There is an optional earlier toast too: docs/idle-toast.md.

Anthropic can switch on an idle compaction of Claude Code's own, which does the same job without asking. When it does, conPACT asks you once which one to keep: conPACT's, Claude Code's, or both. How it works.

Checking the summary's sources

A summary can turn a precaution the agent chose for itself, or another session's request, into a rule that reads as yours. Every compaction conPACT starts asks the summary to give each constraint its source. An optional SessionStart hook checks every compaction afterwards, whoever started it, and tells the resumed agent which constraints it traced to your words or an instruction file and which it could not:

"SessionStart": [
  { "matcher": "compact",
    "hooks": [ { "type": "command", "command": "python /path/to/conpact/tools/compact_provenance.py", "timeout": 60 } ] }
]

More: docs/agent-workflow.md.

ChatGPT Desktop

conPACT reads and measures ChatGPT Desktop's threads out of the box, without changing anything. To compact the thread you are working in, which the app holds open, install the sidecar with one click:

python tools/codex_sidecar.py window

then restart ChatGPT Desktop. The same MCP tools can be registered for Codex threads. What the sidecar is, what it touches and how to remove it: docs/chatgpt-desktop.md.

Check the installed Codex integration without changing anything:

python tools/doctor.py

It checks the Codex login, MCP registration, sidecar, bundled Codex build and read-only thread access. A missing Claude Code Keychain login is informational, not a Codex failure.

Codex CLI

Install one Codex Stop hook, then start the terminal UI through conPACT:

conpact-codex --install
conpact-codex

If that command is not on PATH, run uv tool install --editable . followed by uv tool update-shell, then open a new terminal.

On the first start, open /hooks and trust the conPACT hook. The launcher uses Codex's --remote option to connect the terminal UI to conPACT's existing token-protected loopback app-server. The token stays in an environment variable, not the process arguments. All four MCP tools then work in the CLI, including turn-end queue_compaction and the idle toast.

Plain codex remains unchanged; use conpact-codex for the integrated path. Without an editable install, use python tools/codex_cli.py. See Codex CLI setup.

Settings

python tools/settings.py                                # opens the settings window
python tools/settings.py show
python tools/settings.py set min_context_tokens 150k

Or click Settings on any toast. Every setting, its default and its range: docs/settings.md.

Safety at a glance

• It only acts on the session that asked. No tool takes a target; the session is identified from the runtime, never from anything the model says.
• It only sends /compact. There is no free-text sending, and a request fires at most once.
• The mod reaches only what it needs: no process, no network, no file written. claude plugin validate src/mod lists every call it makes.
• The idle toast sends only what you click, or what you switched that one session to do automatically.
• Your login token never leaks. It is never printed, logged, or stored anywhere but its own file.
• The ChatGPT Desktop sidecar is opt-in and reversible. Its control port is loopback-only and token-guarded.

The full model: docs/security.md.

Status

Tests	Windows 3,287 passed (2026-10-24); Linux 2,003 passed (2026-09-25); macOS 2,178 passed (2026-09-23)
Claude Code, live	Agent-queued and toast-driven compactions observed end to end; with the mod, an agent-queued compaction observed end to end with Remote Control off, a Desktop session compacted through /compact, and the band drawn in the terminal and the Desktop app
ChatGPT Desktop, live	Sidecar compaction, turn-end arming, and a thread queueing its own compaction observed end to end

What has been observed, what has not yet, and the mutation scores: docs/verification.md.

Documentation

How it works	The goal, the Remote Control route, and why a request fires only after the final answer
Setup	Stop hook, MCP server, the mod, Remote Control, sessions that were already open
The Claude Code mod	Compacting a session from inside Claude Code, without Remote Control
Idle toast	Stages, buttons, auto-compaction, holds
Settings	Every setting, with defaults and ranges
Commands	Every command-line tool
ChatGPT Desktop	Codex threads, the sidecar, and Codex Remote Control
Security model	What conPACT can and cannot do, and why
Architecture	Modules, entry points, state files, layout
Verification	Tests, coverage, mutation scores, live evidence

Contributing

The test suite needs pytest, pytest-cov for the mutation tester's own tests, and jsonschema for the MCP tool schemas: pip install pytest pytest-cov jsonschema, then python -m pytest -q. Before changing how something works, read the two project records at the top of the repository: CHANGES.md lists every change, newest first, with how it was verified, and DECISIONS.md lists every settled design choice and the reason for it.

Lance Sandino contributed the macOS support, the Codex CLI compaction and the read-only doctor, the macOS sidecar's move to ChatGPT Desktop's new layout, and the check that confirms a Codex compaction with a very large history record.

License

MIT. See LICENSE.