dsh-companion

English | 简体中文

A lightweight Agent Companion for DeepSeek Harness Web. It turns the selected session's activity, context pressure, and optional usage metrics into a glanceable Living Data Orb.

Status first, usage on demand; friendly without becoming distracting.

This image is a visual-regression baseline rendered from production components and synthetic states. It covers no session, idle, working, waiting, context attention, context warning, and the completion response.

The idea in one minute

DSH Companion communicates two independent signals:

1. Activity — whether the agent is sleeping, idle, working, or waiting for you.
2. Context pressure — how much of the model context window the next request is projected to occupy.

Context, billed input, output, cache hit, and step metrics appear only when you hover, focus, or pin the detail panel.

Design principles

Status first, usage on demand

Activity and context pressure are the default experience. Detailed numbers stay secondary until the user asks for them.

Ambient, not demanding

The companion can communicate work, required interaction, and completion without flashing, covering the page, or demanding continuous reading. It can be moved or collapsed into a recoverable edge tab.

Friendly, not gamified

The Living Data Orb uses expression and restrained motion to improve comprehension. The MVP deliberately avoids feeding, leveling, rewards, collections, cosmetics, and multi-pet mechanics.

Honest about data

Missing projections remain unknown or absent. The companion never fabricates zero usage, pricing, balances, or streaming estimates.

Native to DSH

The plugin mounts additively in shell.overlay, follows the selected session, consumes existing projections, and respects the host lifecycle, semantic styling, and accessibility patterns.

Observational and privacy-first

The companion does not modify prompts, tools, model requests, or session events. It does not inspect conversation content, reasoning, tool input/output, files, credentials, or provider accounts, and it has no telemetry or remote service.

Architecture at a glance

flowchart LR
    DSH["DeepSeek Harness"] -->|"selected SessionSummary"| Adapter["DSH client adapter"]
    Adapter -->|"status + numeric projections"| Derive["Pure state derivation"]
    Derive --> ViewModel["CompanionViewModel"]
    ViewModel --> Orb["Living Data Orb"]
    ViewModel --> Panel["Usage panel"]
    Preferences["Browser-local position and collapse state"] --> Orb

DSH owns the event log and projection folds. Companion starts at the selected summary already exposed to the Web client; it does not scan the log, poll a backend, or duplicate upstream accounting.

Detailed design documents:

• Product Design
• Visual Design
• Architecture
• MVP User Stories

State model

Activity

Waiting takes priority over working because required user action is the more important signal.

Context pressure

Pressure uses visible text, ring weight, and color together, so color is never the only signal.

Interaction

• Hover or keyboard focus previews usage.
• Click pins or unpins the panel.
• Escape or an outside click closes a pinned panel.
• Drag moves the companion and saves its browser-local position.
• Collapse replaces the orb with a reachable edge tab.
• Restore returns the orb to its saved position.

The surrounding overlay is click-through. Only the orb, panel, and recovery tab receive pointer input.

Metrics

Unavailable metrics are omitted instead of estimated.

Install

Install from npm into the DSH Web profile:

dsh plugin --profile web add dsh-companion
dsh web

You can also build a local tarball from source:

git clone https://github.com/gjnzsu/dsh-companion.git
cd dsh-companion
pnpm install --frozen-lockfile
pnpm build
pnpm pack --pack-destination .
dsh plugin --profile web add ./dsh-companion-0.1.1.tgz
dsh web

Remove it with:

dsh plugin --profile web remove dsh-companion

Privacy

The companion reads only status and numeric projections already delivered for the selected session, plus browser-local placement preferences. It has no telemetry, remote service, cloud synchronization, conversation-content inspection, tool-output inspection, credential access, or provider-account access.

Compatibility

dsh-companion@0.1.1 targets DeepSeek Harness 0.1.0-rc.5 exactly. Harness is in developer preview, so later release candidates may require a Companion update.

Development and testing

Development requires Node.js ^22.19.0 || >=24.0.0 and pnpm 11.15.1.

pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm build
pnpm gallery
pnpm test:visual
pnpm pack:check

Run the keyless real-Web smoke against a Harness source checkout from PowerShell:

$env:DSH_REPO='C:\SourceCode\deepseek-harness'
pnpm test:smoke

The test strategy has two layers:

• Synthetic state tests cover state combinations, pressure boundaries, themes, compact viewports, reduced motion, and interactions.
• Real Web smoke proves that the packed plugin installs into DSH and follows the actual selected session.

MVP limitations

Version 0.1.0 supports DSH Web and the selected session only. It does not provide streaming estimates, pricing or cost calculations, history, growth mechanics, multiple companions, prompt/tool-content analysis, or cloud synchronization.

License

MIT