# dsh-usage-stat

<p align="center">
  <a href="README.md">简体中文</a> · <strong>English</strong>
</p>

<p align="center">
  <a href="https://github.com/oujnit/dsh-usage-stat/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/oujnit/dsh-usage-stat/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/oujnit/dsh-usage-stat/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/oujnit/dsh-usage-stat"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

A local-first home dashboard for DSH Desktop. It appears automatically when no other conversation is open and remains available from the top navigation below New Session.

The plugin aggregates local DSH session logs in read-only mode. It does not modify sessions or send usage data to an external service.

## Features

- Active projects, sessions, model calls, and token usage for today, this week, and this month;
- 30-day token trend, active-day count, and peak date;
- Cache reuse rate, average output size, primary model, and per-model totals;
- Recent sessions and project activity;
- Scan duration, unreadable-session count, and generation time;
- A five-minute in-memory cache with explicit refresh.

The Host reads at most four sessions concurrently. A damaged or unreadable session is isolated and reported instead of failing the whole dashboard.

## Install

Install a fixed release into DSH Desktop's `desktop` profile:

```sh
dsh plugin --profile desktop add https://github.com/oujnit/dsh-usage-stat/releases/download/v0.2.3/dsh-usage-stat-0.2.3.tgz
```

To follow the `main` branch instead:

```sh
dsh plugin --profile desktop add github:oujnit/dsh-usage-stat
```

Check the composed configuration:

```sh
dsh --profile desktop --dump-config
```

Quit and reopen DSH Desktop. Open **Settings → Plugins → Plugins** and confirm that `usage-stat` is running and enabled.

Remove the plugin with:

```sh
dsh plugin --profile desktop remove dsh-usage-stat
```

## Measurement

- A model call is an `assistant/message` model event in the session log, including subagent calls.
- Token values are the provider-reported input, output, cache-read, and cache-write fields stored by DSH.
- Calendar days use the Host's local timezone. Weeks start on Monday.
- Cache reuse rate is cache-read tokens divided by ordinary input plus cache-read tokens.
- Projects are grouped by the workspace path stored in each session. Recent activity uses the final event time.

Missing provider usage fields count as zero. This dashboard reports session-log activity, not monetary billing, and does not replace a provider's official invoice.

## Privacy and security

The plugin has no telemetry integration, makes no external upload, and does not write to sessions. Its browser client reads a same-origin `/api/usage/state` endpoint served by DSH.

The response includes session titles, workspace paths, and model names. If you expose DSH Web beyond the local machine, keep DSH's access controls in place and do not publish an unprotected server to untrusted users.

## Compatibility

`v0.2.2` has been verified with:

- DSH Desktop 2.0.2;
- bundled DSH 0.1.1-rc.2;
- macOS on arm64;
- the home dashboard coexisting with the Task Board, SSH, and Skill Center entries in the light theme.

The browser contribution uses the sidebar and center-panel surfaces provided by the current DSH Desktop Web UI. A major Web UI structure change may require a plugin update.

## Development

Use Node.js `^22.19.0 || >=24.0.0` and pnpm 11.7.0:

```sh
pnpm install --frozen-lockfile
pnpm run check
pnpm pack --dry-run
```

Install the local checkout with:

```sh
dsh plugin --profile desktop add .
```

Built output under `lib/` is committed, so a GitHub installation does not run a build script on the user's machine.

## License

[MIT](LICENSE)