Preface

In the development or use of DeepSeek Harness (DSH), a common issue is determining whether the current context is already close to the window limit, or whether to end the current session and start a new one. Such decisions usually rely on experience and lack a quantitative basis.

The dsh-context-compass plugin aims to solve this problem. By collecting real runtime data inside DSH, it provides developers with a fact-based “continue vs. new” decision compass.

Plugin Introduction

dsh-context-compass is a session health plugin for DeepSeek Harness, maintained by NinjaSln-labs. It does not rely on estimates. Instead, it directly reads real data such as Harness’s sessionHealth projection, tokenMeter, fs probes, and Git status to help users assess the current session’s health.

Core Features

Header Badge

The plugin displays a responsive header badge next to the session log button. The badge color is driven by the sessionHealth projection and reflects the current context pressure.

Hovering over the badge reveals detailed information:
* Usage trend: A mini line chart of pressure samples from the last ≤40 requests.
* Cost and cache: Per-turn token cost and cache hit rate (an indicator of context stability).
* Compression info: Compression count and the last compression ratio (inferred based on the snapshot definition).
* Billing forecast: Shows CNY or USD and marks peak/off-peak pricing.

/compass Command

Enter /compass to view a full text report. The command supports multiple variants:

  • /compass: Runs all probes (process detection is disabled by default).
  • /compass minimal: Shows core metrics only (token / window / size).
  • /compass no-git / /compass no-handoff: Skips Git or handoff document probes.
  • /compass doc=<filename>: Checks the specified handoff document.
  • /compass remaining=<turns>: Estimates cost based on the remaining number of turns.
  • /compass processes: Forces process detection to be enabled.

context_compass Tool

This is a read-only, model-callable assessment tool, suitable for self-checks in long tasks. It returns structured conclusions, including severity, recommendation, signals, cost, and handoffReady.

Multi-Session Compass Overview Panel

Click the “Compass Overview” button next to “Settings” at the bottom of the sidebar to open a full-screen panel. This panel lists the health assessment for all sessions, sorted by running status. The status column contains three states: Running, Loaded, and Cooling. Clicking a row opens the corresponding session and runs /compass.

Decision Model

The plugin adopts a two-dimensional “continue vs. switch” model, with adjustable parameters in the configuration. The default levels are as follows:

  • Green: Window percentage < 30% and per-turn billing equivalent < 50K. Recommended to continue with confidence.
  • Blue: Window percentage 30–50% or message count ≥ 800. Recommended to continue while monitoring the window.
  • Yellow: Window percentage ≥ 50% or per-turn billing equivalent ≥ max(50K, 30% × window). Recommended to wrap up at the next task boundary.
  • Red: Window percentage ≥ 80%. Recommended to finish and hand off as soon as possible.

Economic cost (per-turn billing equivalent) takes priority over capacity (window percentage).

Installation and Enabling

The installation command is as follows:

dsh plugin add dsh-context-compass

After installation, the plugin automatically registers the sessionHealth projection and the /compass command.

Configuration

The plugin supports adjustment via a configuration file or a browser configuration card. Key configuration items include:

  • thresholds: Decision model parameters (window percentage, economic threshold, message count proxy).
  • checks: Probe toggles (Git, handoff document, process detection, etc.).
  • cost: Billing-related settings (cache discount, price source, refresh time).

The projection.enabled setting controls badge display. Changes to thresholds and checks usually take effect immediately without a restart.

Pricing and Billing

The plugin includes logic to parse the official DeepSeek pricing documentation. Amount display supports both CNY and USD, and distinguishes peak and off-peak prices (based on Beijing time).

The data source is the official pricing documentation, with support for automatic refresh (default 24 hours) and fallback. Before the first load, or when configured as static, fallback static prices are used.

Ecosystem and Notes

  • Knowledge base integration: The plugin decouples knowledge base dependencies. Cross-session retrospective probes are performed only when a knowledge base plugin (such as dsh-knowledge-sqlite) is detected.
  • Local persistence: Local write persistence is supported only for local loopback deployments.
  • Permissions: The plugin runs with the permissions of the current DSH process. Review the source code and license before installation.

Summary

dsh-context-compass shifts context management from experience-driven judgment to data-driven decisioning, helping developers control the session lifecycle more precisely.