Introduction¶

The DSH (DeepSeek Harness) Web profile logs every session to disk, but the built-in interface only shows the conversation content, not a summary of “how many tokens were run this time, how many cache hits, how many used this month”. To do this manually, one has to manually search the logs for assistant/message usage, which is time-consuming and inconsistent in definition.

The plugin introduced below, genius-alray/dsh-plugin-session-token-stats, solves this problem: it directly reads real session logs and generates a Token usage dashboard, including totals, monthly usage, cache hit rate, daily timeline, and session-level details. Maintained by genius-alray, it falls under the client category and is released under the MIT license.

It only tracks tokens and does not display costs or budgets. This is because these sessions do not have a reliable billing API, and the author’s choice is to avoid presenting guesses as facts.

1. What It Shows¶

After the plugin takes over, a bar chart entry Token stats will appear at the bottom of the left sidebar. Opening it reveals a panel divided into four sections.

1. Summary Cards¶

Displays total tokens (split into uncached input / cached input / output), session count (turns, and merged sub-agent sessions), monthly used tokens, and overall cache hit rate.

2. Token Timeline¶

Stacked bar charts for the last 7 / 30 / 90 days. The three categories are uncached input, cached input, and output. Hovering over a bar shows the precise number for that day. The time range is a setting in the browser.

3. Usage by Session¶

One row for each Main Session, sorted by the latest. Sub-agent sessions are merged into the session that derived them and are not listed as separate rows. Selecting a row expands it to show usage breakdown by model, the number of merged sub-agents, creation and last activity timestamps, and the session ID.

4. CPU and Memory¶

The right side of the panel lists system-level metrics: CPU usage (mini line chart over 120 seconds), 1/5/15 minute load averages, DSH process CPU and RSS, system memory, core count, process uptime, and host identifier.

2. Metrics Definition¶

The Host side reads persistent session logs via ctx.sessionQuery.listSessions() / readSession(id), counting assistant/message usage item by item. The field definitions are as follows:

To ensure these numbers are trustworthy, the plugin applies two deduplication rules:

1. Fork / Inherited Sessions: The log starts with a prefix copied from the parent session; that usage has already been counted in the parent session. Only count events after inheritedEventCount (the latest session/title is still read from the entire log).
2. Sub-agent Sessions: header.parentSession points to the parent session. Follow this chain to merge sub-agent sessions up to the top-level main session into a single row.

Persistent sessions are immutable, so each log is read once and cached; active sessions are re-read on every refresh. The first open involves unzipping and replaying validation for all logs (500+ logs takes about 10–20 seconds), reporting progress as { done, total } and polling quickly; subsequent refreshes only re-read active sessions.

3. Installation and Activation¶

The plugin is a standard dsh bundle: it registers one Host line and one Client line without overriding any built-in components.

UI Installation¶

In Plugins → Add plugin → Install third-party plugin, paste:

dsh-plugin-session-token-stats

CLI Installation¶

# Local checkout (development scenario)
dsh plugin --profile web add /absolute/path/to/dsh-plugins/session-token-stats

# Or directly from the repository
dsh plugin --profile web add https://github.com/genius-alray/dsh-plugin-session-token-stats

After installation, refresh the page, and a bar chart entry Token stats will appear at the bottom of the left sidebar.

4. Interfaces and Data¶

The plugin registers two same-origin Host routes, both authenticated via the Connection service (unauthenticated returns 401; missing Connection service returns 403, fail-closed):

• GET /session-token-stats/data: Totals, daily buckets, session aggregation results, and scan progress.
• GET /session-token-stats/live: CPU / Load / Memory sampling ring buffer (1 Hz, keeps the last 120 samples).

Host-side logic is concentrated in server.js: log folding, sub-agent merging, CPU sampling, and the two JSON routes; Client-side logic is in client.js: main panel, sidebar entry, timeline, table, and settings. Multilingual metadata is in locale/*.json, and cordis.patch.yml only inserts this plugin’s Host row.

5. Running and Verification¶

Dependencies are simple: you need a DeepSeek Harness Web profile and dsh >= 0.2.1-rc.2; the three Host services, sessionQuery, webServer, and connection, are already present in the default Web profile.

Run self-checks and tests in the local checkout (tests use node:test and require no third-party dependencies):

npm run check   # node --check for server.js and client.js
npm test        # node --test tests/

Host tests are driven by a fake Cordis context calling apply(), using synthetic corpus to cover usage folding, peak/valley bucketing, prefix exclusion, sub-agent merging, scan caching, and route authentication; Client tests use a stub module loader to load the browser bundle, covering token formatting, cache hit rate, timeline zero-padding, browser-side preferences, and dictionary consistency.

6. Use Cases and Considerations¶

Suitable for developers who need to track session Token consumption over the long term, pay attention to cache hit rates, or want to verify local DSH process resource usage. If you just occasionally check the usage of a single sentence, it is cheaper to directly search the logs.

A few points to note:

• The plugin runs with the permissions of the current dsh process. It can read your machine’s session logs and system metrics. You should review the source code before installing to ensure the trust boundary meets your expectations. The license is MIT.
• The first scan of 500+ logs takes a few seconds (unzipping + replay validation); subsequent refreshes only re-read active sessions.
• The timeline retains 120 days. Usage older than that will still appear in the session rows and totals, but will not enter the daily chart.
• When a parent session is no longer in the local corpus (archived or cleaned), its sub-agent sessions will each become a top-level row.
• The title follows the latest session/title event; if the old log lacks this event, it falls back to the first user message.
• Not displaying costs/budgets is a design decision. If you wish to calculate costs yourself, use the token breakdown provided by the plugin.

7. Conclusion¶

The value of this plugin lies in converting DSH’s logged session data into a dashboard with clear metrics and verifiable usage: totals, cache hit rate, monthly trends, session breakdown, plus process-level resource monitoring, while deliberately avoiding cost estimation. Installation is a bundle plus a single line of command. The Host-side logic handles prefix deduplication and sub-agent merging to ensure trustworthy results.

Directory page: https://www.skillhub.cn/plugins/genius-alray/dsh-plugin-session-token-stats

GitHub: https://github.com/genius-alray/dsh-plugin-session-token-stats