Introduction

DeepSeek Harness (DSH) adopts a plugin architecture designed to extend Web UI functionality. Headroom is a compression agent used to reduce token consumption. This plugin adds a real-time token and cost savings dashboard to the DSH Web UI. It integrates Headroom statistics into the settings page and chat input area, helping developers intuitively monitor compression results and costs.

Feature Overview

The plugin mainly includes the following capabilities:

  • Settings Dashboard: Located at Settings → Headroom Stats. It provides lifecycle KPIs (tokens saved, compression/caching costs, request count), a current session card, a cost split bar for caching and compression, and a Top 10 items table. It also handles loading, error, and stale states.
  • Composer Stats Line: Displays a line of data below the chat input box, formatted as Headroom: tokens saved · $ · %, with a refresh interval of 5 seconds.
  • Dynamic Path Detection: No hardcoded paths are used, supporting cross-machine usage. The probe order is HEADROOM_SAVINGS_PATH → HEADROOM_WORKSPACE_DIR → %USERPROFILE%\.headroom.
  • 5-Second Real-Time Refresh: A single shared poller uses one snapshot to provide data to the settings page and stats line, avoiding duplicate file reads.
  • Theme Awareness: Uses --dsw-alias-* design tokens to automatically adapt to DSH’s light/dark themes.
  • Survives Restarts: Bundled as a real configuration profile plugin, configured via dsh.bundle, it is automatically loaded when DSH starts, without needing to be redefined in each session.

Installation and Enablement

The installation command is as follows. This command adds the plugin to the specified Web configuration file and persists it with the profile.

dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git

After installation, restart DSH (or perform a hard refresh) to load the plugin. The access path is Settings → Headroom Stats. The stats line will automatically appear below the chat input box.

How It Works and Configuration

  • Data Source: The plugin only reads the file ~/.headroom/proxy_savings. generated by the Headroom agent and does not perform any writes.
  • Path Resolution: When the plugin starts, it probes for the location of the Headroom data file based on environment variables. If no environment variables are configured, it defaults to looking under the user directory for the .headroom folder.
  • Refresh Mechanism: Uses a fixed 5-second polling interval (POLL_MS) to pull snapshot data from the server.
  • No Configuration File: The plugin does not include a configuration file and does not persist user settings. All logic runs based on current environment variables and file state.

Notes

  • Runtime Dependency: You must ensure that the Headroom agent is running on the machine and is writing to the proxy_savings. file.
  • Missing File Handling: If the proxy_savings. file cannot be found, the settings page displays an “unavailable + error” message, and the stats line is hidden.
  • Read-Only Access: For security reasons, the plugin only has read access to Headroom data files. It does not modify files on disk or make network requests.
  • Removal Method: To uninstall it, run dsh plugin --profile web rm headroom-stats-plugin and restart DSH.

Conclusion

By visualizing Headroom statistics, this plugin fills a gap in DSH regarding compression agent monitoring. It provides not only a detailed dashboard on the settings page but also instant session feedback through a persistent stats line. It is suitable for developers who frequently need to monitor token and cost savings during development.

Repository Address: GitHub | Plugin Directory