Context compaction

Every model can only read so much at once: its context window. Long sessions fill it with messages, file contents and tool output. Hull manages this for you by compacting: it summarises the older part of the conversation and keeps working from the summary.

What the summary keepsCopy Anchor Link

The summary records the goal of the session, the constraints and preferences you gave, progress so far, key decisions, next steps, and the files involved. The most recent turns are kept word for word when they fit. If a session is compacted again, Hull updates the existing summary rather than starting over.

When it happensCopy Anchor Link

Automatically. Hull tracks how much of the window the session uses. It compacts when usage reaches compaction.threshold_percent (if you set one), or when the remaining space drops to a reserved safety buffer, whichever comes first.

• For models with a separate input limit, the buffer is 20,000 tokens or the model's maximum output, whichever is smaller.
• For models with a single context window, Hull reserves the model's full output allowance, up to 32,000 tokens.
• Custom models that don't declare a context window aren't tracked, so they aren't compacted automatically.

Pruning. Between turns, Hull also clears out old tool output beyond the most recent 40,000 tokens, replacing it with a short placeholder. This keeps large outputs from filling the window before a full compaction is needed.

Manually. Compact whenever you like, for example before switching to a different part of the task:

Configure itCopy Anchor Link

Set compaction options in hull.jsonc:

{
  "compaction": {
    "auto": true,                  // compact automatically
    "threshold_percent": 80,       // optional: compact at 80% of the window
    "prune": true,                 // clear old tool output
    "tail_turns": 2,               // recent turns to keep word for word
    "preserve_recent_tokens": 8000, // token budget for those turns
    "reserved": 20000              // safety buffer
  }
}

A lower reserved value means compaction happens later and you get more turns from the raw window, at a higher risk of overflowing mid-turn. A higher value compacts earlier and more safely.

Use a different model for summariesCopy Anchor Link

Summaries can use a cheaper or larger-context model than your main agent:

{
  "agent": {
    "compaction": {
      "model": "anthropic/claude-haiku-4-5"
    }
  }
}

Without this, the session's current model writes the summary.

Environment variablesCopy Anchor Link

TipsCopy Anchor Link

• Start with a clear task. A specific opening request makes for a better summary.
• Keep lasting context in AGENTS.md. Project conventions in AGENTS.md are loaded every time and never need summarising.
• Start fresh for unrelated work. A new session is often better than compacting an old one.