Introduction

When running DeepSeek Harness, Codex, or OpenCode locally, tracking token consumption is essential for cost control. Typically, this data is scattered across local logs, making cross-session aggregation and analysis difficult. The tool introduced in this article reads local logs, aggregates token data from three sources, and provides both a visual dashboard and a command-line tool for cost estimation and cache-hit-rate monitoring.

What Is dsh-token-usage-observer

This is a DeepSeek Harness plugin provided by maintainer RyzenWang and released under the MIT License. Its core function is to collect, aggregate, and display local token usage for DeepSeek Harness, Codex (ChatGPT), and OpenCode, including cache-hit status and estimated costs, while never modifying the original data.

Core Features

  1. Data Aggregation and Calculation: The plugin aggregates token usage from three sources (input, cache hits, cache writes, and output), and calculates cache-hit rates and estimated costs.
  2. WebUI Sidebar Dashboard: After installation, a “Token Statistics” entry appears in the WebUI sidebar. The dashboard supports filtering by source, time range, category, and grouping dimensions, and provides an aggregate distribution chart (stacked bar chart) along with a per-session detail list.
  3. Agent Tool: Provides the usage_stats tool, which supports explicit invocation through the command line and returns grouped statistics along with a detail table.
  4. Session Name Resolution: Automatically resolves session names: for Harness it reads session/title, for Codex thread_name, and for OpenCode session.title; when missing, the session ID is used.
  5. Price Configuration: Supports configuring per-million-token pricing. Default values are set according to DeepSeek’s public pricing.

Installation and Activation

Install it using the dsh plugin command:

dsh plugin --profile web add "github:ZhengDaoWang/dsh-token-usage-observer"

After installation or updating, you need to restart dsh web for the “Token Statistics” entry and dashboard to load.

Typical Usage

After installation, you can ask directly in the conversation:

  • “Track token usage on my local machine”
  • “Show how many tokens Codex used this week”
  • “Group August usage by day for DeepSeek models and estimate cost at public pricing”

You can also explicitly invoke it by the tool name usage_stats. Supported parameters include:
* source: data source (all, deepseek-harness, codex, opencode)
* from / to: start and end dates (YYYY-MM-DD)
* category: category filter (model ID or preset substring)
* groupBy: grouping dimension (source, category, day, none)
* prices: price override object

Data Sources and Configuration

The plugin reads local log files. Default pricing values are as follows (per million tokens):
* Input: $0.14
* Cache hits: $0.014
* Output: $0.28

Data source locations include:
* DeepSeek Harness: ~/.dsh/sessions/<encoded-cwd>/session-<uuid>/session.jsonl[.zstd]
* Codex: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
* OpenCode: ~/.local/share/opencode/opencode.db

You can override the log root directories for Harness and Codex using the environment variables DSH_HOME or CODEX_HOME. The plugin silently skips corrupted or unreadable files.

Notes

  • The plugin accesses local logs in read-only mode and does not modify any data.
  • It is recommended to review the source code and license before installation.

Summary

This tool reads local logs and provides developers with a unified view for monitoring token consumption across DeepSeek Harness, Codex, and OpenCode. Combined with the WebUI dashboard and Agent tool, it simplifies cost estimation and usage analysis.

GitHub: https://github.com/RyzenWang/dsh-token-usage-observer