dingyi222666/dsh-wakatime

English | 中文

WakaTime plugin for DeepSeek Harness (dsh) — track your AI coding activity, lines of code, and time spent. Adapted from opencode-wakatime to dsh's plugin model.

Install

# Install from npm (requires dsh >= 0.1.3-alpha.2 <0.3.0-0, declared as engines.dsh)
dsh plugin --profile web add @dingyi222666/dsh-wakatime
# Restart dsh web for it to take effect
dsh web

The plugin works in any profile that runs the agent loop — web, headless, acp, sdk, and the Desktop app's desktop profile — install it into each profile you use:

dsh plugin --profile headless add @dingyi222666/dsh-wakatime

Desktop app

The DeepSeek Harness Desktop application is an Electron shell around the same Web host, but it exclusively owns a separate profile ($DSH_HOME/profiles/desktop) and its own package state. Install the plugin there with the CLI bundled inside the app — an npm-installed dsh cannot mutate the Desktop profile:

# 1. Launch Desktop once so it initializes profiles/desktop, then fully quit it.
# 2. Run the bundled CLI (macOS path shown; Windows uses resources\runtime\cli\bin\dsh.cmd):
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add @dingyi222666/dsh-wakatime
# 3. Reopen Desktop; the bundle patch applies on the next boot.

The same command manages updates (add @dingyi222666/dsh-wakatime@latest), list, and remove <package>, and it keeps the shared Desktop profile lock and compatibility checks intact. Because both the Desktop host and its plugins run in the same Electron Node process, the tracked events and heartbeats are identical to the Web profile.

From source (GitHub)

git clone https://github.com/dingyi222666/dsh-wakatime
cd dsh-wakatime
pnpm install && pnpm run build
dsh plugin --profile web add .
dsh web

Notes:

• dsh plugin behaves like adding a dependency to your profile. A bundle plugin is loaded once its full package name appears in the profile's dsh.profile.bundles list (added automatically); the bundle patch (cordis.patch.yml) applies on the next boot.
• The bundle declares engines.dsh (>=0.1.3-alpha.2 <0.3.0-0): dsh installation and profile startup refuse a host outside that range (this replaced the peer-range check in dsh 0.2.1-alpha.3 — when engines.dsh is present, the @deepseek-ai/dsh* peers are ignored for compatibility; the <0.3.0-0 bound also excludes 0.3 prereleases).
• To update, run the same command again.
• With the repo source-launched CLI, run the args through the bin directly (node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add @dingyi222666/dsh-wakatime).

Configuration

The plugin works out of the box. To override behavior, add a row with the same id (wakatime) in your profile's user patch layer ($DSH_HOME/profiles/<name>/cordis.patch.yml) or via --patch:

- id: wakatime
  config:
    heartbeatIntervalMs: 120000  # rate limit per project (default 60000)
    debug: true                  # force DEBUG logging (default: ~/.wakatime.cfg debug=true)
    client: web                  # client qualifier in the --plugin string (default "dsh")
    timeoutMs: 45000             # heartbeat CLI timeout (default 30000)

All fields are optional and validated by a schemastery schema at load.

Features

• Automatic CLI management — downloads and updates wakatime-cli automatically, or uses a global install (brew install wakatime-cli)
• Detailed file tracking — tracks file operations the agent performs: edit, write, read, read_image, and str_replace_editor (view/create/str_replace/insert)
• Resolved-path accuracy (dsh 0.1.3-alpha.1) — reads the fs tools' durable tool/result meta: resolved (sandbox-aware) entity paths and exact diff hunks win over raw call arguments when present
• Exact write outcomes (dsh 0.1.7-alpha.1) — the write result's operation stamp (create/update) distinguishes a created file (content lines charged) from an unchanged overwrite (zero line changes, heartbeat only)
• Working-directory aware (dsh 0.2.1-alpha.2) — follows the session's committed working-directory/change records, so heartbeats, --project-folder, relative-path resolution, and the per-project rate limit retarget when the agent changes its working directory
• AI coding metrics — sends --ai-line-changes for WakaTime's AI coding analytics, computed exactly from the fs tools' diff hunks (context lines excluded)
• Live activity heartbeats (dsh 0.1.3-alpha.1) — agent/status transitions and the agent/assistant-stream firehose heartbeat the current file in near real time while a long turn streams, instead of waiting for the durable settlement
• Rate-limited heartbeats — 1 per minute per project, persisted to disk so parallel dsh processes share the budget (durable changes and live activity draw from the same budget)
• Session lifecycle — force-flushes pending heartbeats when a session is disposed and when the plugin tree tears down, so one-shot dsh --profile headless runs still report their activity
• Batch tool support — multiple files in one edit are sent in a single wakatime-cli invocation via --extra-heartbeats
• Zero runtime dependencies — the built plugin imports only Node builtins plus the @deepseek-ai/* peers the host already provides

Prerequisites

WakaTime API Key

Ensure you have a WakaTime API key configured in ~/.wakatime.cfg (or $WAKATIME_HOME/.wakatime.cfg when WAKATIME_HOME is set):

[settings]
api_key = waka_your_api_key_here

Get your API key from WakaTime Settings.

WakaTime CLI (Optional)

The plugin downloads wakatime-cli automatically when missing. To install it yourself:

brew install wakatime-cli

or download from WakaTime releases.

How It Works

The plugin subscribes to dsh's session event firehose (session/event):

flowchart TB
    subgraph dsh["DeepSeek Harness"]
        A[Agent Loop] --> B[tool/call + tool/result events<br/>(meta: resolved path + diff hunks)]
        C[Live agent events<br/>agent/status, agent/assistant-stream] --> D[Activity]
        C2[Chat Activity<br/>user/message, assistant/message, assistant/attempt] --> D
        B --> D
        D --> E[Session Events<br/>turn/end, session/disposed]
    end

    subgraph Plugin["dsh-wakatime"]
        B --> F[Join callId: extract file<br/>path + line changes from<br/>meta and fs diff hunks]
        F --> G[Per-project pending<br/>changes + last entity]
        C --> H[Rate-limited<br/>heartbeat batch]
        G --> H
        E --> I[Final force flush]
        H --> J[wakatime-cli<br/>--ai-line-changes<br/>--extra-heartbeats]
        I --> J
    end

• tool/call records the tool name and parsed arguments by callId; tool/result matches it back and reads the fs tools' durable meta payload — resolved entity paths (read, read_image), diff hunks (edit, write), and the write outcome stamp (dsh 0.1.7-alpha.1) — for exact per-hunk line counts, falling back to the call arguments when a host attaches no meta (write content, str_replace_editor strings). A write update with an empty hunk list is charged zero lines; a create is charged its content lines. Failed results — including the synthetic recovery closers agent-loop records for skipped calls when a step fails (dsh 0.2.0) — are never charged.
• Heartbeats are sent at most once per minute per project (state file under ~/.wakatime/dsh-wakatime/), on chat activity, tool results, committed model settlements (including message-less assistant/attempt records in dsh 0.1.3-alpha.1), live agent activity (agent/status, agent/assistant-stream), turn boundaries, session disposal, and plugin teardown.
• The project folder starts at the session header cwd and follows committed working-directory/change records (dsh 0.2.1-alpha.2), matching the directory the fs tools resolve against; each folder keeps its own rate-limit budget.
• The --plugin tag reports Deepseek Harness[-<client>]/<dsh version> dsh-wakatime/<version>.

Development

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run build       # declarations into lib/types + tsdown bundle lib/index.js
pnpm test            # vitest: changes, state, heartbeat, plugin wiring

Layout:

• src/index.ts — plugin entry (name / Config / apply) and event wiring
• src/config.ts — schemastery Config schema, defaults, --plugin tag
• src/changes.ts — tool events → file changes, diff line counting
• src/state.ts — per-project rate limiting
• src/heartbeat.ts — wakatime-cli invocation, batching, flushing
• src/cli.ts — wakatime-cli discovery/download/update
• src/paths.ts, src/logger.ts — WakaTime paths and file logging
• tests/ — unit tests plus an integration test that drives the plugin over a real cordis Context

Known Limitations

• Tool calls executed inside sandboxed/remote filesystems are tracked by their model-visible file_path arguments unless the tool/result meta carries a resolved absolute path (dsh 0.1.3-alpha.1 fs tools do); paths the sandbox resolves differently may land as project-relative entities.
• bash commands are not attributed to files (they can touch anything).
• The dsh host version in the --plugin tag is unknown when the @deepseek-ai/dsh package cannot be resolved from the plugin's location (e.g. an npm install without the dev dependency present).
• The @deepseek-ai/dsh-session/@deepseek-ai/dsh-agent peer ranges start at 0.1.3-alpha.1; older hosts run the tracking paths but get no live agent activity heartbeats.

License

MIT — ported logic from opencode-wakatime (MIT).