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 / CLAUDE.md files.
• 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:

• 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.

Tiers 1–2: 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:

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):

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 1–2 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.

See also

• Slash Commands - the full command reference, including /context, /compact, /compact-mode, /clear, and /model.
• Custom Agents - sub-agents with their own context windows.
• Checkpoints - the append-only session history compaction never rewrites.
• Memory - the memory files counted in the /context breakdown.