DeepSeek Harness (dsh) is built on the design philosophy that “everything is a plugin.” While developing or using dsh, developers often need to quickly understand a session’s token usage, time to first token (TTFT), throughput (TPS), and estimated cost. dsh-tokstat is a plugin maintained by kongjianguan. It reads local session logs directly and provides two types of statistics panels: a Web settings page plugin and a Python TUI dashboard.

Core Capabilities

The plugin reconstructs metrics using frame-level incremental parsing of zstd, turning logs scattered under ~/.dsh/sessions/ into analyzable data:

  • Real-time panel: Provides two forms. One is a Web settings page plugin, which adds a “Statistics” section to the dsh Web settings page and updates by polling every 2 seconds; the other is a standalone Python TUI, providing a terminal dashboard with seven views.
  • Multi-dimensional views: Supports switching among seven views, including Overview (Hero card + sparkline), Trend (hourly/daily bar chart), Model/Provider, Sessions, Requests, and Errors.
  • Detailed metrics: Restores input/output/cached tokens, TTFT (time to first token), TPS, elapsed time, retries and failures, and estimated cost. Supports hourly/daily aggregation and clicking column headers to sort.
  • Error analysis: Supports viewing the distribution of retry reasons (such as TRANSPORT/SERVER/TIMEOUT) and individual retry events and failure steps.

Installation and Activation

Install the plugin into a specified dsh profile (for example, web-dev):

dsh plugin --profile web-dev add https://github.com/kongjianguan/dsh-tokstat.git

After installation, start dsh Web:

dsh --profile web-dev --port 3199

Open a browser and visit http://127.0.0.1:3199/, then go to Settings → Statistics to see the panel.

Usage

Web Settings Page Plugin

The plugin reads and aggregates session logs via sessionPersistence within the dsh in-process Node half, and exposes the /tokstat/stats endpoint. The panel requires no additional service and directly displays aggregated statistics.

Running the Python TUI

Run from the repository root:

./run.sh          # 默认范围：全部
./run.sh --range today          # 只看今日

TUI shortcuts:

  • o t m p s r e: Switch among Overview/Trend/Model/Provider/Session/Request/Error views.
  • 1 2 3 4: Switch time range (all/today/last 7 days/last 30 days).
  • f: Focus the request log filter box (Esc to exit).
  • space: Pause/resume auto-refresh.

Configuring the Price List

Configure prices for each model (per million tokens) via a YAML file:

./run.sh --prices PATH

Notes

  • Version compatibility: The data format has been validated against the session log structure of dsh 0.1.0-rc.6. The plugin form requires Node ≥ 23.6; the TUI requires Python 3.11+.
  • Permissions and security: The plugin is read-only throughout and only reads session.jsonl.zstd under ~/.dsh/sessions/ and ~/.dsh/settings.yaml, without modifying any dsh data. The TUI runs entirely offline, does not connect to the network, has no telemetry, and does not read or upload API keys.
  • Sensitive data: Session logs contain conversation content. Do not commit a ~/.dsh directory containing sensitive conversations to any repository.
  • Metric definitions: The TTFT definition includes queueing/thinking time and has a significant long tail; use p50/p95 as the reliable values. Persisted logs for some sessions only contain batched chunks, so TTFT is approximate (error <10%).
  • Cost explanation: Costs are estimates. Prices for relay channels must be configured in prices.yaml.