DeepSeek Harness Token Usage Statistics Plugin

The design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” In agent development and debugging, it is common to track session input, output, and cache-read token statistics. The dsh-token-usage plugin is designed to address this need. It reads local session logs, aggregates token usage data, and provides two access methods: a Web sidebar panel and an Agent tool.

Plugin Overview¶

This is a token usage statistics plugin maintained by joyiok. Its core value is “authoritative counting”: it does not rely on estimates, but directly reads DSH session log files, counts each (turn, step) only once, and includes built-in multi-frame zstd decoding capability, requiring no external dependencies.

Core Features¶

The plugin mainly provides the following capabilities:

1. Web sidebar: Adds a Tokens button at the bottom of the Web client. Clicking it lets you view the all-time total, today’s, and per-session details for input, output, and cache-read tokens.
2. Agent tool: In headless or Web sessions, retrieves statistics through the registered token_usage tool, with support for a scope parameter to limit the query range.
3. Authoritative counting: Reads $DSH_HOME/sessions/**/session.jsonl(.zstd), uses the built-in decoder to parse the data, and ensures accurate statistical criteria.

Installation and Enablement¶

Installing the plugin requires adding the plugin directory to a DSH profile. Run the corresponding command based on your use case (Web or Headless).

cd /home/joy/Documents
dsh plugin --profile web add /home/joy/Documents/token-usage-dsh-plugin
dsh plugin --profile headless add /home/joy/Documents/token-usage-dsh-plugin

After installation, restart dsh web. The client scans the Typert manifest, and the configuration takes effect after a restart. You can verify this with dsh --profile web --dump-config; the output should contain the dsh-token-usage configuration section.

Usage¶

Web sidebar¶

On any active session page, a Tokens icon appears in the lower-left corner. Clicking it displays the following:

• Summary view: all-time total / today’s input, output, input + output, cache reads, total including cache, and LLM steps.
• Session details table: lists each session’s title, model, input/output/cache-read token counts, and last activity time.

Agent tool¶

Ask for token usage directly in the conversation. The Agent will call the token_usage tool and return the result.

Example:

用户：我一共用了多少 token？
Agent：调用 token_usage(scope: "all") 后回答

Tool parameters:

Configuration¶

The plugin supports overriding settings in cordis.patch.yml within a profile. Note that the entire config line must be overridden.

- id: token-usage
  config:
    cacheTtlMs: 8000        # 聚合缓存毫秒数
    maxToolSessions: 20     # token_usage 工具最多返回的会话数

To disable the plugin, you can add the following to the configuration:

- id: token-usage
  disabled: true

Technical Details and Notes¶

• Log path: The plugin reads $DSH_HOME/sessions/**/session.l(.zstd).
• Calculation formula: totalTokens = inputTokens + outputTokens. The total including cache, totalWithCache, additionally counts cacheReadTokens and cacheWriteTokens.
• Decoding mechanism: The plugin has built-in multi-frame zstd decoding. If the built-in decoder fails and a zstd CLI exists in the system PATH, it automatically falls back to invoking that command-line tool.

References¶

• Plugin Directory Page
• GitHub Repository