Reclaim a full context window with /compact

You are still on the same task, not switching projects, but the context window is crowded: long transcript, file bodies from earlier reads, test output still in history. The agent starts re-reading files it already saw. Starting a brand-new session would discard in-progress reasoning that never reached disk. Compaction keeps the thread and replaces much of the verbose history with a summary.

A session is the saved Codex conversation (codex resume restores it). Compaction operates inside that session. It does not change files on disk; see resume for the distinction between transcript and working tree.

Condensing the thread

/compact

Codex offers to summarize the chat so far; you confirm. Compaction tends to keep the current goal, decisions reached, recent turns, and the latest picture of the code. It tends to drop bulk: full file bodies read hours ago, verbose command output, abandoned approaches. Those are tendencies, not a contract you can inspect line by line.

After compaction you typically see a marker such as Context compacted in the history. The summary text itself is not printed in current builds; making it visible in the transcript is an open request, not a shipped audit trail. You choose the moment; you do not get to proofread the summarizer’s draft.

Automatic compaction can also run as the window nears its limit (marker may say automatically). That fires when capacity is tight, not necessarily at a clean boundary in your work. Prefer choosing /compact yourself between steps when you feel the squeeze.

How much room returns? Treat exact ratios as illustrative, not product guarantees. In the widget’s simulated session, a deliberate compact might move modeled occupancy from about 150k tokens toward about 35k: a summary block, recent turns kept verbatim, and standing overhead compaction does not remove. The widget dramatizes the shape of that trade; it is not a measurement of your session.

Watch the stakes before the rule. The replay below x-rays a filling window and pauses for your choice among continue, compact, or clear. Generic command names appear in the scene; in Codex the condense move is /compact.

An illustrative session, played back with its context window x-rayed. Watch what the work costs on the right; when the playback pauses, you decide what the session does next - then replay the other choices.

0k / 200k

Fixed overheadRulesConversationFile readsTool outputSummaries

agent session - billing-app

agent cli · new session · repo: billing-app

the window, x-rayed

Every number is an illustrative order of magnitude, and the commands answer to different names across tools - /compact, /compress, or /summarize; /clear, /new, or a fresh chat. The outcomes are constructed possibilities, not predictions. Choose based on the task and verify what survives.

Run /status after compacting if you want the aggregate context line on the same thread; see status for how to read it.

What compaction can’t do

Compaction is lossy. Details that exist only in chat (the exact conversion you settled on, why one approach beat another) can flatten into a generic line. Save first, then compact: commit, branch, or sketch in a file anything you cannot afford to lose.

Durable project rules belong on disk anyway. In budgetcli (the course’s running example, a small self-hosted personal-finance API in Python and FastAPI), integer-cents handling lives in AGENTS.md at the repo root and reloads every session without depending on the transcript. Compaction is for transient working context; git and project docs are for what must survive any reset or summarize pass.

Automatic and manual compaction address conversation weight - old file bodies and spent exchanges are exactly what they reclaim. What compaction does not shrink is standing overhead: connected MCP schemas and a long rules chain reload or persist regardless. If the window is full mainly from that standing overhead, or from reads that keep recurring turn after turn, diagnose with /status and your own accounting before compacting working context away - you would be shrinking the part that was not the problem.