# dsh-context

> Add a "Context" panel and /context popup to DeepSeek Harness, displaying current window composition, historical token trends, compression and pruning events, giving users visibility into how much context the model consumes.

## Metadata

- Author: [@bowenliang123](https://github.com/bowenliang123)
- Repo: <https://github.com/bowenliang123/dsh-context.git>
- GitHub: [bowenliang123/dsh-context](https://github.com/bowenliang123/dsh-context)
- Stars: 600
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://www.npmjs.com/package/dsh-context>
- Topics: `cordis-plugin`, `deepseek-harness`, `deepseek-harness-plugin`, `dsh-external`, `dsh-plugin`, `dsh-plugins`
- Forks: 5
- Open Issues: 1
- Last push: 2026-08-20T15:39:02.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:bowenliang123/dsh-context
```

## Wiki

## One-Line Description
dsh-context adds a "Context" panel and `/context` popup to DeepSeek Harness's Web session view, visualizing the token composition of the model's current visible window, historical changes, and compression/pruning records through stacked bars, trend curves, and event lists—so you can see at a glance "what's eating up the context".

## Core Features
- **Inject "Context" tab**: Insert a Context tab at order 20 in the session view, positioned after Chat (order 0) and Trajectory (order 10), displayed alongside official panels
- **Provide `/context` slash command**: Type in the input box or select from the `/` menu to pop up a centered dialog showing current composition headline + six types of stacked bars + compact trend chart for the last 10 turns
- **Real-time display of current window composition**: Token percentages for six categories—system prompts / tool definitions / user messages / injected context / assistant replies / tool results—plus remaining capacity relative to the model's full context window
- **Show historical token trends**: One stacked bar per model request, switchable between Turn / Step granularity, hover for details, click to pin a complete breakdown of a single request
- **List context change events**: Four event types—compression, tool result pruning, skill/plugin injection, model switching—filterable by category, annotated with token increase/decrease for each event
- **Expose model's actual visible message list**: Complete message list the model can see in the current session, sorted by token cost from highest to lowest

## Technical Implementation
- **Language**: TypeScript (both host half and client half compiled from src/)
- **Key dependencies**: `zod` (runtime validation + projection schema), `@deepseek-ai/dsh-session-projection` (host registers projection unit), `@deepseek-ai/dsh-token-meter` (reads `contextPressure` projection as anchor), `@deepseek-ai/dsh-client-ui-primitives` (shared UI icons)
- **Architecture pattern**: Dual-sided plugin — Host half registers as a cordis plugin in `cordis.patch.yml`, registers a projection unit named `contextTimeline` to harness's `ctx.sessionProjections` (init/apply/view, stateVersion=2), driven event-by-event by harness to fold and push results through the session projection pipeline to the browser; Client half is bundled as a CJS closure factory injected into the browser via the package's `dsh.client` declaration, reads data from the standard `useProjection('contextTimeline')` seat, no custom RPC involved
- **Entry files**: Host `src/host/index.ts` (cordis entry, registers projection unit to sessionProjections), Client `src/client/index.ts` (registers session view tab and `/context` command), build by `scripts/build.mjs` producing `lib/index.js` (host, ESM) and `lib/client.js` (client, `window.__ModuleLoader__.load` closure)

## Use Cases
When DeepSeek Harness sessions become long, models start "forgetting" early content, compression and pruning happen frequently, but users have no way to know whether it's system prompt bloat, heavy tool schemas, or tool results filling the window—this plugin's visualization panel shows how many tokens each content type occupies and how much space compression/pruning recovered. The compact popup for the last 10 turns is perfect for quickly checking `/context` during long-running tasks without shifting the current input focus.

## Prerequisites & Compatibility
| Dependency | Min Version | Description |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+ (all devDependencies locked to 0.1.0-rc.6; no peerDependencies declared in package) | Both client and host depend on session-projection registry and token-meter introduced in 0.1.0-rc.6 |
| Node.js | Not declared | Build script uses esbuild + Node ESM, runtime is managed by host |
| Platform | macOS / Windows / Linux | Cross-platform, no native modules, no specific OS restrictions |
| Native modules | None | zod is the only runtime dependency, pure JS |

## Installation
```bash
dsh plugin --profile web add github:bowenliang123/dsh-context
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `maxRequestSteps` | Integer | Maximum historical step (single model call) records to keep per session; beyond this, pruning by full turns, never half-turns | 1500 |
| `maxKeptTurns` | Integer | Number of recent full turns to keep; once session exceeds this limit, folder immediately prunes to the most recent N turns | 300 |
| `maxEvents` | Integer | Maximum recent context events (compression/pruning/injection/switching) to retain | 400 |
| `maxNodes` | Integer | Maximum "model visible message nodes" pushed to browser; newer nodes overwrite older ones | 200 |

> These fields correspond to the `config:` block of the dsh-context loader row in `cordis.patch.yml`; zod validates strictly, incorrect or unknown fields will cause plugin load failure. Other fields are maintained by the plugin itself and generally don't need modification during deployment.

## FAQ

**Q: Does this plugin modify session history or inject extra content into prompts?**

A: No. The host half folds session event streams into view state but doesn't write back any new events; the `/context` command is client-triggered and doesn't write to session/events during triggering, so one `/context` won't become model input.

**Q: What's the difference between the `/context` command and the right-side Context tab?**

A: The data is identical. The command popup is a condensed version of the tab: it only renders the current composition headline, six stacked bars, and compact trend chart for the last 10 turns; the tab adds full historical curves, compression/pruning event stream, current model's visible message list, and session stats card.

**Q: What if the "Context" tab doesn't appear on the right after installation?**

A: This plugin only works for web profile (dsh.client.platform=web in package.json). Please confirm the installation command included `--profile web` and use `dsh web` to start the frontend; CLI / TUI / other clients won't show the tab.

**Q: Why does typing `/context` in the input box have no response?**

A: `/context` is a soft dependency on harness's `inputTriggers` service. If the current DSH version doesn't have this service, the tab will work normally but there's no trigger menu; please upgrade DSH to 0.1.0-rc.6 or higher.

**Q: How many recent turns / steps are retained? Will data be lost?**

A: Default 1500 steps / 300 turns / 400 events / 200 model visible message nodes. The folder only prunes full turns, never cuts a turn in half; these are adjustable fields in the cordis config, not the underlying session logs themselves.

**Q: Will uninstalling the plugin lose my accumulated context view data?**

A: Yes. The context projection state is folded by the plugin itself and doesn't persist to a DSH external layer; after uninstall or disable, reinstalling requires the session to regenerate events to rebuild the view. The session's original events are still preserved in harness and unaffected.

**Q: Where does the "model remaining available window" number at the top come from?**

A: Since 0.11, this number comes from DSH official token-meter's exposed `contextPressure` projection (provider actual usage + heuristic estimate). If token-meter is not installed or that projection doesn't exist, it automatically falls back to this plugin's surface-based message estimate.

**Q: Do I need internet or configure an API key?**

A: No. zod is the only runtime dependency, all token estimation is done locally; only the "plugin info" card makes one version check request to npm registry (1-hour cache), offline or CSP-blocked will gracefully degrade without showing upgrade hints.

## Learning Curve
Beginner — install it and the Context tab and `/context` command appear on the right; no additional configuration needed; understanding cordis config block structure is only required if you want to adjust historical window length.

## Known Issues & Limitations
- Both client and host depend on session-projection registry and token-meter `contextPressure` projection introduced in 0.1.0-rc.6; earlier DSH versions may not see the tab or read the anchor number
- Projection state `stateVersion: 2`, after host upgrades to 0.11 the old client `occupancy` field is marked as LEGACY — clients should read token-meter projection instead, otherwise only see compatibility fields
- `latestVersion` check goes to https://registry.npmjs.org/dsh-context/latest, strict corporate intranet/CSP policies may block it, but failure degrades silently without affecting core functionality
- `/context` command depends on harness's `inputTriggers` service; in hosts without this service the tab still works but command will be ineffective
- Context projection state is not persisted by the plugin, after uninstall need to wait for session to regenerate events before view can be rebuilt

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-context](https://deepseek-plugin.org/plugins/bowenliang123/dsh-context)
Wiki generated by AI (model: `MiniMax-M2.5`)