Introduction

dsh-token-meter in DeepSeek Harness provides real-time token metering but does not include cross-session aggregate reports. When users need to know things like “How many tokens did I use this month?” or “Which model uses the most tokens?”, they usually have to manually review logs. The dsh-token-stats plugin addresses this issue: it listens for session events, automatically writes logs, and provides the token_report tool for aggregate queries.

Features

This plugin provides the following core capabilities:

  • Automatic logging: Listens for session/event events and automatically writes a log entry containing counts and the session ID whenever an assistant/message includes a usage field.
  • Aggregate reports: Supports aggregation by day, week, month, or all data, with filtering by model and date range.
  • Tool support: Provides the dsh-token-report command-line tool and the token_report tool, which can be called by the model in a DSH session.
  • System guidance: Uses system prompt instructions to guide the model to call token_report when users ask about token usage.

Installation and Setup

System Requirements

  • Operating system: Linux or macOS (Windows is untested).
  • Environment: DeepSeek Harness CLI (dsh) and its profile are installed.

Installation Command

Use the official plugin installation command:

dsh plugin --profile headless add github:QEDQCD/dsh-token-stats

After installation, the plugin automatically attaches the token_report tool to the corresponding profile.

Usage Examples

Command-line View

Run dsh-token-report directly in the terminal to view summary data:

dsh-token-report                  # Today + this month + total summary
dsh-token-report --by day         # Daily details
dsh-token-report --model deepseek # Filter by model

Model-side Invocation

In a DSH session, the model can proactively call the tool:

token_report(period: "month")
token_report(period: "month", model: "deepseek-chat")

Limitations and Privacy

Privacy and Security

The log file is stored at ~/.dsh/token_usage.l and contains only token counts and session IDs, not prompt content or API keys.

Known Limitations

  • Storage path: The log file path is fixed to ~/.dsh/token_usage.l.
  • Recorded content: The model name cannot currently be recorded.
  • Configuration item: The maxRecords configuration field is declared but not implemented, so the number of records is currently not limited.
  • Compatibility: Codex is not supported.
  • Operating system: Only Linux/macOS are supported; Windows has not been tested.