Compact the context automatically

Agents: claude, codex, opencode · On: phone, desktop

When a turn ends with the context over a token mark, VCode runs a compaction turn of its own before the next message goes in. You can set the mark for every tab in the settings sheet, or for one tab with /autocompact.

Why you would use it

A long thread gets slower and dearer with every turn, and eventually the agent runs out of window mid-answer. Compacting on a mark you choose keeps that from happening while you are not watching, and because it runs between turns it never lands in the middle of work.

How to use it

For every tab:

1. Tap the cog (#settings-open) and find the Auto compact group (#settings-autocompact).
2. Switch Enabled (#ac-enabled) on or off.
3. Set Context tokens limit (#ac-tokens), a number with a tokens unit beside it.
4. Optionally write a Custom prompt (#ac-prompt) saying what to keep.

Each field saves the moment it changes; there is no Save button. The status at the right of the group title (#settings-hint) reads Saving…, then a green check and Saved. A refused value shows in red there, for example a whole number of tokens, at least 10000.

The group's help reads Compacts tabs past the token limit., and the limit's row adds /autocompact overrides it per tab.

For one tab, type in the composer:

• /autocompact — reports this tab's mark
• /autocompact 120k — compact over 120,000 tokens
• /autocompact off — never compact this tab
• /autocompact default — follow the settings sheet again

What you see

A system card opens in the transcript before the compaction: auto-compacting: context at 168k, over the 150k mark, with a timer counting up beside it. The activity line says COMPACTING. When it is done the same card closes with the final duration; the 30-second heartbeats the CLI sends collapse into that one card rather than adding more. Codex reports its own contextCompaction system item, which renders as compacting context… and then context compacted.

If the compaction fails, the same card becomes a warning: auto-compact failed: <reason>.

The ctx segment in the status bar drops once it is done. Tapping that segment says context 168000 tokens · auto compact 150k tokens, or context 168000 tokens · auto compact default on a tab that follows the sheet.

/autocompact toasts its result, for example auto compact: 120k tokens, auto compact: off, auto compact: default.

Options and settings

Limits and known gaps

• The custom prompt is Claude only. Codex and opencode take no compaction instructions; the sheet says so under the field.
• Only after a turn that finished on its own. A turn you stopped, or one that errored or failed — including one a usage limit cut short — is not followed by a compaction.
• Never after a compaction turn itself: claude reports no usage on that turn, so the figure is still the old one when it ends and re-checking it would loop.
• The mark is re-checked at drain time, so a /clear or a handoff between the turn ending and the compaction cancels it.
• A usage limit reported after the turn closed cancels the pending compaction, so the retry is not queued behind it.
• Only on an agent whose channel supports compaction. All three do today.
• The compaction is a turn of VCode's own, so it costs tokens and takes time before your next message runs.
• /autocompact takes 120k, 120000, off, 0, default or auto. Anything else is refused with auto compact takes a token count like 120k, or off, or default. A bare decimal is refused: 0.1 would round to 0 and switch compaction off without anyone asking.
• The tokens field refuses anything under 10000.
• A message sent while a compaction runs waits: <agent> is compacting its context; the message runs when that ends. A steer during a compaction waits too.
• Once settings.json exists it wins over VCODE_AUTO_COMPACT, so a setting changed on the phone is not reverted by the next install.sh update.

Related

• clear-the-context — drop the context instead of summarising it
• status-bar — where the ctx figure lives
• activity-line — the COMPACTING label
• hand-a-tab-to-another-agent — the other way a thread starts fresh
• read-the-transcript — where the system card lands