Context compaction
Compaction lets a long conversation continue by replacing older history with a shorter handoff.
Automatic and manual compaction
fx compacts automatically when a model request reaches 80% of its usable input window, then continues the same prompt. The usable window excludes tokens reserved for the model's response.
Set auto_compact_percent to an integer from 10 to 80 in ~/.fx/settings.json to start earlier. The default is 80; this is a personal setting, not a project .fx.json field. The FX_AUTO_COMPACT_PERCENT environment variable overrides the setting, and fx ignores a value outside that range.
If the provider reports a context overflow before returning text or a tool call, fx compacts and retries once, and the status line shows Conversation too long · compacting, then retrying. If the request is still too long, the shell waits with Still too long after compacting · press Esc and shorten your message. When a provider rejects a request with images as too large, fx first retries with fewer images; see Request size.
Run /compact between prompts to compact immediately:
/compactThis works below the automatic threshold and does not start another prompt. With no history to compact, fx makes no model request. On a subagent's screen, /compact compacts that subagent's conversation and saves the result in its session.
What fx keeps
fx keeps up to four of the newest turns unchanged and compacts everything older. It cuts only between complete tool steps, so each tool call stays with its result. The turns it keeps can use 40% of the room the conversation aims for right after compaction. That room is 20% of the usable input window, or half the compaction threshold when that is smaller, less the instructions and tool definitions that every request carries.
In the compacted part, each turn keeps your messages, including ones you sent while it ran, and the assistant's final reply word for word. The model writes notes for the rest: what the assistant did, why it made each tool call, and what the call showed. The notes also keep the session's rules, facts, decisions, and status as numbered entries that later compactions only add to. fx checks each note against the saved turns and tool calls and marks any claim it can't confirm, so the agent checks it before relying on it.
fx aims to keep the compacted conversation, with the turns it kept and the request's instructions, within half the compaction threshold. When the compacted text would go past that, fx shortens the longest messages and replies, and each shortened text names the saved turn that keeps it whole.
fx saves every compacted turn word for word as M1, M2, and so on, and every tool call with its result as T1, T2, and so on. The agent can open and search them with read_tool_result. From the second compaction on, fx saves the previous compaction whole as L1, L2, and so on, and the model writes one summary that stands in for all of them. The rules, status, and open entries that still apply carry over word for word.
Requests and saved history
Automatic compaction asks the conversation's model for its notes in a request that repeats the pending conversation with the same instructions, tools, and settings, so the provider can reuse its prompt cache. /compact, compaction after a context overflow, and an automatic attempt that fails or doesn't fit send a separate request instead, with the model's reasoning turned off or at its lowest level. If that request fails or returns nothing, fx tries once more through AI Gateway with a model from another family: openai/gpt-6-sol when the conversation uses an Anthropic model, and anthropic/claude-sonnet-5 otherwise. A large history may take several requests.
Compaction requests never use Ultrafast. They count toward your provider usage and may add cost. See Usage and costs.
Compaction does not delete the original conversation. Full detail loads earlier turns from the saved session, one compaction at a time. fx switches to the compacted context only after saving its checkpoint. If that fails, it keeps the previous context.