Skip to content
  • Home
  • Plugin manual
  • dsh-headroom

wjxn13/dsh-headroom

30Last commit Aug 15, 2026

dsh-headroom DSH plugin

This plugin automates the setup of Headroom, a context compression proxy, for DeepSeek Harness. It detects Python, creates a virtual environment, installs the headroom-ai[proxy] package, and manages the proxy process. A settings page provides a one-click switch to enable or disable the compressed line, along with real-time statistics on token savings and cache hit rate.

developer-tools

How to install the dsh-headroom DSH plugin

dsh plugin add file:../dsh-headroom  # 或本地路径

Copying does not run this command. Review the repository and version before installing the dsh-headroom DSH plugin.

dsh-headroom DSH plugin data source

dsh-headroom DSH plugin snapshot date: Aug 16, 2026

discovered

What the dsh-headroom DSH plugin can do

  • One-click enable compression line: point DSH's llm-deepseek.baseURL to the local Headroom proxy via the settings page.
  • Automatic environment management: detect Python, create venv, install headroom-ai[proxy] (lightweight, no torch).
  • Process daemon: auto-start headroom proxy, /livez health check, crash notification.
  • Compatibility presets: fixed Windows workaround (HEADROOM_DETECT_BACKEND=python, HEADROOM_TOOL_SEARCH=off) and DeepSeek dual-protocol routing.
  • One-click revert to direct connection: switch back to api.deepseek.com at any time without lock-in.
  • Real-time statistics: display tokens spent/saved, cache hit rate (refreshed every 10 seconds) in the settings page.

Where the dsh-headroom DSH plugin fits

  • Reduce redundant token usage in tool schema descriptions (saves 4-71 tokens per request).
  • Compress cross-turn content in large-context coding sessions, especially when tool outputs are large.
  • Benefit from DeepSeek prefix caching (99.9% hit rate) by not breaking the cache prefix, lowering input costs.
  • Occasional large savings (8-20%) when deduplication triggers on large tool outputs.

Who the dsh-headroom DSH plugin is for

  • DeepSeek Harness users who want to minimize per-request token usage and cost.
  • Developers working with large-context sessions (e.g., 1M tokens) and seeking additional compression beyond DSH's built-in compaction.

dsh-headroom DSH plugin limitations

  • Requires Python 3.10+ (Windows: 3.10-3.13).
  • First startup after enabling compression line may take about 1 minute (cold start of Headroom tokenizer/model).
  • Actual token savings vary heavily by scenario; in large-context coding sessions, typical savings per request are ~0.001% (only when tool schema is already compacted and history is cached).
  • Does not compress session history (compaction-basic) or prune tool results (tool-result-pruner) – those are handled by DSH's own mechanisms.
  • Depends on the external Headroom project (Apache 2.0) and its ongoing maintenance.

dsh-headroom DSH plugin: from the repository README

Quoted from the wjxn13/dsh-headroom README, the upstream source of the dsh-headroom DSH plugin. Copyright remains with the original authors.

DeepSeek Harness 的 Headroom 上下文压缩代理集成插件：一键检测、安装、启动 [Headroom](https://github.com/headroomlabs-ai/headroom) 压缩代理，并自动接入 DeepSeek 线路（OpenAI 协议），在设置页提供状态面板与切换控件。 > **重要声明**：本插件是 [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom) > （Apache License 2.0）的**集成与封装**，Headroom 压缩引擎本身由 Headroom 项目提供， > 版权归其作者所有。本插件不包含、也不修改 Headroom 的压缩算法，仅负责： > 环境检测、依赖安装、进程管理、DeepSeek 兼容预设与线路切换 UI。 > 详见 [NOTICE](./NOTICE) 与 [LICENSE](./LICENSE)。 ## 功能 - **一键启用压缩线路**：设置页点按钮，把 DSH 的 `llm-deepseek.baseURL` 指向本地 Headroom 代理 - **自动环境管理**：检测 Python → 自动建 venv → 安装 `headroom-ai[proxy]`（轻量，无 torch） - **进程守护**：自动启动 headroom proxy、`/livez` 健康检查、崩溃提示 - **兼容预设**：固化 Windows workaround（`HEADROOM_DETECT_BACKEND=python`、 `HEADROOM_TOOL_SEARCH=off`）与 DeepSeek 双协议路由 - **一键切回直连**：任何时刻可切回 `api.deepseek.com`，无锁死风险 - **实时统计**：设置页显示花费/节省 token、缓存命中率（每 10 秒刷新） ## 实测成果 > 以下数据来自本机真实使用（DeepSeek V4-Flash，DSH 大上下文会话），2026-08-15 统计： | 指标 | 实测值 | 说明 | |---|---|---| | 累计压缩节省 | **1,256,265 token** | Headroom 累计压缩掉的 token（跨 1,533 次请求） | | 累计输入 | 413M token | 压缩后实际发送量 | | 缓存命中率 | **99.9%** | 前缀缓存命中（DeepSeek 官方机制，Headroom 不破坏它） | | 单请求典型节省 | 4-71 token / 请求 | 工具 schema 压缩为主（大上下文会话） | ### 能省多少？（诚实预期） Headroom 官方宣称可省

Read the full READMERepository license: Apache-2.0

dsh-headroom DSH plugin questions

How do I install dsh-headroom?

Clone the repository, then run `dsh plugin add file:../dsh-headroom` from your DSH profile directory. Add the plugin entry to `cordis.patch.yml` and restart DSH. Detailed steps are in the README.

Does it work on Windows?

Yes, as of Headroom 0.35.0, precompiled wheels are available for Windows (Python 3.10-3.13). No Rust or MSVC toolchain is needed. The plugin also includes a Windows-specific workaround for environment detection.

How much token can I save with this plugin?

Savings vary by usage. For JSON/structured data, you can expect 60-95% reduction. For large-context coding sessions, typical savings per request are small (around 0.001%) because tool schema is already compacted and history is cached. However, large tool outputs can trigger occasional 8-20% savings. The real value lies in preserving DeepSeek's prefix caching (99.9% hit rate).

What is the difference between this plugin and DSH's built-in compaction?

DSH built-in compaction handles session-level tasks: summarizing old conversations (compaction-basic) and trimming tool results when over budget (tool-result-pruner). This plugin focuses on request-level compression: reducing tool schema redundancy and cross-turn deduplication. They are complementary and do not overlap.

How do I uninstall dsh-headroom?

Use `dsh plugin remove dsh-headroom` and remove the entry from `cordis.patch.yml`. If you want to remove the Headroom engine, delete the venv folder created by the plugin (usually inside the plugin directory). The plugin will not affect your DSH configuration after removal.