{"id":"83a98bc0-3bd2-4e1f-8c0e-32123cf17497","slug":"conpact","kind":"mcp","name":"conPACT","summary":"CONtext comPACT coordinates agent-initiated context compaction at verified scope closure—after the final answer and a durable checkpoint. It compacts the live context without clearing the visible conv","owner":"st0nebridge","repoUrl":"https://github.com/st0nebridge/conPACT","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-08T11:08:19.000Z","addedAt":"2026-10-21T09:48:07.691Z","logoUrl":"https://avatars.githubusercontent.com/u/23309360?u=1bffe4ce6dff8ca20ef792b9e5dc15b9c8581ae1&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","developer-tools"],"tags":["chatgpt-desktop","claude-code","codex","context-compaction"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T13:43:02.875Z","sample":false,"url":"https://conduits.dev/tools/conpact","language":"Python","transports":["stdio"],"install":{"pypi":"conpact"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# conPACT\n\n*CONtext comPACT.* Lets your coding agent compact its own context when a piece of\nwork is done, and offers to compact idle sessions before their prompt cache\nexpires. For **Claude Code Desktop** and **ChatGPT Desktop (Codex)**.\n\n## Why\n\nLong agent sessions get expensive in two ways:\n\n- **The context keeps growing** long after the work that needed it is finished.\n- **An idle session goes cold.** Come back after its prompt cache has expired and\n the next message re-reads the whole context uncached.\n\n`/compact` fixes both, but only if someone types it at the right moment.\nconPACT does it for you, for real:\n\n- **At the end of a piece of work**, the agent queues a compaction of its own\n session. It runs after the final answer, as a genuine `/compact`: your chat\n history stays visible, and only the live context is summarised. With the\n conPACT mod, Claude Code does it from inside the session; without it, it\n travels over Remote Control.\n- **When a big session sits idle**, a small toast appears shortly before the\n cache expires and offers to compact it now, or always to do so for that\n session.\n- **In ChatGPT Desktop**, the same two things, through an optional sidecar.\n\nWhat it is not: a token-threshold trigger, a reminder for you to type `/compact`,\n`/clear`, or a fake \"I compacted\" message.\n\n## Requirements\n\n- **Python 3.11 or later.** No other dependencies; everything is standard\n library.\n- **Claude Code Desktop.** With the conPACT mod (Claude Code 2.1.284 or later) a\n session compacts itself, for the agent and for the idle toast, and needs\n nothing else. Without the mod, **Remote Control must be on** for the sessions\n you want compacted: it is the route the `/compact` travels.\n- **Windows, Linux or macOS.** The whole test suite runs on Windows 11, Linux\n and macOS, and conPACT has been used live on Windows. Only the **Claude Code**\n integration reads a macOS Keychain login; ChatGPT Desktop and Codex CLI use\n Codex's own authenticated process and conPACT never reads their credentials. See\n [what each platform supports](docs/setup.md#what-each-platform-supports).\n\n## Quick start (Claude Code)\n\n**1. Get the code.** Nothing to build; the tools run straight from the checkout.\n\n```bash\ngit clone https://github.com/st0nebridge/conPACT.git conpact\n```\n\n**2. Add the Stop hook.** This is what sends the `/compact` at the end of a turn.\nIn `~/.claude/settings.json`:\n\n```json\n{\n \"hooks\": {\n \"Stop\": [\n { \"hooks\": [ { \"type\": \"command\", \"command\": \"/path/to/conpact/tools/stop_compact.sh\", \"timeout\": 90 } ] }\n ]\n }\n}\n```\n\nThat is macOS and Linux. On Windows the command is\n`C:/path/to/conpact/tools/stop_compact.cmd`. It works from the next turn end, in\nevery session, including ones already open.\n\n**3. Register the MCP server,** so the agent can queue a compaction with a tool\ncall. Use the full path to the Python executable, not a wrapper script such as\npyenv-win's `python.bat`:\n\n```bash\nclaude mcp add --scope user conpact -- \"/path/to/python3\" \"/path/to/conpact/tools/mcp_server.py\"\n```\n\nSessions pick it up when they next start.\n\n**4. Install the mod.** With it, a queued compaction is carried out inside the\nsession at the end of the turn, with no Remote Control:\n\n```bash\nclaude plugin marketplace add st0nebridge/conPACT\nclaude plugin install conpact@conpact\n```\n\nIt needs Claude Code 2.1.284 or later; before 2.1.287 mods are in early access\nand need one environment variable. Where the mod does not load, the Stop hook\nand the MCP server carry on without it. Details, and how to load it from your\ncheckout instead: [docs/claude-code-mod.md](docs/claude-code-mod.md).\n\n**5. Turn on Remote Control** in each session's toolbar, or wait for the first\nidle toast to offer to turn it on for every new session. Only a session the mod\nis not loaded in needs it, for the idle toast and for a queued compaction.\n\n**6. Check** what each open session still needs:\n\n```bash\npython tools/session_ready.py\n```\n\nMore detail, including uninstalling: [docs/setup.md](docs/setup.md).\n\n## Using it\n\n### Let the agent do it\n\nWith the MCP server loaded, the agent gets four tools, and the server tells it\nwhen to use them: after verified, saved implementation work, such as a feature,\nfix or build, or when you explicitly ask to compact. Routine questions,\nread-only investigations, status reports and intermediate answers do not queue\ncompaction, even when the context is large. It never queues in a throwaway\nworktree session (one Claude Code\nstarted in a `.claude/worktrees/...` checkout, which is merged and discarded\nrather than resumed). You can also just ask it to compact.\n\nTo make it a dependable step of your own workflow, with a block to paste into\n`CLAUDE.md` or `AGENTS.md` and advice on the focus and the minimum size, see\n[Telling your agent when to compact](docs/agent-workflow.md).\n\n| Tool | What it does |\n|---|---|\n| `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). |\n| `cancel_compaction` | Withdraw it. |\n| `compaction_status` | What is queued, and how big the context is now. |\n| `hold_idle_toast` | Hold the early idle toast while waiting on a long build or test run. |\n\nThe tool only records the request, and the compaction happens when the turn\nends, so it always lands after the final answer, and at most once. With the mod\nloaded, the mod answers the tools and compacts the session itself; without it,\nthe Stop hook sends `/compact` over Remote Control.\n\nWith the mod, one row above the prompt follows the request: queued (with what\nit will keep and **cancel**), compacting, then what it came to, with a meter of\nwhat was kept and a **×** to dismiss it. An idle-toast compaction shows there\ntoo. In the Desktop app the mark at the start is drawn: a pulsing dot, a\nturning ring, a check or a cross.\n\n

\n \"Claude\n

\n

\n \"The\n

\n\nThe same row in the Desktop app's Code tab:\n\n

\n \"The\n

\n\nMore on the row: [docs/claude-code-mod.md](docs/claude-code-mod.md#the-band-above-the-prompt).\n\n### Or from the shell\n\n```bash\npython tools/bridge_send.py --self --request # compact at the end of this turn\npython tools/bridge_send.py --self --request --min-context-tokens 150k # ...only if it is worth it\n```\n\nEvery option: [docs/commands.md](docs/commands.md).\n\n### The idle toast\n\nIt turns up by itself for sessions of 100,000 tokens or more, five minutes\nbefore a 1-hour cache expires, in the bottom-right corner, without taking focus.\n\n

\n \n \n \"The\n \n \n \n \"The\n \n

\n\n- **Compact now**: compact it while the cache is still warm.\n- **Always compact**: do this for that session from now on, without asking.\n- **Silence 24 h** or **Not now**: leave it.\n\nUsing the session again cancels it, and nothing is ever sent to a busy session.\nThere is an optional earlier toast too: [docs/idle-toast.md](docs/idle-toast.md).\n\nAnthropic can switch on an idle compaction of Claude Code's own, which does the\nsame job without asking. When it does, conPACT asks you once which one to keep:\nconPACT's, Claude Code's, or both.\n[How it works](docs/idle-toast.md#claude-codes-own-idle-compaction).\n\n### Checking the summary's sources\n\nA summary can turn a precaution the agent chose for itself, or another\nsession's request, into a rule that reads as yours. Every compaction conPACT\nstarts asks the summary to give each constraint its source. An optional\n`SessionStart` hook checks every compaction afterwards, whoever started it, and\ntells the resumed agent which constraints it traced to your words or an\ninstruction file and which it could not:\n\n```json\n\"SessionStart\": [\n { \"matcher\": \"compact\",\n \"hooks\": [ { \"type\": \"command\", \"command\": \"python /path/to/conpact/tools/compact_provenance.py\", \"timeout\": 60 } ] }\n]\n```\n\nMore: [docs/agent-workflow.md](docs/agent-workflow.md#keeping-the-summary-honest).\n\n## ChatGPT Desktop\n\nconPACT reads and measures ChatGPT Desktop's threads out of the box, without\nchanging anything. To compact the thread you are working in, which the app holds\nopen, install the sidecar with one click:\n\n```bash\npython tools/codex_sidecar.py window\n```\n\nthen restart ChatGPT Desktop. The same MCP tools can be registered for Codex\nthreads. What the sidecar is, what it touches and how to remove it:\n[docs/chatgpt-desktop.md](docs/chatgpt-desktop.md).\n\nCheck the installed Codex integration without changing anything:\n\n```bash\npython tools/doctor.py\n```\n\nIt checks the Codex login, MCP registration, sidecar, bundled Codex build and\nread-only thread access. A missing Claude Code Keychain login is informational,\nnot a Codex failure.\n\n## Codex CLI\n\nInstall one Codex Stop hook, then start the terminal UI through conPACT:\n\n```bash\nconpact-codex --install\nconpact-codex\n```\n\nIf that command is not on `PATH`, run `uv tool install --editable .` followed\nby `uv tool update-shell`, then open a new terminal.\n\nOn the first start, open `/hooks` and trust the conPACT hook. The launcher uses\nCodex's `--remote` option to connect the terminal UI to conPACT's existing\ntoken-protected loopback app-server. The token stays in an environment variable,\nnot the process arguments. All four MCP tools then work in the CLI, including\nturn-end `queue_compaction` and the idle toast.\n\nPlain `codex` remains unchanged; use `conpact-codex` for the integrated path.\nWithout an editable install, use `python tools/codex_cli.py`. See\n[Codex CLI setup](docs/setup.md#codex-cli).\n\n## Settings\n\n```bash\npython tools/settings.py # opens the settings window\npython tools/settings.py show\npython tools/settings.py set min_context_tokens 150k\n```\n\nOr click **Settings** on any toast. Every setting, its default and its range:\n[docs/settings.md](docs/settings.md).\n\n

\n \n \n \"The\n \n

\n\n## Safety at a glance\n\n- **It only acts on the session that asked.** No tool takes a target; the\n session is identified from the runtime, never from anything the model says.\n- **It only sends `/compact`.** There is no free-text sending, and a request\n fires at most once.\n- **The mod reaches only what it needs:** no process, no network, no file\n written. `claude plugin validate src/mod` lists every call it makes.\n- **The idle toast sends only what you click,** or what you switched that one\n session to do automatically.\n- **Your login token never leaks.** It is never printed, logged, or stored\n anywhere but its own file.\n- **The ChatGPT Desktop sidecar is opt-in and reversible.** Its control port is\n loopback-only and token-guarded.\n\nThe full model: [docs/security.md](docs/security.md).\n\n## Status\n\n| | |\n|---|---|\n| **Tests** | Windows 3,287 passed (2026-10-24); Linux 2,003 passed (2026-09-25); macOS 2,178 passed (2026-09-23) |\n| **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 |\n| **ChatGPT Desktop, live** | Sidecar compaction, turn-end arming, and a thread queueing its own compaction observed end to end |\n\nWhat has been observed, what has not yet, and the mutation scores:\n[docs/verification.md](docs/verification.md).\n\n## Documentation\n\n| | |\n|---|---|\n| [How it works](docs/how-it-works.md) | The goal, the Remote Control route, and why a request fires only after the final answer |\n| [Setup](docs/setup.md) | Stop hook, MCP server, the mod, Remote Control, sessions that were already open |\n| [The Claude Code mod](docs/claude-code-mod.md) | Compacting a session from inside Claude Code, without Remote Control |\n| [Idle toast](docs/idle-toast.md) | Stages, buttons, auto-compaction, holds |\n| [Settings](docs/settings.md) | Every setting, with defaults and ranges |\n| [Commands](docs/commands.md) | Every command-line tool |\n| [ChatGPT Desktop](docs/chatgpt-desktop.md) | Codex threads, the sidecar, and Codex Remote Control |\n| [Security model](docs/security.md) | What conPACT can and cannot do, and why |\n| [Architecture](docs/architecture.md) | Modules, entry points, state files, layout |\n| [Verification](docs/verification.md) | Tests, coverage, mutation scores, live evidence |\n\n## Contributing\n\nThe test suite needs `pytest`, `pytest-cov` for the mutation tester's own tests,\nand `jsonschema` for the MCP tool schemas:\n`pip install pytest pytest-cov jsonschema`, then `python -m pytest -q`.\nBefore changing how something works, read the two project records at the top of\nthe repository: [CHANGES.md](CHANGES.md) lists every change, newest first, with\nhow it was verified, and [DECISIONS.md](DECISIONS.md) lists every settled design\nchoice and the reason for it.\n\n[Lance Sandino](https://github.com/LanceSandino) contributed the macOS support,\nthe Codex CLI compaction and the read-only doctor, the macOS sidecar's move to\nChatGPT Desktop's new layout, and the check that confirms a Codex compaction\nwith a very large history record.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n"}