dsh-token-saver

DSH Token Saver

Trim oversized tool output to keep more of your DSH context window for the model.

A configurable token-efficiency plugin for DeepSeek Harness (DSH). It shrinks file reads, grep dumps, and command logs before they enter the conversation, and adds optional context-pressure handling, prompt shaping, local responses, and LLM-summary compaction.

简体中文 · Releases · Issues

Why

Tool output is the fastest way to fill a context window. A single file read or grep dump can add tens of thousands of bytes to a session, most of which the model never needed — and the tokens stay in the conversation for every later turn.

DSH Token Saver intercepts that output at the DSH tool-execution boundary: it keeps the head and tail of long results, folds grep output down to its matches, and compacts structured command output through RTK. Everything is configurable, and the extras (prompt shaping, RTK, local responses, LLM summaries) are off by default.

Quick install. Run dsh plugin --profile web add github:LoveDoLove/dsh-token-saver. See Install for pinned releases and build-script approval.

Features

Install

Install from the GitHub repository with DSH:

dsh plugin --profile web add github:LoveDoLove/dsh-token-saver

If your DSH installation asks for build-script approval, follow the approval instructions printed by DSH/pnpm and retry the install. Then reload or restart the target DSH profile as required by your installation.

The GitHub repository and GitHub Releases are the source of truth for this project. Use a version-pinned release when one is available.

Install the current v1.0.4 release explicitly:

dsh plugin --profile web add github:LoveDoLove/dsh-token-saver#v1.0.4

The prebuilt artifact dsh-token-saver-1.0.4.tgz is also available from the v1.0.4 release and can be installed as a local package without a local build environment.

v1.0.4 includes the DSH contract-compatibility fixes and keeps the grep-pattern fix (commit 8562f48) shipped in v1.0.3. The v1.0.2 release predates the grep-pattern fix.

How it works

DSH Token Saver hooks into the DSH tool-execution pipeline:

1. Post-execute hook — after a tool returns, oversized output is trimmed to head + tail or folded (grep results keep their matches; RTK compacts structured command output).
2. Context-pressure handling — when context pressure crosses the threshold, higher modes can trigger compaction before the next step.
3. LLM-summary compaction — in balanced/aggressive mode, an optional LLM summary can replace bulky output (requires a configured callLlm provider).
4. Prompt-cache stability — system-prompt sections are reordered so pinned, cacheable sections stay stable across turns.

All paths are fail-open: if an optimization errors, the original content is preserved unchanged.

Configuration

The settings panel is available in DSH Web under Settings → Token Saver. You can also configure the plugin through its DSH bundle configuration.

Example:

dsh-token-saver:
  mode: conservative # off | conservative | balanced | aggressive
  rtkEnabled: false
  cavemanLevel: off # off | lite | full | ultra | wenyan-lite | wenyan | wenyan-ultra
  ponytailLevel: off # off | lite | full | ultra
  localResponsesEnabled: false
  localResponses: [quota, prefix, title, suggestion, filepath]
  llmSummaryEnabled: false

Key options

Modes

• off — disables token-saving transformations. (RTK still runs when rtkEnabled: true.)
• conservative — trims/folds oversized tool output while retaining the normal DSH compaction path.
• balanced — enables additional context-pressure handling.
• aggressive — enables more extensive compaction behavior (including replacing the basic compaction provider by default); review the configuration before enabling it.

Exact behavior depends on the individual options and the installed DSH version. Check the settings panel and configuration defaults for the current build.

Statistics

The Web settings panel shows live savings telemetry, and the totals are persisted to ~/.dsh/token-saver/stats.json (or $DSH_HOME/token-saver/stats.json) so the dashboard still reports savings after a host restart.

• Saved — bytes reduced across all compaction passes.
• Saved ratio — saved bytes as a percentage of original bytes.
• Calls — compaction invocations that produced at least one trimmed block.
• Blocks — text blocks that were actually compacted.

The same tool output can be compacted twice — once by the post-execute hook and again by the LLM/stream path — so calls counts events and blocks counts compacted text. Saved bytes stay exact because per-pass savings add up to the total. Telemetry reads and writes are fail-open: a broken store must never affect compression behavior.

v1.0.2 introduced persistent cumulative savings. Earlier versions reset the dashboard to zero on every restart.

Safety behavior

• Fail open: if an optimization fails or produces an unusable result, the original content is preserved.
• Error output is preserved: tool results marked as errors are not compacted by the tool-output filter.
• Opt-in extras: RTK, prompt shaping, local responses, and LLM-summary compaction are independently configurable.
• No quality guarantee: token reduction can change the information visible to a model. Review settings carefully, especially for aggressive compaction.

Benchmark

Verified byte-reduction measurements on plugin v1.0.4 (DSH 0.2.1-rc.2, Node v24.22.0, Linux, mode conservative, rtkEnabled: false). Every scenario is a deterministic in-process call on synthetic input — no DSH session and no LLM request are involved. Full methodology and reproducible commands are in docs/benchmark-results.md; how to reproduce and report measurements is in docs/benchmark-methodology.md.

These are UTF-8 byte reductions of synthetic input passed through the compaction functions in-process. They are not model token counts, token-cost savings, latency improvements, or task-quality evidence. The production grep path now extracts the search pattern from exec.arguments (commit 8562f48); the 93.4% figure is the folding library's capability on a different, smaller input, not the default production-path result.

Reproducibility differs per row: the read-like, library-level, and RTK rows are reproduced by the committed npx tsx bench-tmp.ts script, while the two 29,321-byte production rows were measured on an input whose generator is not committed, so they cannot be re-run from this repository as committed. See Reproducibility status in the benchmark results document.

Compatibility

Designed to coexist with:

• Billion Context — ACP-marked content is preserved by the relevant output filter.
• OmniRoute — request routing fields are intended to remain intact.
• Our Free Model — detects the `` marker to avoid applying prompt shaping twice.

Compatibility depends on the versions and configuration of the surrounding plugins. Report reproducible issues with version details.

Development

Requirements: Node.js >=22.19.0 and pnpm.

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build

License

MIT. See LICENSE. Third-party-derived portions retain their required attribution; see the source and license notices for details.