Preface

DeepSeek Harness (dsh web) currently has no official usage or billing API, making it difficult for developers to track actual charges. The dsh-usage-calendar plugin calculates actual charges by sampling balance decreases and provides a calendar view that aggregates token usage, cache hit rates, and other data across all local sessions.

Features

Balance Query
Queries account balance via the official API, cached for 1 second. The interface auto-refreshes every 1 second and supports manual forced refresh.

Calendar View
Aggregates token usage for all local sessions by day. Active sessions use in-memory logs, archived sessions use ctx.sessionQuery, so historical dates are also complete. Supports month switching and “Today”.

Daily Actual Charges
DeepSeek has no usage/billing API. The plugin persists each sampled balance reading, treats balance decreases as charges, and aggregates them by day. This reflects the amount actually deducted by the platform and does not distinguish by model.

Local Estimate
Estimates each item according to official pricing for comparison.

Cache Hit Rate
Calculates cacheRead / (input + cacheRead + cacheWrite) (prompt side).

Local Statistics
Reads only local session event logs and the balance API; no data is uploaded.

Installation and Enablement

Use the npx installer:

npx --yes github:xiyi123465/dsh-usage-calendar

The installer copies the package to $DSH_HOME/profiles/node_modules/dsh-usage-calendar and takes effect after restarting dsh web.

Typical Usage

  1. Click the calendar panel to view detailed usage for historical dates (active sessions use in-memory logs, archived sessions use ctx.sessionQuery).
  2. Click the balance capsule to manually force refresh the balance.
  3. Use the --local-only option to aggregate only usage for the local key.
  4. Use node scripts/import-actual.mjs to backfill historical data.
  5. Configure the API Key via the llm-deepseek settings namespace.

Notes

  1. Charge calculation method: DeepSeek has no usage/billing API; charges are calculated by sampling balance decreases.
  2. Data accuracy: Amounts are accumulated in integer cents and do not drift when data is collapsed.
  3. Privacy and security: Reads only local session event logs and the balance API; no data is uploaded.
  4. Reconciliation warning: If an actually measured day differs from the local estimate by more than 1.5×, a warning is shown.
  5. Settlement delay: Server-side settlement is delayed, and calls spanning midnight may be recorded on the next day.

Summary

dsh-usage-calendar uses balance sampling and local log aggregation to address the lack of an official usage API from DeepSeek, providing a visual calendar view for cost tracking.