STEP 01
Measure pressure
Codex compares active token usage with the auto-compact limit and the model's usable context window.
Source-guided explainer
How Codex compacts context
When a thread grows too large, Codex swaps the model's working transcript for a smaller checkpoint. The saved rollout remains intact. What changes is the history sent into the next inference request.
The short version
Compaction is a checkpoint operation. Codex detects pressure, picks one of three compaction routes, replaces the active model history, and records enough state to resume from that new boundary.
01 / PIPELINE
The four moves
The details differ by provider and feature flags. The outer shape does not.
STEP 02
Choose a route
A token-budget reset wins first. Otherwise provider capability selects remote or local compaction.
STEP 03
Build a replacement
The new history contains a summary or opaque checkpoint plus selected messages and fresh context.
STEP 04
Checkpoint and continue
Codex advances the context-window ID, persists replacement_history, recalculates usage, then resumes work.
Model-visible history is the key phrase. The append-only rollout keeps the earlier events. Compaction changes the working set reconstructed for the model.
02 / ROUTING
Three routes share one lifecycle
Pick a tab. The current source checks these routes in this order.
Remote v2 returns an opaque checkpoint
Codex copies the current prompt input, attaches known tool calls, and appends a CompactionTrigger item. The provider must return exactly one ResponseItem::Compaction.
- The replacement retains selected recent user and hook messages, selected inter-agent messages, and optionally client-authored developer messages.
- Retained message text has a 64,000-token budget. Individual agent messages above 10,000 estimated tokens are excluded.
- The opaque compaction item is designed for continuation. Codex does not parse it into a human-readable summary.
before
assistant reasoning + output old
tool call / large result old
real user message retained
recent agent instruction eligible
↓ provider compacts
replacement history
selected recent messages ≤ 64k
opaque compaction item encrypted
Local compaction asks the model for a handoff
Codex appends its built-in checkpoint prompt, runs a normal model response, and treats the last assistant message from that compaction turn as the summary.
- The prompt asks for progress, decisions, constraints, preferences, next steps, and critical references.
- Codex carries forward recent user messages using a separate 20,000-token budget, walking newest to oldest.
- If the compaction request itself overflows, Codex removes the oldest history item and retries while preserving recent messages.
before
assistant + tools + outputs summarized
older user message budgeted
newest user message preferred
↓ model writes handoff
replacement history
recent user messages ≤ 20k
compaction summary user fragment
Token-budget mode starts a clean window
This experimental route skips model and server summarization. It rebuilds initial context from current settings and world state, then installs that as the replacement history.
- It still runs the same pre-compact and post-compact hooks.
- It may retain client-authored developer messages when that feature is enabled.
- It relies on model-managed notes and reminders for continuity. The compaction operation itself does not create a summary.
before
conversation history not carried
tool traffic not carried
assistant output not carried
↓ open new window
replacement history
fresh initial context settings
current world state full snapshot
03 / TRIGGERS
When it runs
Token pressure is the common case, but it is not the only reason Codex compacts.
Pre-turn
Before sampling starts
At the start of a user turn, Codex checks the existing history. If it is already at the threshold, compaction runs before the new input is recorded.
Mid-turn
Between tool-loop steps
After a model response, Codex compacts only when more work remains and the limit was reached or the model requested a new context window.
Model transition
Compatibility or size changed
A changed compaction compatibility hash triggers compaction. Moving to a smaller context-window model can also trigger it when current usage no longer fits.
Manual
/compact
The TUI exposes a direct command. It creates a standalone compaction turn and uses the same provider and feature routing as automatic compaction.
Default threshold geometry
auto = min(configured limit, 90% of context)
90% derived auto-compact point
95% default usable-context cap
reserved headroom
The two limits are independent. A custom auto-compact value is clamped to 90% of the model context. The usable-context percentage is model metadata and defaults to 95%. In
body_after_prefix scope, Codex subtracts the current window's initial prefix before comparing usage with the configured auto-compact budget.04 / CONTENT
What survives the boundary
Compaction preserves task continuity, not a verbatim transcript. Each route has different retention rules.
| Input | Remote v2 | Local summary | Token-budget reset |
|---|---|---|---|
| User messages | Selected and retained, newest-first budget when truncating | Recent messages retained within 20k tokens | Not carried by the compaction operation |
| Assistant and tool history | Compressed into the opaque provider item | Compressed into the handoff summary | Not carried |
| Developer messages | Optional for client-authored items | Reinjected as current initial context | Optional for client-authored items |
| Current settings and world state | Reinjected at the appropriate boundary | Reinjected at the appropriate boundary | Installed as full fresh context |
| Images | Budgeted retention behind a feature flag | Not copied into the text summary history | Not carried by the reset itself |
05 / PERSISTENCE
A checkpoint, not a deletion
The old rollout records stay on disk. Codex appends a CompactedItem that names the new model-visible starting point.
Resume can start from the latest compacted suffix
The checkpoint stores replacement history, window lineage, the remote response ID when there is one, retained review context, and a token-usage snapshot.
For paginated rollouts, the reverse scanner can stop once it finds a usable compaction plus completed turn context. It does not need to replay the thread from its first line.
live history := replacement_history
rollout log += compacted checkpoint
window number := window number + 1
rollout log += compacted checkpoint
window number := window number + 1
codex-rs/history/src/lib.rs · simplified
{
"type": "compacted",
"replacement_history": [
// selected messages + summary/checkpoint
],
"window_number": 4,
"previous_window_id": "…",
"window_id": "…",
"compaction_response_id": "resp_…",
"latest_token_usage_record": { /* … */ }
}
06 / LIMITS
What compaction cannot promise
The source has guardrails, but compression still trades detail for room.
≈
Token counts are partly estimated
Codex uses server usage when available and local estimates elsewhere. Exact trigger timing can differ from what a user infers from visible text.
≠
A summary is not the transcript
Tool outputs, intermediate reasoning, and older messages may survive only through compressed task-relevant information.
n+1
Repeated compaction compounds loss
The local route warns that long threads and multiple compactions can reduce accuracy. A focused new thread remains the cleanest reset.
One current edge: pre-turn compaction checks the history before the incoming user message and context updates are recorded. A source TODO says Codex does not yet estimate those pending items before deciding to compact.
Source trail
01context_window.rs · threshold calculation↗
02turn.rs · pre-turn, model-switch, and route selection↗
03turn.rs · mid-turn rollover and continuation↗
04compact.rs · local summary request and history replacement↗
05compact.rs · 20k recent-user-message budget↗
06compact_remote_v2_attempt.rs · CompactionTrigger request↗
07compact_remote_v2.rs · retained messages and 64k budget↗
08compact_token_budget.rs · fresh-window reset↗
09session/mod.rs · install and persist checkpoint↗
10model_context.rs · bounded resume scan↗
11Official OpenAI documentation · API compaction concepts↗