Pi extension for Codex remote compaction on openai-codex models.
Long-lived coding sessions only work when compaction preserves the context that matters. Codex's model-native compaction is markedly better at this than replacing history with a local prose summary: it returns an opaque checkpoint that lets the model resume its own compressed state, including recent model-visible tool state.
In practice, this lets a single Codex session continue through repeated compactions without the gradual loss of continuity common with repeatedly summarized history. Results still depend on the selected model and Codex service; this is the intended benefit, not a fidelity guarantee.
Requires Node.js >=22.19.0, Pi >=0.80.10, and an openai-codex model.
pi install npm:@yeungkc/pi-codex-compact
/reloadFor a local checkout:
pi install .
/reloadConfirm that Pi registered the package:
pi listThen, in an openai-codex session, run /compact. A successful remote compaction displays ✓ OpenAI compaction complete. The checkpoint is stored in the local Pi session JSONL and is replayed on later requests.
No configuration is required. By default, the extension uses Codex remote-compaction V2 and automatically compacts retained history at 90% of the selected model's context window. The current user input is not included in this pre-request threshold check.
Optional configuration belongs in ~/.pi/agent/pi-codex-compact.json, or in a trusted project's .pi/pi-codex-compact.json. Pi loads the global file first; valid project settings override it. Missing or invalid fields leave the global or default value in place:
{
"remoteCompactionV2": false,
"tokenBudget": false,
"autoCompactTokenLimit": 128000,
"autoCompactScope": "total",
"fallbackBufferTokens": 0
}| Setting | Default | Meaning |
|---|---|---|
remoteCompactionV2 |
true |
Use Codex V2; set false only for the legacy V1 endpoint. |
tokenBudget |
false |
Use Pi's nearest token-budget compaction boundary. Pi cannot create Codex's true fresh token window. |
autoCompactTokenLimit |
90% of the model context window | Override the automatic-compaction threshold. |
autoCompactScope |
"total" |
Count estimated retained-history tokens; "bodyAfterPrefix" excludes a reliable prefix baseline when Pi exposes one. |
fallbackBufferTokens |
0 |
Add estimated tokens to the automatic-compaction threshold. |
The extension does not probe endpoints at runtime.
Where Pi exposes the needed lifecycle hooks, this extension follows Codex CLI's observable remote-compaction flow:
- Sends active Responses history followed by
{ "type": "compaction_trigger" }. - Uses V2 by default and persists the returned opaque
encrypted_contentcheckpoint. - Replays the checkpoint with the active Pi branch tail on later requests.
- Defers model-transition compaction until the first request after model selection.
- Runs automatic compaction before a provider request, not after an aborted turn.
- Retains recent eligible messages, drops old tool/reasoning items, caps retained agent messages at 10,000 tokens, and applies Codex V2's 64,000-token retained-message budget.
- Retries transient HTTP and stream failures. For eligible model/request failures during a transition, it retries with the newly selected model.
Unsupported providers keep Pi's normal local text summarization.
Codex CLI internally owns exact comp_hash capability metadata, token accounting, mid-turn continuation, and fresh token-budget windows. Pi does not expose those seams to extensions.
The extension therefore:
- fails closed when the persisted and selected models lack comparable compaction hashes;
- estimates history, stable system/tool prefix, images, and tool output for automatic compaction;
- uses Pi's closest token-budget boundary rather than inventing a local text summary; and
- treats the actual pre-provider request as authoritative when a fork has changed Pi's inherited history.
These are deliberate compatibility adaptations, not server probing or local-summary fallbacks.
pi update npm:@yeungkc/pi-codex-compact
pi uninstall npm:@yeungkc/pi-codex-compactRemoving the package does not delete existing Pi session JSONL files or their native checkpoints. Remove ~/.pi/agent/pi-codex-compact.json separately if it is no longer wanted.
pnpm install --frozen-lockfile
pnpm testIf this extension behaves unexpectedly in your Pi or Codex setup, fork this repository, install the fork locally with pi install ., and reproduce or diagnose the behavior in your own branch. Pull requests with a focused reproduction and tests are very welcome.
Do not include credentials or session JSONL content in an issue or pull request.