Preface

Running agents with DeepSeek Harness (DSH) often involves multiple routes: official APIs, New API proxies, Sub2API, various Coding Plans, and more. With numerous sessions, billing information gets scattered across different consoles, making it challenging to answer two fundamental questions: How many Tokens did I consume this month? And which route or project is spending the money?

The community plugin TokenLedger (zh667/TokenLedger) addresses this pain point by integrating a “Usage Ledger” into the dsh web GUI. It attributes each request’s Token usage to the actual service relay (proxy) used and groups them by project based on the working directory. After installation, you can view summaries immediately—zero configuration required, no additional credentials needed; it only reuses existing API keys from the host when checking balances. The project has approximately 138 stars on GitHub (under the MIT license) and is maintained by zh667. It is categorized as Model Inference in the SkillHub Plugin Directory.

It is important to note that DSH’s core philosophy is “everything is a plugin,” and directories like SkillHub are independent sites with no official affiliation to DeepSeek or High-Flyer; TokenLedger itself is also a third-party community project.

What Is It

In one sentence: TokenLedger is a Token usage statistics and attribution plugin for the DSH Web GUI (npm package name dsh-tokenledger).

It aggregates usage data from the Harness event stream, normalizing traffic to the corresponding relay based on the origin (domain) derived from the provider’s baseURL—multiple keys under the same origin are merged into one row, identified by domain name rather than any custom route alias. It also attributes usage to projects based on the working directory at session start: workspaces that are registered display their titles, while unregistered ones use the directory name. Even sessions started in subdirectories are not missed.

Usage statistics, balance checks, cost estimation, and diagnostic exports use the same query set in both the panel and the command line, ensuring consistency.

Core Features and Highlights

  1. Relay Attribution: Automatically discovers baseURL from host provider configurations, read-only access without touching credentials; multiple routes under the same origin are merged for statistics.
  2. Project Attribution: Groups by cwd (current working directory), optionally associating with workspace titles; sessions without a directory are labeled “Unrecorded Directory” and not silently discarded.
  3. Balance and Subscription Quotas: Supports DeepSeek official, New API proxies, Sub2API, Moonshot/Kimi, Zhipu GLM, OpenRouter (requires Management Key), OpenCode Go, Kimi For Coding, MiniMax / Z.ai Coding Plan, and more; subscription-based plans display progress bars and reset times over rolling windows (5-hour/daily/weekly/monthly).
  4. Usage Analysis: Provides three windows—today, this month, and cumulative—with drill-down by site and model, including cache hit rate and a one-year activity heatmap.
  5. Cost Estimation: Supports tiered rate tables and peak/off-peak pricing; unpriced models display a dash, avoiding speculative guesses.
  6. Export and Diagnostics: CSV/JSON export, /tokenledger diagnostics checks route attribution and index health; rows with attribution failures are listed separately.
  7. Privacy and Security: Records only token counts, model names, route names, and site domains; does not read prompts, tool parameters, or response bodies; HTTP endpoints are restricted to local loopback GET requests and verify peer socket addresses.

The project handles several tricky edge cases in usage aggregation: usage may still flow from assistant/chunk after request failure; duplicate reports for the same (turn, step) are replaced rather than summed; orphan usage chunks fall back to the nearest request/header, and unattributed entries are marked as unknown instead of guessed.

Installation and Activation

Requires DSH’s web profile and host version @deepseek-ai/dsh >= 0.1.0-rc.6.

Run in the terminal (commands based on GitHub README and directory page):

dsh plugin --profile web add "github:zh667/TokenLedger"

After installation, restart the running dsh web and hard-refresh the browser. An “Usage Ledger” entry will appear at the bottom of the sidebar.

To upgrade or uninstall:

dsh plugin --profile web update dsh-tokenledger
dsh plugin --profile web remove dsh-tokenledger

To pin a version, use the full 40-character commit SHA; short SHAs will fail to resolve:

# Track the main branch (default)
dsh plugin --profile web add "github:zh667/TokenLedger#main"

# Example of pinning a version (SHA based on current repo commit)
dsh plugin --profile web add "github:zh667/TokenLedger#87b3d1806ac4d204a9195fc04ae8af6d6ebdd3ee"

After installation, use /tokenledger diagnostics to troubleshoot “why a relay isn’t showing”—no guesswork needed.

Typical Usage Examples

Web Panel: Access “Usage Ledger” from the sidebar to view three-window totals, distribution by day/model/site, account balance, and heatmaps.

Command Line (same source data as the panel):

/tokenledger                      # All time
/tokenledger 7                    # Last 7 days
/tokenledger 30 api.example.com   # Last 30 days for a specific relay

/tokenledger site                 # List discovered relays
/tokenledger site add <route-name> <url>
/tokenledger site rm <route-name>

/tokenledger export csv 30        # Export last 30 days as CSV
/tokenledger diagnostics          # Index and route diagnostics
/tokenledger reindex              # Discard index and rebuild fully

Optional Configuration (write to settings.yaml, hot-reloaded after changes)—most scenarios don’t require this:

tokenledger:
  relays:
    my-route: https://relay.example.com/v1
  rates: []          # Cost estimation rate table; dashes if not configured
  fingerprint: false # Relay program fingerprint detection; auto-probed once on first balance check

For providers not covered by the built-in table, you can declare balance endpoint paths via tokenledger.endpoints (must be same-origin with configured providers, only sends GET, keys still read only from the provider’s apiKeyEnv).

The package can also be used as a library by other consumers:

import { foldUsage, bySite, byModel } from "dsh-tokenledger";
import { LedgerStore } from "dsh-tokenledger/store";
import { readBalance } from "dsh-tokenledger/balance";

Use Cases and Considerations

Who Should Use It:

  • Users with multiple API routes/relays configured who need to see “which site, which model, which project” is consuming Tokens;
  • Those using New API, Sub2API, or other proxies and wanting to compare quotas and usage in one panel;
  • Those needing to export CSV/JSON for team reconciliation or monthly reviews.

Considerations:

  1. Web Profile Only: The plugin injects the sidebar and loopback API via dsh web; it is not suitable for TUI/CLI-only scenarios.
  2. Plugin Permissions: TokenLedger runs with the current dsh process permissions. Review the source code and MIT license before installation to confirm you accept its behavioral boundaries.
  3. “Unknown Routes”: If historical request routes are deleted or renamed in the provider configuration, usage is temporarily attributed to “Unknown Routes”—data is not lost; reconfigure the same route name and trigger an index rebuild to restore attribution.
  4. Balance Query Exception: Usage statistics require zero credentials; balance interfaces reuse keys stored by the host (OpenRouter requires Management Key), and the browser cannot access secrets.
  5. Community Directory Stars: Stars on SkillHub and GitHub change over time; refer to the page you opened at installation time.

Conclusion

If you’ve connected multiple routes in DSH but still worry about Token attribution, TokenLedger is worth a try: one installation command and a page refresh bring usage clarity to both relays and working directories. It is a relatively complete piece in the community’s “get it right” puzzle, with no affiliation to the official Harness but aligning well with the “everything is a plugin” ecosystem direction.