Preface¶

When running coding agents with DeepSeek Harness (dsh), the session quickly fills up with tool calls, file contents, and reasoning processes. Once the context window approaches its limit, the default backend @deepseek-ai/dsh-compaction-basic will invoke the model again to summarize the old history into a single paragraph. Summarization requires waiting for inference and consumes tokens, and file paths, commands, and identifiers may even be rewritten into “approximate” expressions.

dsh implements compaction as a replaceable capability: the service is defined in @deepseek-ai/dsh-compaction (ctx.compaction), the built-in implementation is dsh-compaction-basic, and manual triggering uses dsh-command-compact (/compact). The official documentation states that only one implementation can be loaded per context, so switching engines does not require modifying the Harness source code—just swap the plugin.

The community plugin dsh-compaction-instant takes a different approach: it does not call the model. Following the conversation compilation idea from lllyasviel/VCC, it organizes old history into a checkpoint containing only the original text, and the truncated content is pointed back to the append-only session log via seq pointers. This article is organized based on the plugin directory page, GitHub README / package.json, and the official DeepSeek Harness compaction documentation, verified as of August 18, 2026.

What is This¶

dsh-compaction-instant is a session and message plugin for DeepSeek Harness. The directory page lists it as maintained by KitDoesIt, with the repository at KitDoesIt/dsh-compaction-instant and the MIT license. The directory page’s one-sentence description is: Lossless compression engine without LLM, compresses context without losing information. The repository README is more precise: the checkpoint only contains the original text, all omitted parts have source markers, and the full content remains in the persistent log, so it is positioned as near-lossless, rather than stuffing the entire history verbatim into the context.

It replaces the built-in summarization engine @deepseek-ai/dsh-compaction-basic. Compression happens during millisecond-level text processing, without sending summarization requests or occupying KV cache. The /compact command is backend-agnostic and remains available after switching engines.

As of verification (2026-08-18), both the directory page and GitHub repository have 7 stars; the repository package.json version is 0.1.4, requiring Node.js >= 18. The public latest version of the同名 npm package dsh-compaction-instant at that time was 0.1.3. The directory page uses the GitHub source, while the alias installation in the README resolves via npm, so versions on the two sides may differ. Confirm the actual resolution result before installation.

The core philosophy of DeepSeek Harness is “everything is a plugin”. The referenced plugin directory deepseek-harness-plugin.com is an independent community site and has no official affiliation with DeepSeek / Horizon Robotics. Do not treat it as an official app store.

Core Features¶

1. Deterministic Compilation Without Model Calls¶

Compression performs a deterministic scan over the shadowed interval: no network, no model, no summarization prompt. The same input will produce the same checkpoint. The summarizationProvider / summarizationModel fields are retained for compatibility with official configurations, but have no effect.

The compilation example provided in the repository (user request, assistant reply with tool calls, followed by another question) is as follows:

[user]
please fix the bug
[assistant]
on it
* read "a.js" (seq 2 -> result 3)
[user]
next question

The rules can be summarized into several points:
- Each tool call only takes up one line. Whitelisted tools (toolArgTools, including read / write / edit / glob / grep / bash / shell / web_search / skill / subagent, etc.) display key parameters, while others only show the name, and tools in hideTools are omitted entirely.
- Tool results do not take up an entry; they rely on the -> result N pointer, which can be retrieved with a single recall(type:"result") call.
- Overly long user/assistant texts are truncated according to the budget, with ...(truncated from seq N) appended at the end.
- Reasoning is not retained by default; set includeReasoning: true to include it in the checkpoint.
- When earlier checkpoints are pruned due to space constraints, a [checkpoint N] marker (with 1 being the oldest) will be left, rather than disappearing silently.

There are two budget limits: the token count, and the character limit of budget × 4, to prevent base64 or compressed files from bypassing truncation. When exceeding the budget, the oldest tool lines are deleted first, followed by the oldest other entries, and conversation text will not be displaced by tool calls; the latest content is prioritized for retention.

2. Near-Lossless: Omissions Are Labeled with Seq Numbers, Full Content Is Retrievable From the Log¶

“Near-lossless” does not mean the checkpoint equals the full text, but rather:
- The checkpoint only contains the original text, with no rewriting or fabrication.
- Every omission points to the seq in the persistent log.
- Old checkpoints are copied verbatim, without being summarized a second time.

The same package also includes a recall layer for both models and humans:

recall can retrieve text, reasoning, complete tool parameters, and nested tool results. The default maxRecallTokens is 16000, and overages will be truncated and labeled; the search function displays up to 50 results by default (maxSearchHits). These two plugins are standalone, read-only logs that can be attached to any compression backend. There is also a RECALL guide at the start of each checkpoint, telling the model how to use recall / search.

3. Contract-Compatible, Can Replace the Built-in Engine¶

The repository states that it is a contract-level replacement for compaction-basic: it uses the same ctx.compaction interface, the same injection list (llm, tokenMeter, sessions), the same event and error vocabulary, and bills via the same ctx.tokenMeter. If compression fails to reduce the apparent context size, the checkpoint will be rejected. The optional toolResultPruner is also compatible: the pruner organizes and retains the tail content, while this engine handles the old intervals that have been shadowed.

Some default values differ from basic, and behavior will change after switching engines:

Manual /compact will retain the most recent original text according to manualRetainRatio (default 0.05), and the ongoing conversation content will not be entirely pruned.

Starting from version 0.1.4, deployments with a settings field (standard web/desktop profile) will show a compaction-instant card in Settings → Plugins, where you can modify checkpointScale, checkpointCap, maxTokens, auto, debug, and debugLogPath. Changes are written to settings.yaml and overlaid on the Cordis configuration. The card is included in the client bundle, so you need to restart dsh web once after installation. If npm still has version 0.1.3 as the latest, this option will not be available.

4. Compression Rate Provided in the Repository README¶

The figures below are from the repository README, tested on the development session of this project itself, with no entries lost during compilation, only entry-level truncation and tool call line consolidation, as a percentage relative to the original tokens. This is not a third-party evaluation: tool-dense sessions will see significantly better results, while pure text sessions will see less impressive compression.

The main sources of compression are: tool results do not take up entries, tool calls are condensed into one line (max 128 tokens), and reasoning is omitted by default. Pure text only achieves about 1.5x compression, mostly from removing JSON wrappers and truncating the longest blocks. The README also notes the tradeoff: the information density of narrative long conversations may be lower than LLM summarization, because long sentences are truncated rather than merged.

The default deployment checkpointCap is 65536. For the same 2.52 million token tool-dense session, this cap will retain approximately 2.2%, losing a large number of old entries; to retain all entries, the checkpoint needs to be around 226,000 tokens. When you need a more complete history, you should increase checkpointCap / checkpointScale, or rely on recall, rather than assuming that “compression will equal the full text by default”.

Installation and Activation¶

The installation command given on the directory page is as follows, executed in the DeepSeek Harness terminal:

dsh plugin add github:KitDoesIt/dsh-compaction-instant

For a reproducible installation, fix the commit hash:

dsh plugin add github:KitDoesIt/dsh-compaction-instant#<commit>

The directory page also notes: the plugin runs with the permissions of the current dsh process, and may execute code during installation. Inspect the source repository and license before installing.

Executing just the above command may not actually replace the built-in preset engine. The repository README explains: dsh currently does not have a “select compression engine” switch, and the built-in presets standard / code / cordis hardcode the package name @deepseek-ai/dsh-compaction-basic. To use the plugin, follow one of the three options from the README, all installed via the plugin manager (it runs pnpm in the profile directory). The example uses --profile web, adjust for your own profile.

Method 1: Alias to Replace the Built-in Engine¶

Built-in presets resolve package names from the profile’s node_modules (higher priority than the Harness built-in installation). Install this package under the built-in name, and standard / code / cordis will load it automatically, without modifying the preset files:

dsh plugin --profile web add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-instant"

Delete this alias dependency to revert to the official basic engine.

Alias installation will not be recognized as a dsh.bundle (Harness still resolves via the official package name in its own directory, which has no bundle declaration). The recall tool and /recall command need to be manually added to the profile’s cordis.patch.yml, placed in the insert list. The file supports hot reloading, no restart required. Use the alias package name for the entry names:

- id: compaction-basic
  disabled: true
- insert:
    - id: compaction-instant
      name: '@deepseek-ai/dsh-compaction-basic'
    - id: tool-recall
      name: '@deepseek-ai/dsh-compaction-basic/tool'
    - id: command-recall
      name: '@deepseek-ai/dsh-compaction-basic/command'

The engine line is optional, mainly used as a host fallback for presets without compression configuration (such as minimal).

Method 2: Direct Installation, Then Duplicate a Preset¶

dsh plugin --profile web add dsh-compaction-instant

Starting from v0.1.1, the package declares a dsh.bundle, and direct installation will automatically become a profile-level layer: it disables the built-in summarization entry and inserts this engine and the recall tool (see the package’s cordis.patch.yml). The host does not need to manually write a patch.

The built-in presets themselves still hardcode basic. Open a session using the built-in cordis preset (creative mode) and ask the model to:

Duplicate the standard preset, replace its compression engine line with dsh-compaction-instant.

The README workflow is: use agentPresets.copy to create a local copy, modify the name of the compression line, verify the mount with standingKeyFor, and point agent-presets config.default to the new preset if needed. A new preset will appear in the selector, while the built-in presets remain unchanged.

Method 3: Direct Installation, Then Manually Modify a Preset Duplicate¶

First run dsh plugin --profile web add dsh-compaction-instant as before, then duplicate the built-in preset, do not modify the Harness built-in preset files:

mkdir -p "$DSH_HOME/.agent-presets/<id>"
cp <built-in preset path>/agent.cordis.yml "$DSH_HOME/.agent-presets/<id>/agent.cordis.yml"

Write preset.yml next to it (containing name + description), then change the engine line in the compression group of the duplicate to dsh-compaction-instant, keeping the isolate field unchanged:

- id: compaction
  name: cordis:group
  group: true
  isolate:
    compaction: true
    toolResultPruner: true
  config:
    - id: compaction-instant
      name: dsh-compaction-instant
    - id: command-compact
      name: '@deepseek-ai/dsh-command-compact'

toolResultPruner must be in the same isolate as the engine. The true test is whether the standingKeyFor mount succeeds, or directly open a session with this preset; the broken list only catches parsing errors.

A comparison of the three methods (extracted from the README):
| Method | Engine in Built-in Presets | Modify Preset Files | New Preset in Selector |
|--------|----------------------------|---------------------|-----------------------|
| Alias Replacement | Automatic (standard / code / cordis) | No | No |
| AI-Copied Duplicate | Only in new presets | Only modified duplicates | Yes |
| Manual Preset | Only in new presets | Only modified duplicates | Yes |

Only one ctx.compaction implementation can be attached per context; presets have independent isolate domains, so host instances and preset instances will not conflict.

Typical Usage¶

After installing and ensuring the current preset actually loads this engine, the usage follows the same entry points as basic.
1. Automatic compression: Default auto: true, it checks pressure during agent/pre-step and performs overflow recovery during agent/request-error. The default thresholdRatio is 0.5, which triggers earlier than basic’s 0.8.
2. Manual compression: Execute /compact in the session. The most recent segment is retained verbatim according to manualRetainRatio.
3. Recall: Use recall / search on the model side; use /recall <keyword or regex> on the human side.
4. View checkpoints: The compaction/summary event carries the compiled entries themselves, and the expandable checkpoint row in the UI shows the actual content the model sees.

Common configuration options (all optional). Do not write empty arrays in the Cordis configuration to “disable” the whitelist: schemastery will fill the default array key with [], and this engine treats an empty array as unset and falls back to the default values. toolArgTools: [] will not clear the whitelist.

thresholdRatio: 0.5
retainRatio: 0.05
auto: true
maxTokens: 8192
checkpointScale: 0.1
checkpointCap: 65536
textTokens: 512
userTextTokens: 1024
toolCallTokens: 128
includeReasoning: false

debug: true will write diagnostics for each compilation to debugLogPath (default $DSH_HOME/compaction-debug.log).

Token counting follows character rules, not the model tokenizer: consecutive English