Copy Page

Context & Compaction

Every model has a context window - a fixed token budget that has to hold the system prompt, your memory files, tool definitions, skills, and the entire conversation so far. Long sessions fill it. Command Code manages that budget for you: it shows you exactly where tokens are going (/context), automatically compacts the conversation in progressive tiers before the window overflows, recovers on its own when a request comes back "prompt too long", and tracks how many tokens compaction has reclaimed across the session.

This page is the complete reference: the window, the /context breakdown, the auto-compaction tiers, /compact and /compact-mode, savings tracking, automatic recovery, model switches, and the habits that keep context lean in the first place.

The context window

Everything the model sees on a request counts against one budget:

System prompt - Command Code's identity, behavior, and security instructions.
Memory - your AGENTS.md files, across every memory tier that exists.
Taste - your taste.md, when taste learning is on.
Tool definitions - every built-in tool schema, plus one schema per connected MCP tool.
Skills and subagents - the loaded skill catalog and agent definitions.
Messages - the conversation itself: your turns, the model's turns, and every tool result (file reads, shell output, search results). This is what grows.

The window's size depends on the model - switch with /model and the budget changes with it. Command Code reads the active model's limit fresh on every check, so a mid-session switch immediately recalibrates everything below.

The status-bar indicator

You don't have to run a command to know where you stand. The small context indicator next to the input stays hidden while there's plenty of room, then appears once you're within 20 percentage points of the auto-compact threshold (which fires at 90% of the window - see below), as a small bar counting down the percent left. On very large-window models it shows an earlier plain-text token count once usage passes ~180k tokens - a nudge that /compact is worth running for response quality long before a 1M window is at any risk of overflowing.

`/context` - where the tokens are going

Run /context at any time for a full accounting of the window:

The progress bar - tokens used, the model's limit, tokens remaining, and the percentage, colored by pressure (normal warning at 50% danger at 80%). The numbers use API-reported ground truth from the last request when available; before the first request (or right after a resume) they're local estimates, and the view says so.
Distance to auto-compact - once usage passes 40%, a line shows roughly how many tokens remain until the summarization tier fires ("~52k until auto-compact"), escalating in tone as it gets close.
The per-section breakdown - one row per bucket, largest first:

Row	What it measures
System prompt	The assembled system prompt, measured per-section by the server at prompt-assembly time (falls back to a computed residual on the first turn).
Memory	Your memory files. If you've edited an `AGENTS.md` since the last request, the row is flagged (modified, refreshes next request).
Taste	`taste.md`, when present.
System tools	All built-in tool schemas, with a count.
MCP	Every connected MCP tool schema, labeled with the server names.
Skills	Loaded skill catalog entries.
Subagents	Loaded agent definitions.
Messages	The conversation itself - with user/assistant message counts.

Tips - context-aware suggestions generated from the actual numbers: /compact before the summarize tier fires, a warning when conversation dominates the window, a note when MCP tool schemas are a big fixed cost, image counts (~1.5k tokens each), or a nudge to start a fresh session after a very long one.

Auto-compaction

Command Code compacts reactively, in progressive tiers, keyed to the fraction of the active model's window the last turn actually used. The check runs before each model call; each tier only engages when the pressure has passed its threshold.

 window used                    fires
 
   0%                          quiet
      
  40%  /context starts warning
      
  50%  TIER 1  keep last 20    fast
                  tool calls    only
      
  80%  TIER 2  keep last 10    fast
                  tool calls    only
      
  90%  TIER 3  summarize       always
                  older turns
 100%  overflow (never reached)

Copy

Tiers 1 and 2 only run when /compact-mode is fast. In the default mode nothing happens until 90%, then Tier 3 summarizes.

Tier	Fires at	What it does	When it runs
1	50% of the window	Trim the transcript to the last 20 tool calls (only when more than 20 exist)	`fast` compact mode only
2	80%	Trim to the last 10 tool calls	`fast` compact mode only
3	90%	Summarize older messages into a handoff brief	Always, in any compact mode

Tiers 12: tool-call trims

The trim tiers are pure and model-free: they remove whole tool_use/tool_result pairs - the oldest first - and nothing else. Your messages and the model's prose survive; only stale tool output (old file reads, old command output) is dropped. These tiers only run when /compact-mode is set to fast; in the default mode Command Code skips straight to summarization at 90%.

Tier 3: summarization

At 90%, Command Code makes a real model call that compresses the older part of the conversation into a structured handoff brief - goal, a walk through your turns, in-flight work, pending tasks, files touched, decisions made, errors hit, and the exact resume point. The brief replaces the older messages; you'll see it in the transcript prefixed with "This is an auto-compacted summary of the earlier conversation".

Summarization is deliberately conservative:

The recent tail survives verbatim: Roughly the last 30k tokens of conversation are never summarized (and never less than the last 3 messages), split at a clean turn boundary - the active exchange always survives intact.
Skill content is exempt from every tier: A loaded skill's instructions are re-injected deliberately and must keep steering the session, so skill messages are carried through compaction verbatim - never trimmed, never folded into a summary.
Images are kept verbatim: A summary can't reproduce pixels, so the keep-boundary moves back to the first image and everything after it survives as-is.
Old summaries never feed new ones: A prior compaction brief is dropped and replaced, not re-summarized.
It fails open, with fallbacks: Fewer than 5 older messages nothing to summarize, the transcript is left intact. The summarizer model call is retried on transient errors and falls back once to a second model if the compaction model's upstream is down; if the summary still can't be produced, Command Code falls back to a Tier-2 tool-call trim rather than leaving the window full. A failure never loses conversation.
Scratchpad files are indexed, not lost: The brief carries a small manifest of the session-scratchpad files that survive on disk (names and metadata only), so post-compaction turns still know what's there.

Your original log is never rewritten

Compaction changes what is sent to the model, not what is stored. The session log is append-only: a compaction is recorded as its own entry in the session tree, pointing at the summary and the first kept message. Your full history remains on disk - checkpoint restore, /rewind, and session forking still see everything.

When it fires

When the summarize tier engages you'll see a status line while it runs, then a feed entry reporting the result:

Compacted conversation. Saved ~41,300 tokens (total ~112,000 this session).

Copy

Every compaction event - auto, manual, or model-switch - reports its own savings and the session's running total. The totals are persisted to the session's metadata as they accrue, so they survive a restart: resume with --resume and the "total ~N this session" figure keeps counting from where it left off.

`/compact` - compact on your terms

/compact runs the same Tier-3 summarization immediately, without waiting for the 90% threshold. The best time to run it is before auto-compact fires - the /context tips start suggesting it at 50%, and urgently past 80% - because compacting at a moment you choose (a task boundary, right after a conclusion is reached) gives the summarizer a clean story to compress, instead of whatever mid-task state the threshold happens to catch.

After a compact, the reported context usage restarts against the model's window; if there was nothing worth compacting you'll get "Conversation is already compact." A failure reports an error and leaves the conversation untouched.

`/compact-mode` - how aggressive auto-compaction is

/compact-mode selects between two auto-compaction strategies (also available in /config; the choice persists in your user config):

Mode	Behavior
`default`	Summarize-only. Nothing happens until 90%, then Tier 3 summarizes. Maximum context fidelity - every tool result stays available until the window genuinely runs out.
`fast`	All three tiers. Old tool results start being trimmed at 50% (keep last 20) and 80% (keep last 10), before summarization at 90%. Leaner requests and cheaper turns in long tool-heavy sessions, at the cost of older tool output leaving context earlier.

The setting is read live - a mid-session switch applies from the next check.

Automatic recovery and model switches

"Prompt too long" never fails the turn

If a request is rejected by the provider as too long - usage estimates drifted, or a single giant tool result blew past the window - Command Code doesn't surface an error and stop. The error is classified, the window is compacted (summarized) on the spot, and the request retried once with the compacted transcript. Only a second consecutive failure surfaces. In practice the reactive tiers fire first and this path stays rare; it exists so the edge case costs you a retry, not a turn.

`/model` recalibrates - and can pre-trim

The tier thresholds are fractions of the current model's window, re-read on every check, so switching models instantly moves the goalposts:

Switching to a larger window simply gives you more headroom; nothing is touched.
Switching to a strictly smaller window when usage already sits past 90% of the new window triggers a proactive summarization immediately, before your next message - so the first request to the smaller model can't overflow it. The switch notice reports what the trim reclaimed, and it counts toward the session's savings total like any other compaction.

Keeping context lean

Compaction is the safety net, not the strategy. The cheapest token is the one that never enters the window:

Delegate research to sub-agents: A sub-agent launched with the agent tool (like the built-in Explore agent) burns its own context window reading files and searching, and only its final report enters yours. Sweeping a codebase in the main session can pull tens of thousands of tokens of file contents into your window; the same sweep delegated costs you a few hundred.
/clear between unrelated tasks: Finished one piece of work and starting another? A fresh conversation beats dragging the old task's tool results along - and beats making a future summary of two unrelated tasks compete for space. Use /clear at real boundaries (memory files and skills are re-loaded; the conversation restarts).
Point at files instead of pasting: Pasting a large file into the prompt puts it in the window forever - it's part of your message and survives every trim tier. Giving a path lets Command Code read it as a tool result, which Tier 12 trims and Tier-3 summaries can later reclaim. The same goes for the model's output: have it write large intermediate results to the scratchpad (or project files) and pass paths around - compaction's scratchpad manifest keeps an index of what's on disk, and the data itself never occupies the window.
Disconnect MCP servers you aren't using: Every connected server's tool schemas are a fixed cost on every request. /context shows exactly what each is costing; /mcp manages them.
Watch images: Each image in context costs ~1.5k tokens and is deliberately never summarized away.
Compact at boundaries, not under pressure: A /compact right after finishing a sub-task produces a better brief than an auto-compact in the middle of the next one.