Introduction

In the plugin mode of DeepSeek Harness (DSH), the model invocation itself can run normally, but after multiple sessions, token usage often lacks unified persistence. Relying solely on single-call logs makes it difficult to answer questions like “how many tokens were spent recently,” “how many tokens were used by a specific model,” or “whether the budget is approaching the limit.”

Below is an introduction to dsh-cost-ledger. It is a DSH plugin used to record LLM token usage into SQLite and provides three agent tools: record_cost, query_cost, and set_budget.

What is this

The positioning of dsh-cost-ledger is DSH’s cross-session persistent cost ledger. The GitHub repository is located at https://github.com/suimi8/dsh-cost-ledger with an MIT license. According to verified information, the package.json author is empty, and maintainer information is subject to the current content of the repository.

The problem it solves is: LLM token usage in DSH can be automatically recorded per provider call and persisted via SQLite for subsequent querying and budget setting. According to verified information, Phase 1 host side is complete and live-verified in DSH 0.1.0-rc.6.

Core Capabilities

Automatic Token Usage Recording

The plugin subscribes to the llm/stream waterfall. Each provider call writes a record with fields including:

  • timestamp
  • session
  • project
  • model
  • inputTokens
  • outputTokens
  • cacheReadTokens
  • cacheWriteTokens
  • cost

According to verified information, the usage chunk is not guaranteed to exist; it will be recorded as debug if missing.

SQLite Persistence

The plugin uses SQLite for persistent storage and depends on better-sqlite3.

DeepSeek Pricing

The plugin comes with built-in DeepSeek pricing and supports overriding or adding model prices via configuration.

For unknown models, tokens will be recorded first with a cost of 0 until a price is set.

Agent Tools

The plugin provides three agent tools:

  • record_cost: Manually record a usage entry.
  • query_cost: Query costs.
  • set_budget: Set a budget.

Installation and Enablement

Environment Requirements

The package.json engines requirements:

node ^22.19.0 || >=24.0.0

Installation

Install using the DSH plugin command:

dsh plugin --profile web add <path-or-package>

Restart after installation:

Restart dsh web

If installing via git and pnpm >= 10 blocks the prepare script of git dependencies, you need to configure allowBuilds in the profile’s pnpm-workspace.yaml to allow the package, then reinstall. Refer to the pnpm output for the specific package key.

Local Development and Loading

You can execute the following during local development:

pnpm install
pnpm selftest
pnpm typecheck
pnpm build

Then load via patch:

dsh web --patch ./cordis.patch.yml

Typical Usage

Verify Real LLM Invocation

You can use the headless profile to verify if real LLM invocations generate ledger entries:

dsh --profile headless "reply with exactly: hi"

Using Agent Tools

Once enabled, you can call the following in the agent:

  • record_cost
  • query_cost
  • set_budget

Refer to the repository README and source code for specific parameters.

Configuration and Persistence

According to verified information:

  • Configuration in dashboard settings is runtime and not persistent after restart.
  • WebUI plugin config card or cordis.patch.yml can be persistent.
  • Configuration can be used to override or add model prices.

Use Cases and Notes

  • Suitable for developers who need to view token usage, costs, and budgets across sessions within DSH.
  • The plugin runs with the current DSH process permissions; check the source code and license before installing.
  • Verified DSH version is 0.1.0-rc.6, last verified 2026-08-13.
  • WebUI dashboard panel is only researched, not implemented.
  • According to verified information, the README and package.json are both truncated; actual dependency, limitation, or compatibility information should be based on the current repository source code.

Links

GitHub: https://github.com/suimi8/dsh-cost-ledger

The directory page URL is not provided in verified information and is not listed for now.