Introduction¶

DeepSeek-style agents in long-running tasks spend over 80% of their prompt tokens on two types of content: first, large files read in a single pass (such as a 1MB migration SQL file), and second, grep results that are repeatedly searched and spliced back in. As a result, the context window is filled quickly, affecting reasoning quality.

dsh-token-saver is a Cordis plugin designed for DeepSeek Harness (dsh). It is maintained by developer Shaw529 and licensed under the MIT License. Its core goal is to achieve aggressive and lossless token savings by mounting extension points without breaking task effectiveness.

Core Features¶

The plugin implements token optimization through three extension points:

• tools/post-execute: Performs lossless head-and-tail trimming and grep folding. By default, the head and tail portions are preserved, while the middle is replaced with metadata, and the model can still perceive that the content has been truncated.
• agent/pre-step: Delegates to dsh’s official ctx.compaction mechanism to automatically compact the context when the pressure threshold is triggered.
• Optional features: Supports stable sorting of prompt-cache sections to improve cache hit rates.

Installation¶

Make sure DeepSeek Harness is installed. Run the following command in the harness home directory to install:

dsh plugin --profile web install dsh-token-saver

Install with a pinned version:

dsh plugin --profile web install dsh-token-saver@0.1.0

Prerequisites: Node.js version >= 22.19.0 is required.

Configuration¶

Add the plugin configuration to cordis.yml. The following is an example of the default configuration:

- name: 'dsh-token-saver'
  config:
    mode: balanced
    headBytes: 16384
    tailBytes: 8192
    grepMaxMatches: 30
    grepContextLines: 2
    grepHeadBytes: 8192
    grepTailBytes: 4096
    pressureThreshold: 0.5
    compactPressureThreshold: 0.5
    llmSummaryEnabled: false
    llmSummaryMaxInputTokens: 16000
    replaceBasicCompaction: false
    includeToolNames: []
    excludeToolNames: ['interaction.ask_user', 'interaction.confirm']
    cacheStableSections: ['agent-identity', 'user-instructions', 'tool-list']
    telemetry:
      onFold: |
        (event) => logger.info({ kind: 'fold', ...event })
      onCompact: |
        (event) => metrics.histogram('tokens.saved', event.savedTokens, ['engine', event.engine])

Description of key configuration options¶

• mode: Mode selector; the default is conservative.
• headBytes / tailBytes: Number of bytes to preserve at the head and tail of tool results.
• llmSummaryEnabled: Enables the LLM summary engine (recommended to turn on in balanced or aggressive mode).
• excludeToolNames: Blacklist to prevent truncation for certain interactive tools.

Modes and Effects¶

The plugin provides four modes, configured via the mode field:

Conservative mode: It does not replace the native dsh processing pipeline at all; it only performs lossless head-and-tail folding on tool results, ensuring zero loss to task effectiveness.

In a benchmark test covering eight real-world scenarios (estimated based on a 4 chars/token rule), the plugin performs as follows:

• Conservative mode: Saves approximately 97.6% of tokens on average.
• Balanced mode: Saves approximately 98.5% of tokens on average.

The scenario with the highest savings rate is the mixed session (12 tools): the original token count was about 2 million, reduced to about 35,000 after compression in balanced mode.

Notes¶

• Compatibility: Conservative mode does not modify the native dsh pipeline and is suitable for scenarios with extremely high stability requirements.
• Runtime environment: It must run in a Node.js >= 22.19.0 environment.
• Ecosystem context: DSH’s philosophy is “everything is a plugin.” This plugin is a community project and has no official affiliation with DeepSeek.

Conclusion¶

By intervening after tool execution and before subsequent steps, dsh-token-saver intelligently compresses and folds tool output results, significantly reducing token consumption in long-running tasks. For agent tasks that need to process large files or large numbers of search results, this is an optimization approach worth trying.

Project repository: GitHub