Skip to main content

deepseek-harness-desktop/packages/dsh-live-stats

156Stars5Forks6Issues0Watchers

Shows real-time input/output token estimation and generation throughput (TPS) in the DSH Web chat status line, automatically replacing with actual provider usage when available.

Categories▣ UI Enhancements◇ Models & Routing
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the ningbainb/deepseek-harness-desktop monorepo — stars and activity count the whole repository.

ningbainbningbainb
·ningbainb/deepseek-harness-desktop·ningbainb.github.io/deepseek-harness-desktop
Language
TypeScript
License
BSD-3-Clause
Branch
main
ai-agentai-coding-assistantcodexdeepseekdeepseek-harnessdesktop-appdshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add @linxin666/dsh-live-stats

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin ningbainb/deepseek-harness-desktop/packages/dsh-live-stats for me: review the repository at https://github.com/ningbainb/deepseek-harness-desktop first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Display real-time estimated input/output token count and generation throughput (TPS) in the DSH Web chat status line. Automatically replace estimates with actual provider usage once available.

Core Features

  • Real-time input token estimation: Combines surface message character count from session with header/tool framework, converted via character density parameter
  • Real-time output token estimation: Accumulates chunk-by-chunk during streaming, with text, reasoning, and tool-call each following different billing rules
  • Real-time generation throughput: Renders metrics like TPS 31.4 tok/s, positioned after step count and before billing group
  • Automatic replacement with real usage: When provider returns usage chunk or final message lands, estimates are overwritten with actual data
  • TPS persistent display: Once a rate is measured, it continues to display. When new step hasn't produced output or encounters a step without rate, it falls back to most recent measurement, preventing status line flicker
  • Expose settings card: DSH Web plugin settings include a live-stats card for adjusting character density parameter and master switch

Technical Implementation

  • Language: TypeScript + React (client-side)
  • Key Dependencies: @deepseek-ai/dsh-session (consuming event stream), @deepseek-ai/dsh-session-projection (registering replayable projections), @deepseek-ai/dsh-token-meter (consuming projection results), schemastery + zod (configuration/data structure validation)
  • Architecture Pattern: Classic host/client dual-zone — host side uses cordis plugin to register liveTokenUsage session projection (liveTokenUsage uses pure function fold, replayable), client side mounts a settings card to web-ui.plugin.item slot and TPS line to conversation.composer.dock slot
  • Entry Files: src/index.ts (host half), src/client/index.ts (browser half)

Use Cases

  • Running long conversations in DSH Web and wanting to see generation speed (TPS) and cumulative token trends in real-time, instead of waiting until the end
  • Wanting to have a rough idea before provider actual usage is available, such as judging whether to stop generation early
  • Wanting to uniformly adjust token estimation density (e.g., setting charsPerToken to 1.5-2 for Chinese workflows) to make status line numbers closer to actual billing

Prerequisites and Compatibility

DependencyMinimum VersionDescription
DSH0.1.0-rc.7+All SDK dependencies pin to ^0.1.0-rc.7; also declares compatibility fallback to rc.6 (falls back to ctx.settingsScope when ctx.webUiSettings is missing)
Node>=22.19.0Repository root package.json engines field: ^22.19.0 || >=24.0.0
Runtime PlatformWebdsh.client.platform: "web", only registers slots in browser half, no TUI/CLI equivalent
Native ModulesNoneOnly depends on Runtime SDK, no node-gyp compiled modules

Installation

dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-live-stats

Configuration Options

ConfigTypeDescriptionDefault
enabledBooleanMaster switch, when disabled host-side projection fold won't register, TPS line won't appeartrue
charsPerTokenNumberApproximate character count per token, smaller values make estimated tokens larger4
blockOverheadIntegerFixed framework token allocated per content block (text/tool call/tool result, etc.)4
roleOverheadIntegerFixed framework token allocated per message or assistant response4

FAQ

Q: Does this plugin increase token consumption per request?

A: No. The plugin only consumes persistent event stream and projection data, doesn't inject prompt segments, doesn't register tools, and doesn't send any session events. Token impact per request is zero, and it has no impact on KV cache.

Q: Is charsPerToken=4 too low for Chinese estimation?

A: Yes. Default 4 characters/token underestimates Chinese (Chinese is actually denser) while overestimating pure ASCII text. You can adjust charsPerToken in the settings panel or overlay configuration. For dense Chinese scenarios, recommend setting it between 1.5-2.

Q: How is the TPS number calculated? Why does it sometimes not display?

A: TPS is calculated by dividing output token count of an active step by wall-clock time, following a "persistent" strategy: as long as a rate has been measured for a step, the status line continues to display. When new step hasn't produced output or encounters a step without rate, it falls back to the most recent measurement, preventing flicker. It only doesn't display when it has never been measured from the start.

Q: When will the ~ estimate be replaced with real data?

A: ~ indicates heuristic estimation. When provider returns usage chunk or final response message lands, estimates are replaced with actual usage; precise cache statistics always come from DSH's built-in persistent token usage projection, not this plugin.

Q: Is it Web-only or supported on all clients?

A: Currently Web-only. TPS status line renders within DSH Web's conversation statistics line, no TUI/CLI equivalent exists. During installation, dsh.client.platform field is also fixed to web.

Q: How to adjust character density parameters? Where is the config file?

A: Recommended to directly modify in DSH Web's plugin settings panel (a staging form bound to live-stats namespace). You can also add charsPerToken / blockOverhead / roleOverhead three fields in ~/.dsh/config.yaml overlay, saved and hot-reloaded immediately.

Q: Does it need to restart after disabling and re-enabling the plugin?

A: No. When enabled switch in settings panel or overlay configuration changes, host side will destroy old projection and re-register projection fold with new parameters. Next session log replay takes effect immediately, no need to restart dsh web.

Difficulty Level

Beginner — installs and works instantly, zero configuration can see TPS and estimation results; advanced users can adjust density parameters in settings panel.

Known Issues and Limitations

  • Heuristic estimation: Input/output totals before provider usage arrives are character count estimates (marked with ~), precise cache statistics always come from DSH's built-in persistent token usage projection
  • Browser-only: TPS line renders within DSH Web's conversation statistics line, no TUI equivalent
  • Single active step: Projection only tracks one active step per session, concurrent sessions each have independent projections
  • Character density assumption: charsPerToken=4 underestimates Chinese, overestimates pure ASCII; need to adjust according to deployment when estimation deviation is significant
  • No platform native modules: Plugin is pure JS/TS, doesn't introduce node-gyp compiled artifacts, but can only rely on DSH Web as the runtime form

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-live-stats)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory