devspm

Transparent, metadata-only project activity reporter — the client-developer plugin for the Project Monitor portal.

What it sends (and what it never sends)

devspm reports work metadata only to your project's monitoring server:

• commit hash, branch name, commit message
• per-file change stats (path, lines added/removed)
• commit timestamps and coarse activity intervals (5-minute buckets)
• the repository's folder name
• the devspm version you are running
• only if you run devspm usage: Claude Code token counts — a date, a model name and four numbers per day. Never prompts, replies or file contents.

It never reads or transmits file contents, diffs, or credentials. The upload contract (src/schemas.js) is strict-validated on both ends — fields for code simply don't exist. Verify anytime:

devspm log        # the exact JSON payloads that were sent
devspm open       # your personal read-only dashboard on the server

Install & enable

npm install -g devspm
cd your-repo
devspm init --server https://staging-project.sages.work --key pm_live_xxxx

--server is the origin of the Project Monitor dashboard your agency runs — not your git remote, and not the site you are building. For SAGE projects that is https://staging-project.sages.work (staging) or https://project.sages.work (production); your key is issued against one of the two and is rejected by the other.

init validates the key, prints the data policy, and asks for confirmation before touching anything. It appends a shim to .git/hooks/post-commit (coexists with husky/lefthook; never blocks or slows a commit).

Commands

| Command | Purpose | |---|---| | devspm init [--key --server --yes] | Enable for this repo (consent-gated) | | devspm start | Foreground watcher for accurate active-hours (optional) | | devspm usage [--dry-run] [--all] | Report Claude Code token counts for completed days | | devspm flush [--quiet] | Upload queued events now (runs automatically after commits) | | devspm status | Config, hook, queue depth, last upload | | devspm log [--pending] [-n N] | Show sent (or queued) payloads verbatim | | devspm open | Open your self-view dashboard | | devspm uninstall | Remove the hook + config for this repo |

How it works

Events append to a local queue (~/.local/share/devspm/<hash>/queue.jsonl, where <hash> is derived from the repository's path). A detached flush uploads them in batches; offline events wait for the next flush. Sent events move to sent.jsonl together with the server's response — that ledger is what devspm log prints. Retries are safe: every event has a UUID and the server counts replays as duplicates, not new data.

Requires Node.js ≥ 18 and git.

Keeping up to date

devspm updates itself. After a flush it checks the npm registry at most once a day, and if a newer version exists it runs npm i -g devspm@latest in the background. You never need to think about upgrading.

Stating that plainly because it is a change to software on your machine: the check happens in the detached process that uploads events, never in your commit, and every failure — offline, a registry timeout, an npm prefix that needs sudo — is a silent no-op that leaves your working version alone.

To turn it off:

export DEVSPM_NO_AUTO_UPDATE=1

Versions before 0.2.0 cannot self-update — they were built without the updater. If you are on one, run npm i -g devspm@latest once and it is the last time you will need to.

Licence

MIT. See LICENSE.

Full setup walkthrough, file locations, endpoint reference and troubleshooting: devspm Integration Guide.