Introduction

In agent development, handling what happens after the context window fills up is a common pain point. Traditional summarization and compression is usually lossy, causing models to forget details, and quality degrades with each compression. After version 0.153.0, Codex introduced a new context window management model: instead of compressing frequently, it “window-swaps” near the threshold by discarding the entire old window and loading a fresh initial context, relying on notes and searchable history to preserve details.

dsh-context-window is a DSH plugin maintained by CooperZhuang, designed to replicate this mechanism. It contains three core components: token budget prompts, a new_context tool callable by the model, and budget accounting with threshold throttling.

Core Features

The plugin provides two window-swap modes (resetMode):

  1. resetMode: handoff (recommended): no-summarization window swap. When swapping, it directly writes a handoff checkpoint (including objective, tasks, notes, last request), does not produce a compaction event, and the model knows where the old content is.
  2. resetMode: seam-region: delegates to ctx.compaction.compactRegion to perform full replacement. This follows the traditional summarization and compression path, and the row needs to be mounted in the agent preset’s compaction realm.

Installation and Enablement

Install using the official command; the plugin defaults to enabled: false, so adding it does not change the current behavior.

dsh plugin --profile web add dsh-context-window

When configuring, write the following in the profile’s cordis.patch.yml or mount line:

- id: context-window
  name: 'dsh-context-window'
  config:
    enabled: true
    resetMode: handoff
    noticeThresholds: [25, 50, 75]
    effectiveContextWindowPercent: 95
    autoCompactTokenLimitRatio: 0.9
    fallbackBufferTokens: 8000
    reminderThresholdTokens: 16000
    bodyAfterPrefix: true
    toolEnabled: true
    toolName: new_context
    notesToolEnabled: true
    notesToolName: notes

Model Interaction

The model receives window prompts and the window-swap tool.

1. Window Prompt
A prompt is injected when a window is opened, including the current window ID and the remaining token count.

2. Window-swap Tool
When the model calls the new_context tool, the following text is returned:

A new context window will start without summarizing conversation history.

3. Notes Tool
When the model calls the notes tool, the following text is returned:

Noted (1/8 notes retained for the next window).

4. Handoff Checkpoint
In resetMode: handoff mode, after the window swap, the first message in the new window is context_handoff:

<context_handoff>
Context window 1 (id 0199…) ended; this is context window 2 (id 0199…).
The messages of the previous window are gone. The state below was carried over verbatim.

<objective phase="active">
修复换窗后没有任务状态的问题
</objective>

<remaining_work>
- [~] 补 history 工具
- [ ] 真机挂载冒烟
</remaining_work>

<notes>
- seam 禁止不平衡切点，换窗只能落在 step 边界
</notes>

<last_human_request>
继续之前的工作
</last_human_request>
</context_handoff>

Known Limitations

When using the plugin, note the following:

  • Mount constraints: ctx.compaction is isolated by realm. seam-region mode requires mounting the row in the agent preset’s compaction realm; handoff mode does not require a backend and works on the host plane.
  • Boundary limitations: window swaps can only occur at step boundaries. DSH compression seams enforce tool-pairing balance and do not allow cutting through in-flight tool calls.
  • Metering heuristics: the token meter is heuristic (4 characters/token); CJK text and JSON schemas are underestimated, so thresholds trigger later than expected.
  • UI invisibility: handoff mode does not produce compaction/* events, is not visible in UI compaction statistics, and is only recorded in logs.
  • Non-persistent baseline: baselinePrefillTokens exists only in memory; after a process restart, body_after_prefix degrades to total.

Summary

dsh-context-window provides an explicit restart-based context management approach. By using the handoff mode, it explicitly writes handoff content into the new window, avoiding information loss from implicit summarization and compression. It is an MIT-licensed open source project, suitable for developers who need to maintain context continuity in complex long-conversation scenarios.

GitHub repository