Introduction¶

After running DeepSeek Harness (hereinafter referred to as DSH) for a while, one often wants to know two things: which sessions this month burned tokens on, and which model took the largest share. The host’s built-in interface provides usage data for individual requests but does not offer aggregation by session, by model, or by day. One can calculate it by digging through logs and writing scripts, but long-term tracking requires doing it repeatedly.

dsh-token-dog solves the “aggregation step”. It does not create a new ledger; it directly reads the already-disked Session logs, and once installed, you can see historical usage without recounting from the day of installation. Below is an introduction to the positioning, features, installation method, and data scope of this plugin.

What is this?¶

dsh-token-dog (Chinese name: Token Puppy) is a DSH client plugin, maintained by ccodeJava, categorized as a client. It adds a “Token Usage” panel to the DSH Web GUI: statistics on token consumption by session and by model, a daily stacked bar chart to show the composition over a recent period, and a yearly calendar heatmap to show activity levels. The plugin only displays data; it does not rewrite any host state.

The accompanying directory page is on skillhub.cn; see the end of the article for the repository address.

Core Features¶

Overview Page¶

The page is divided into five blocks:

• Stats Card: Total Tokens, Cache Hit Rate, Output Tokens, Call Count; Sub-row shows session count, cache vs. input split, output ratio, average daily calls.
• Daily Consumption: One bar per day, segments within the bar by session, max 6 segments per day, the rest merged as “Other”; hover to see that day’s total, call count, and details of the top 4 sessions.
• Model Usage: Total, call count, and number of sessions involved for each model, with a percentage bar in the row. Rows are clickable, entering that model’s details page.
• Session Ranking: The 8 sessions with the highest consumption, including call count and last used date.
• Active Calendar: Last 52 weeks, cells starting on Monday, 5 levels of intensity; hover to see that day’s total Tokens, call count, session count, and each model’s usage and share for that day.

Model Details¶

Clicking a model row enters the details page. The top changes to “Back” plus the model name, and the content is replaced with that model’s stats card, daily bar chart, and a complete list of sessions that consumed this model (not truncated). The interval switch at the top also applies to the details page.

Interval and Appearance¶

• Interval Switch: Last 7 days / Last 30 days / Last 90 days / All, applies to stats card, bar chart, ranking, and model details.
• Theme: 8 low-saturation preset colors (Mist Blue, Cyan, Moss Green, Wheat, Terra Cotta, Lotus Purple, Red Bean Paste, Neutral), plus a custom color picker; three levels of “Light / Medium / Bold” control the intensity of the same color set, affecting only bars and heat levels. The color scheme is saved in localStorage.
• Bilingual: Text follows the host language, falling back to Chinese if the dictionary is missing.
• Sidebar Icon Toggle: The puppy icon in the left sidebar can be turned off in the top-right corner of the page; after closing, it can still be accessed via Settings → Token Usage.

Installation and Enablement¶

The plugin is not published to npm and does not require building; the repository directory itself is installed. The prerequisite is that DSH (Desktop version or dsh web) is installed, version 0.2.x.

Step 0: Get the Directory¶

git clone https://github.com/ccoderJava/dsh-token-dog.git

If you don’t have git, you can unzip by clicking Code → Download ZIP on the repository page.

Method 1: Let the Agent in DSH Install It¶

Open any session in DSH and send the following sentence to the Agent, replacing the path with the actual path you cloned:

Install the directory /Users/you/plugins/dsh-token-dog as a plugin

The Agent will call the built-in plugin_manager to complete the installation: writing dsh-token-dog into the current profile’s package.json (pointing to that directory via link:), and adding it to dsh.profile.bundles. If the application in the return is applied, it means it has taken effect.

Method 2: Command Line¶

In an environment where dsh CLI is installed (Desktop version usually doesn’t have CLI, so use Method 1):

dsh plugin --profile desktop add link:/absolute/path/to/dsh-token-dog

desktop is the profile name, defaulting to desktop; CLI users might be default.

After Installation¶

Refresh the page (Cmd/Ctrl + R). There are two entry points: the puppy icon at the bottom of the left sidebar (opens the whole page), or Settings (gear icon) → “Token Usage” as the last item in the left navigation. The first time it opens, it scans historical sessions; results are cached for 60 seconds afterwards.

To confirm installation success:

• Settings → Plugins → Installed: You can see Token Puppy (package name dsh-token-dog) with a puppy icon;
• The puppy icon appears in the left sidebar;
• To confirm the data pipeline via command line:

curl -s "http://127.0.0.1:<GUI 端口>/token-dog/usage?tz=Asia/Shanghai" | head -c 300

Update and Uninstall¶

Method 1 installs a soft link; changing or pulling code and refreshing the page takes effect without needing to reinstall:

cd dsh-token-dog && git pull

To uninstall, tell DSH “uninstall the dsh-token-dog plugin” (via plugin_manager’s remove_bundle), or run via command line:

dsh plugin --profile desktop remove dsh-token-dog

Typical Usage¶

Why did usage suddenly spike on a certain day?¶

Open the overview page, hover over a corresponding day on the daily consumption chart, to see that day’s total, call count, and details of the top 4 sessions. If you want to know how much each model took on that day, switch to the active calendar and hover over the same day.

Drill down by model¶

Click a row in the Model Usage block to enter that model’s details page, to see its own daily curve and all sessions that consumed it. Return to the overview using the “Back” at the top.

Shrink time range¶

The top interval switch applies to stats card, bar chart, ranking, and model details. Use last 7 days or last 30 days for short-term fluctuations, and last 90 days or All for long-term trends.

Adjust color scheme¶

Select a preset color from the row of dots in the top-right; the last dot enters the custom color picker. Adjust intensity with “Light / Medium / Bold” next to it. The color scheme is persisted and remains after refresh.

Data Scope¶

The plugin does not create a new ledger; data comes only from Session logs (ctx.sessionQuery). It replays several types of events from the logs to piece together the usage for each call:

Several key metrics:

• Deduplication for single calls is based on turn:step:attempt, later samples of the same attempt overwrite previous ones.
• Total Tokens = input + cacheRead + cacheWrite + output, four buckets do not overlap.
• Cache Hit Rate = cacheRead / (cacheRead + input).
• Not counted: calls not in any Session log, such as title generation or compression, which are background calls. This is a trade-off of “logs as the single source of truth”.

The Host side registered a read-only route, accessible only via local loopback:

GET /token-dog/usage?tz=Asia/Shanghai[&refresh=1]

The response body aggregates results into rows with dimensions day / session / provider / model, example:

{
  "ok": true,
  "generatedAt": 1793860698515,
  "scanMs": 672,
  "timeZone": "Asia/Shanghai",
  "rows": [
    { "day": "2026-11-04", "session": "session-…", "provider": "deepseek-account",
      "model": "deepseek-flash", "input": 344317, "cacheRead": 8053120,
      "cacheWrite": 0, "output": 141471, "calls": 138 }
  ],
  "sessions": { "session-…": { "title": "…", "createdAt": 1793, "cwd": "…", "origin": "", "parent": "" } },
  "scanned": 26, "skipped": 0, "failures": 0, "failureSample": []
}

Full scan results are cached for 60 seconds; refresh=1 forces an immediate rescan. During a scan, the same scan is reused, no overlapping concurrent scans. Returns 403 when the request has forwarding headers (X-Forwarded-For / CF-Connecting-IP), cross-origin, or a non-loopback address. Data does not leave the network; the browser only requests the local machine 127.0.0.1.

Suitable Scenarios and Notes¶

Suitable for those already using DSH who want to figure out where tokens are spent on sessions and models. Its value lies in “see history upon installation”: because it reads existing logs, conversations before installation are also counted, and no need to switch to a new bookkeeping method.

Points to note:

• The plugin runs with the permissions of the current dsh process. The host-side route is registered inside the host process. You should read the source code (index.js, client.js, cordis.patch.yml) and confirm the license (MIT) before installing.
• Only calls written to Session logs are counted. Calls like title generation and compression are not counted, so it is normal for the numbers not to match the bill; the plugin does not perform price conversion.
• The scan window is sessions created within the last 400 days or currently online, max 600, a warning appears when exceeded.
• Daily bar charts only draw the last 120 days if over 120 days; bars only appear on days with usage, no placeholder for days with zero usage.
• Calendar heat levels are graded by quantiles of the day’s tokens, recalculated across themes and intervals, so intensity between two intervals cannot be compared directly.
• The plugin depends on the host’s settings.section / main / sidebar.panellist slots and the sessionQuery service; behavior of these slots needs to be re-validated after a major DSH version upgrade. The verified environment noted in the README is DSH 0.2.1-rc.5 (Desktop, macOS).

Conclusion¶

dsh-token-dog is quite restrained: it doesn’t create new data sources or introduce external dependencies; it only organizes existing logs on the host into a drill-down view, and the data pipeline is also closed on the loopback interface. For DSH 0.2.x users, it is a supplement to the existing Web GUI; install the directory and use it.

Directory page: https://www.skillhub.cn/plugins/ccoderJava/dsh-token-dog
Repository: https://github.com/ccoderJava/dsh-token-dog