llmtrim-stats-plugin · Live llmtrim Savings Dashboard for DeepSeek Harness (DSH)

Show real-time llmtrim savings inside the DeepSeek Harness (DSH) Web UI: a full dashboard in Settings plus a rotating carousel stats strip under the composer. 在 DSH 内实时展示 llmtrim 压节省统计：设置页完整仪表盘 + 输入区轮播统计条。

中文文档: README.zh.md · LLM index: llms.txt · Agent guide: AGENTS.md

Keywords: dsh-plugin · deepseek-harness-plugin · llmtrim · compression · tokens · savings · stats · dashboard · carousel

---

📑 Table of Contents

• ✨ Features
• 🏗️ How it works
• 🚀 Quick start
• ⚙️ Configuration
• ❓ FAQ
• ⚠️ Security notes
• 📦 Project structure
• 🙏 Credits

---

✨ Features

| Feature | Description | | --- | --- | | 📊 Settings dashboard | Settings → llmtrim Stats: KPI cards (You paid / Would have cost / Saved today / Saved this week + tokens trimmed, requests, net saved re-priced), daemon health badge + version, per-model table (model / requests / saved % / USD) | | 🎠 Configurable carousel | Composer strip under the chat input: choose Rotating (cycle one stat at a time) or Static (show every selected stat at once, fixed) — pick exactly which stats appear; refreshed every 5s | | 💵 Four money cards | You paid (money.paid_usd), Would have cost (money.would_have_usd), Saved today (money.saved_today_usd), Saved this week (prorated: current-week (Monday-start) token share × lifetime money.saved_usd — llmtrim reports no weekly USD) | | 🔗 Lives off the real CLI | The host runs llmtrim status --json (the same command as llmtrim status) via the subprocess service — no ledger-file parsing, always consistent with the CLI | | 🩺 Daemon health at a glance | The dashboard shows a green/amber badge (daemon healthy / stopped) plus the binary version | | 🌗 Theme-aware | All colors use --dsw-alias-* design tokens; follows light/dark automatically | | ♨️ Survives restarts | Real profile-bundled plugin: install once with dsh plugin add, auto-loads on every DSH boot — no per-session define, no cordis_define |

🏗️ How it works

llmtrim interceptor (daemon :43117) ──writes──> ~/.local/share/llmtrim/tracking.db
                                  │
Host half (DSH process)           ▼
  └─ subprocess service: resolveExecutable('llmtrim') → spawn llmtrim status --json
  └─ reshape → { daemon, totals, money, cost, byModel }
  └─ settings namespace `llmtrim-stats` { mode, staticStats } (carousel config)
  └─ webServer routes: GET /llmtrim-stats/api (snapshot incl. config)
                       PUT /llmtrim-stats/config (persist carousel choice)
                                  │
Client bundle (browser)           ▼
  └─ single 5s poller → fetch(/llmtrim-stats/api) → snapshot fan-out to two seats
       ├─ settings.section (id llmtrim-stats)      → full dashboard + carousel config
       └─ conversation.composer.dock (id llmtrim-carousel) → rotating or static strip

• Pure pull from the CLI: no ledger parsing, no events, no file watching; llmtrim missing or status --json failing → {ok:false,error}, UI shows unavailable, polling self-recovers.
• Read-only: the plugin never writes to llmtrim's directory or ledger.
• Persistence: ships dsh.bundle (cordis.patch.yml) + dsh.client (exports["./client"], bundled) so it installs as a real profile plugin that the DSH client-modules scanner loads on every boot.

🚀 Quick start

Standard install: dsh plugin add (persists across restarts)

Install the package from this GitHub repo:

# local directory (from the parent of this repo):
dsh plugin --profile web add ./llmtrim-stats-plugin

# or directly from GitHub (any DSH machine):
dsh plugin --profile web add github:Zenjibad/llmtrim-stats-plugin
# or:
dsh plugin --profile web add git+https://github.com/Zenjibad/llmtrim-stats-plugin.git

dsh plugin add is a pnpm add into the profile plus a dsh.profile.bundles reconcile: seeing this package's dsh.bundle declaration, it appends llmtrim-stats-plugin to the bundle stack. Restart DSH, then hard-refresh the browser tab (Ctrl+F5). On boot the client-modules scanner resolves exports["./client"] and the dashboard + carousel appear. No per-session define, survives restarts.

⚠️ Important: after installing (or updating) a client plugin, a hard page refresh (Ctrl+F5) is required — the DSH client HMR only hot-swaps already-loaded bundles and does not pull in new bundles into an open tab.

Manual profile mount (alternative)

1. git clone https://github.com/Zenjibad/llmtrim-stats-plugin.git (any location).
2. Add to ~/.dsh/profiles/web/package.json dependencies: "llmtrim-stats-plugin": "link:<repo-path>", then pnpm install in the profile dir.
3. Restart DSH.

Requirements

• llmtrim installed and on PATH (npm i -g @llmtrim/cli — the plugin resolves it via the subprocess service; override with LLMTRIM_BIN if it's somewhere unusual).
• The llmtrim daemon should be running for live numbers; the plugin works (showing stopped/zero) without it.

⚙️ Configuration

The carousel is configurable from the Settings page (persisted in the llmtrim-stats settings namespace, written via PUT /llmtrim-stats/config):

| Setting | Values | Effect | | --- | --- | --- | | Mode | rotating (default) / static | Rotating cycles one stat at a time through the selected stats every 4 s; Static shows every selected stat at once, fixed (no rotation) | | Stats | 9 checkboxes (all on by default) | Which stats appear in the carousel: Saved today, Saved total, You paid, Would have cost, Saved this week, Tokens trimmed, Requests, Input saved, Round-trip |

Fixed constants in source:

| Knob | Location | Default | | --- | --- | --- | | HTTP routes | src/index.ts | GET /llmtrim-stats/api, PUT /llmtrim-stats/config | | Executable resolution | resolveLlmtrim in src/index.ts | subprocess.resolveExecutable('llmtrim'), fallback LLMTRIM_BIN, then the npm win32-x64 path | | Poll interval | POLL_MS in src/client/index.tsx | 5 s | | Carousel cadence | CAROUSEL_MS in src/client/index.tsx | 4 s | | Settings seat | src/client/index.tsx | settings.section id llmtrim-stats, order 80 | | Dock seat | src/client/index.tsx | conversation.composer.dock id llmtrim-carousel, order 15 |

❓ FAQ

Q: The dashboard/carousel is missing? A: Restart DSH (if the host half isn't mounted yet), then hard-refresh the browser tab (Ctrl+F5). New client bundles only appear on a full page reload — the HMR client does not add new bundles to an already-open tab.

Q: It says "llmtrim stats are unavailable"? A: The host couldn't run llmtrim status --json. Check llmtrim --version works in a shell; if it's not on PATH, set LLMTRIM_BIN to the absolute exe path and restart DSH.

Q: The carousel shows zeros / "daemon stopped"? A: The daemon isn't running (llmtrim start), or the ledger is empty. Start the daemon and the numbers populate on the next 5s poll.

Q: "Saved (proxy bills)" vs "Net saved (re-priced)" differ? A: Both come straight from llmtrim status --json — money.saved_usd (per-turn frozen rates) vs cost.net_saved_usd (re-priced at current list rates). They're different views of the same traffic; llmtrim's own CLI shows the same distinction.

Q: How is "Saved this week" computed? A: llmtrim reports money only for the lifetime (money.saved_usd) and today (money.saved_today_usd); its by_period rows carry tokens but no USD (daily 2026-08-19 keys by default). The plugin therefore prorates: input tokens this week (Monday-start) ÷ lifetime input tokens × lifetime saved. It updates as the ledger grows.

Q: Can I make the carousel show only one stat, or stop it rotating? A: Yes — Settings → llmtrim Stats → Carousel: set Mode to Static and tick exactly the stats you want. Static shows every selected stat at once (fixed, no rotation); a single tick pins it to that one stat. Rotating mode cycles one stat at a time through the ticked stats. A green "Saved ✓" appears after each change; the choice is persisted and survives restarts.

Q: How do I remove it? A: dsh plugin --profile web rm llmtrim-stats-plugin (or delete the profile dependency + bundle entry) and restart DSH.

⚠️ Security notes

• Read-only: the plugin only runs llmtrim status --json and never writes to llmtrim's files or ledger.
• Same-origin route: the client polls /llmtrim-stats/api on the DSH origin only.
• No credentials: the plugin reads no API keys, tokens, or secrets — only the public savings snapshot.
• Small outputs: status --json stdout is capped at 512 KB.

📦 Project structure

llmtrim-stats-plugin/
├── src/
│   ├── index.ts            # host half: resolve llmtrim, spawn status --json, reshape, /llmtrim-stats/api + /llmtrim-stats/config routes, settings namespace
│   └── client/index.tsx    # client bundle: 5s poller, settings dashboard, configurable dock carousel
├── cordis.patch.yml        # dsh.bundle patch (inserts the plugin row on boot)
├── tsdown.config.ts        # bundles host (node ESM) + client (CJS ModuleLoader)
├── package.json            # name, exports["./client"], dsh.client + dsh.bundle
├── lib/                    # build output (index.js, client.js)
├── AGENTS.md               # repository guide for AI agents
├── llms.txt / llms-full.txt
├── README.md / README.zh.md
└── LICENSE

🙏 Credits

• llmtrim — the compression interceptor and llmtrim status --json data source.
• DeepSeek Harness — the DSH plugin/dynamic runtime, Slots, theme, webServer, client-modules.
• headroom-stats-plugin — reference for the packaged client-plugin build pattern (tsdown host/client split, cordis.patch.yml, dsh.client, settings + dock seats).

📄 License

MIT

Repo

Requires DSH ≥ 0.1 with the web profile.