dsh-perf-lens

A DeepSeek Harness (DSH) plugin that shows which plugin is using your host's CPU, memory and disk — and which plugin is making the browser jank.

Every DSH host plugin runs in one Node process, so the operating system can only tell you what the whole process costs. Perf Lens samples that process from the inside, charges each sample to the plugin that caused it, and puts the result in a dashboard in the DSH web GUI — with the same treatment on the browser side, where long-frame script time is attributed per plugin (Long Animation Frames API). No more throwaway profiling scripts when something feels slow.

Status: 0.1.0 feature-complete (see CHANGELOG.md); 0.2.0 is in progress on master — per-plugin jank attribution, the descendant-process view, and the listeners / on-disk columns have already landed.

What you get

Open Perf Lens in the left sidebar:

• Process overview — RSS, heap, event-loop lag, GC pauses, and how much of the last window was idle, plus the readings that explain what the host alone cannot: the descendant process tree (count, combined CPU, combined memory), the CPU the profile could not account for, and the async resources the process is holding.
• Cost composition — how much of the whole process each plugin takes, for CPU and for sampled heap.
• Top consumers — the plugins costing the most right now, with their average and peak.
• Trend — CPU per plugin over the last hour, day or week.
• Cumulative cost ranking — who burned the most CPU over that range.
• Plugin detail — every plugin grouped and sortable, with the heaviest harness packages broken out and, in deep mode, each plugin's hot functions. Includes listeners (exact, from the cordis event registry) and on-disk bytes (exact, from a directory scan of $DSH_HOME) per plugin.
• Foreground jank — long tasks and dropped frames in the browser, with long-frame script time attributed per plugin (Long Animation Frames API) next to what the host was busy with at the time. Browsers without the API fall back to the plain time correlation. On the DSH Desktop window, where the browser withholds that attribution, a jank probe switch measures instead which plugins' scheduled callbacks occupy the main thread, with callback milliseconds, call counts and the longest single call per plugin.

The panel follows the GUI language (Chinese or English).

Requirements

• DeepSeek Harness 0.1.7-alpha.1 or later, using the web GUI (dsh web)
• Node.js 22.13 or later (whatever runs your DSH host)

Install

Not on npm yet — install from a local checkout:

git clone https://github.com/Nwflower/dsh-perf-lens.git
cd dsh-perf-lens && pnpm install && pnpm build   # produces lib/ (host + single-file client bundle)

Then register it in your DSH profile. For the default web profile, edit ~/.dsh/profiles/web/package.json:

{
  "dsh": { "profile": { "bundles": [ /* … existing bundles … */, "dsh-perf-lens" ] } },
  "dependencies": { "dsh-perf-lens": "link:D:/path/to/dsh-perf-lens" }
}

cd ~/.dsh/profiles/web && pnpm install

The host half loads when the server starts, so restart dsh web for it to take effect. Once the package is published to npm, the dependency line becomes "dsh-perf-lens": "^0.1.0" and no build step is needed. If the profile's pnpm supply-chain policy (minimumReleaseAge) blocks a package, run a one-off pnpm install --config.minimumReleaseAge=0 instead of changing the profile's settings.

Sampling controls

Sampling is never free, so Perf Lens samples in short windows and lets you choose how hard it looks. There are three controls, and they combine — the panel always shows the combination it is actually running, not just which buttons are lit.

Intensity (one of three):

Tier	What it does	When to use it
Low (default)	A 5-second window every 30 seconds or more; backs off to 2 minutes when the host is idle, with a cheap 1-second check every 10 seconds so bursts are not missed	Always on
High	Back-to-back 2-second windows; drops back to low after 10 minutes	While you are actively watching something
Stop	No new windows	When you want the host left alone

Background sampling (on / off) decides what happens while the intensity is Stop: on, the host keeps a coarse 2-second window every 2 minutes, so a long-term record survives with the panel closed. It has nothing to add at Low or High, where the foreground already samples.

Memory sampling (on / off) adds heap sampling to whichever windows run — memory attribution, hot functions per plugin, and credit for work a plugin schedules through harness callbacks. It is the most expensive option, and the only one that costs extra on top of CPU sampling.

So Stop + background on is a cheap always-on record, Low + memory on is the normal profiling setup, and High + memory on is "I am watching this right now". Every change takes effect immediately, and all three settings are reported by the host, so they survive a page reload.

Reading the numbers

• Share vs absolute cost. A plugin's share is its part of the CPU the process actually used during the window. On an idle host that denominator is tiny, so something that ran for a few milliseconds can show 90%. The panel always shows the absolute cost next to it — ms of CPU per second and % of one core — and that is the number to compare across time or machines.
• Charged to the caller. Each sample is walked up the call stack to the nearest plugin frame, so the code a plugin calls into (its dependencies, Node built-ins) counts against that plugin.
• Harness built-ins is the DSH framework itself, folded into one row with its busiest internal packages listed underneath. Runtime rows (GC, native / syscalls, Node internals, event loop) are work no plugin frame was on the stack for. This plugin's overhead is Perf Lens itself.
• Estimates are marked. Anything sampled rather than measured says so, and the cumulative ranking hides its whole-range estimate when sampling covered too little of the range to scale up honestly.
• Jank attribution carries its coverage. The per-plugin long-frame table always shows the share of script time that could be attributed; combo bundles whose segments cannot be read land in an explicit "Unresolved" row, never a guess.

Limits

• There is no per-plugin RSS. One process means one RSS. Memory figures are sampled heap allocations from deep-mode windows, not a plugin's footprint.
• Child processes are shown, not attributed. The overview reports what the host's descendants cost in total, because a shell command, a terminal or a language server runs outside the host and the host alone would look idle. Which plugin spawned a child is not measured yet, and because the tree is polled rather than watched, a command that starts and exits between two polls is not seen — the reading is for long-lived descendants (language servers, dev servers, terminals, builds). It costs about 330ms of wall time per poll on Windows (a PowerShell start), so it runs every 30s, plus an immediate refresh while the panel is open.
• Disk bytes are not measured. Per-plugin file operation counts are exact, and so is per-plugin on-disk footprint (the "On disk" column, which scans $DSH_HOME plus each plugin's own directory); file bytes read and written are not. The scan does not follow symbolic links, so a plugin whose files sit behind a link outside both of those roots reads as empty.
• Timers and handles are process-wide only. Counting them per plugin needs an always-on async_hooks hook, which measured 2.3–2.6× on promise-heavy work, so the panel reports the process totals and leaves the per-plugin columns out rather than showing a false zero. Listeners are per plugin and exact.
• Unexplained CPU is a signal, not an answer. It says some CPU ran outside the sampled thread (a worker, or native code); it does not say which plugin put it there.
• Short windows are noisy. One window is good for "who is busy"; the cumulative ranking is the precise view.
• Jank attribution is script execution only. Long Animation Frames name the script that ran and the style/layout it forced; painting, compositing and browser bookkeeping belong to no script and stay in the frame-level totals. The API needs Chromium 123 or later (the DSH web GUI qualifies); older engines show the correlation view instead. The DSH Desktop window (dsh-app:// custom scheme) withholds script attribution at the browser level, so the long-frame table only appears on the dsh web GUI.
• The jank probe measures registration, not execution. It reports the total time the page spent inside callbacks registered at a given position, counts nested wrappers at each level, and cannot say which statement inside a callback burned the time (the in-page profiler is disabled on that origin). A plugin can register another plugin's callback, so a row reads "callbacks registered here". It is off by default; switching it on reloads the page once so the probe installs before plugins register, and the choice is remembered.

Data and privacy

• Everything stays on your machine. The panel talks only to your own DSH host.
• Each sampling window appends one line of aggregated numbers to $DSH_HOME/perf-lens/metrics-YYYYMMDD.jsonl (default ~/.dsh/perf-lens/). Files are kept for 14 days, capped at 200 MB in total.
• Only costs and counts are written. Call stacks, function names and file paths are never written to disk; hot functions live in memory while deep mode is on. The disk-footprint scan reads paths under $DSH_HOME but writes only the resulting byte totals, and the descendant-process reading keeps process names in memory only.
• The descendant-process reading runs a process-table command (ps, or PowerShell on Windows) every 30 seconds; that is the only external process Perf Lens starts.
• Unloading the plugin stops all sampling and every timer it owns.

Troubleshooting

If the panel is empty or the numbers look wrong, check the diagnostics endpoint first:

Invoke-RestMethod http://127.0.0.1:3081/api-perf/diagnostics | ConvertTo-Json -Depth 4

• sampleCount of 0 means the last window collected no samples; lastError shows the exception the sampling loop caught.
• ownerRules should list real package directories (for example …/node_modules/dsh-context/lib). If it is empty or points at the profile directory, plugin paths could not be resolved and samples will land in "unattributed".
• listenersMeasured should be true. If it is false the cordis event registry was not exposed, so the Listeners column is a gap rather than a number.
• processTree.available should be true with a non-zero at. If it is false, the process-table command (ps, or PowerShell on Windows) is missing or was denied, and the overview says "unreadable" rather than "no children" — those are different facts.
• diskFootprint should be non-null with a recent scannedAt. truncated: true means the walk hit its budget or could not open a root, so every on-disk figure is a lower bound.
• Sampling controls greyed out with a warning. The host half is loaded once, when dsh web starts; the panel is a bundle the page fetches. After upgrading the plugin the page can be newer than the running host, and a host that predates the three-block controls does not know the fields they send — a click would be silently ignored. The panel detects this (the host reports no sampling config) and disables the controls instead. Restart dsh web to pick up the new host half.
• The same skew affects the endpoint shapes: /api-perf/snapshot from a host older than 0.1.0 has no sampling field, and /api-perf/trend from one older than the absolute basis has no cpuMsPerSec.

The HTTP API behind the panel (/api-perf/snapshot, /stats, /trend, /hotspots, …) is documented in docs/design.md §8.

Development

pnpm install      # dev toolchain only; the harness peer packages are not installed (see .npmrc)
pnpm test         # vitest: host specs in node, client specs in jsdom
pnpm typecheck    # tsc --noEmit
pnpm lint         # oxlint
pnpm build        # tsdown: lib/index.js (host) + lib/client.js (single-file client bundle)

prepublishOnly runs all four.

After local changes, rebuild with pnpm build, then reload the page to pick up client changes; host changes need a restart of dsh web.

The harness client type packages are not installed as dev dependencies: their registry latest tag points at a broken 0.0.1-rc.1 line that depends on an unpublished package. The client declares the structural types it needs in src/client/ctx.ts instead, as dsh-context does.

Documentation

Document	Contents
docs/feasibility.md	Why this works: runtime facts, each mechanism verified, overhead, limits
docs/landscape-survey.md	Who else attributes runtime cost to a plugin: the DSH ecosystem, other plugin hosts, continuous profilers, and what to borrow
docs/roadmap-proposals.md	Proposed features after the survey, ordered by which promise gaps are real
docs/design.md	Architecture: attribution, metric contract, sampling state machine, persistence, HTTP API, dashboard layout, decisions
docs/evidence.md	Raw measured output behind every conclusion, and how to reproduce it
docs/design-overnight-analyzer.md	Research on continuous background analysis: sampler cost, heap snapshots (rejected), share vs absolute cost, detection precision
probes/README.md	The one-off research scripts and what each one established
CHANGELOG.md	What each release contains

Ecosystem

More DSH plugins by the same author: dsh-chat-import (migrate 25+ external agents' chat history into DSH) · dsh-pilot (contract-driven master/subagent dispatch) · dsh-file-claim (multi-session file claiming) · dsh-claude-style

License

MIT