Docs — Curse Monitor CLI & plugin

Install

git clone https://github.com/Maijied/Curse-Monitor-by-Lorapok.git
cd Curse-Monitor-by-Lorapok
npm install && npm run build && npm link
curse-monitor --help

Requirements: Node.js 20+ (22+ recommended for built-in node:sqlite) and a signed-in Cursor session, or a token via env / flag.

Commands

curse-monitor              # pretty status board (default)
curse-monitor status
curse-monitor report [--group-by autoApi] [--range 7d]
curse-monitor watch [--interval 30]
curse-monitor json [--report] [-g autoApi] [-r 7d]
curse-monitor whoami
curse-monitor --help

Command	Purpose
`status`	Human-facing boxed board
`report`	Board plus grouped breakdowns
`json`	Machine-readable snapshot; `--report` adds analytics
`whoami`	Which Cursor product folder / email will be used
`watch`	Live refresh every N seconds (default 30)

Reports

Group-by: model · autoApi · surface. Ranges: 7d · 30d · cycle · mtd.

Cursor API does not expose per-model dollar spend. Model breakdown is local active-model / analytics grouping plus Auto/API meters. We do not invent per-model USD.

Group	Source
`autoApi`	Cursor usage-summary Auto % / API % plus local poll history from status/watch/report
`surface`	Local daily stats: Tab vs Composer accepted lines
`model`	Locally configured active models per surface — not a billed dollar split

Auth

Source	Priority
`--token <token>`	1
`CURSOR_TOKEN` env	2
Cursor `state.vscdb` (`cursorAuth/accessToken`)	3

The access token is never logged or written to JSON output. See Privacy.

Grok Bot / Cursor agent plugin

Template layout (no nested plugin/plugin/):

.cursor-plugin/marketplace.json
plugins/curse-monitor/
  .cursor-plugin/plugin.json
  assets/logo-animated.svg
  skills/…  commands/report.md
  README.md · LICENSE · CHANGELOG.md

Validate: npm run validate-template. Submit via cursor.com/marketplace/publish. Checklist: PLUGIN_STORE.md.

What the board shows

Field	Notes
Included pool	Bar + used / total from plan breakdown
Bonus / Agent credits	Shown when bonus > 0
Combined pool	included + bonus; remaining drives at-limit
Auto % / API %	Always when present on the plan
On-demand	Cents → USD when values look like cents
Cycle	Billing start → end + days until reset
Stale 100% banner	Yellow when API says 100% but `pool.remaining > 0`

API stub (connect later)

Placeholder Worker under api/ exposes /api/curse-monitor/health and /api/curse-monitor/usage. Responses are structured stubs with usage: null — no invented numbers, no Cursor session tokens. Later this can bind on Mission Control at cursor-dev.lorapok.tech using the sibling admin wrangler service-binding pattern. See api/README.md.

Library API

import {
  resolveAuth,
  fetchSnapshot,
  buildUsageReport,
  formatReportBoard,
} from "curse-monitor";

const auth = resolveAuth();
const snap = await fetchSnapshot(auth.accessToken, {
  email: auth.email,
  productFolder: auth.productFolder,
  dbPath: auth.dbPath,
});
const report = buildUsageReport(snap, { groupBy: "autoApi", range: "7d" });
console.log(formatReportBoard(snap, report));

CLI reference & plugin