Visualize the usage events CSV exported from the Cursor dashboard.
- Terminal: summary and bar charts right in your terminal
- Dashboard: a local web dashboard — just drag & drop your CSV
Runs on Node.js 20+ (npx) or Bun (bunx).
- Japanese and English — choose the dashboard language from the globe icon; export PNGs in either language
- Local-only analysis — drag & drop a Usage Export; data stays in the browser and is never sent anywhere
- Daily Window cost trends — stacked bars by Model Family plus a cumulative line, with click-through to a per-window detail view
- Model Family grouping — reasoning effort / thinking / fast variants are collapsed, and Auto (Cursor Router) is one slice; click it to see the actual Models the Router selected
- User breakdown & filter — Top 10 costs per User; click a bar to focus the whole analysis on one User
- High Spend events — the most expensive events at a glance, with Cloud Agent / Automation / Max Mode / Fast Mode Event Labels
- Daily Window detail — hourly cost, Kind breakdown, and every event in the window
- CLI parity — the same breakdowns in the terminal, or as JSON for scripting
- Screenshots & daily report — capture the Overview or a shareable Daily Window PNG
npx @jnst/cursor-usage # or: bunx @jnst/cursor-usageStarts a local server and opens your browser. Drag & drop a CSV exported from Cursor onto the page. All data is processed in the browser and never sent anywhere.
Use the globe icon in the upper right to choose 日本語 or English, even before loading a CSV. The first visit uses the first supported browser-preferred language, falling back to English. An explicit choice is saved for that browser origin and takes priority on subsequent visits; only the language preference is stored. Changing language preserves the loaded CSV, filters, and Spend visibility. The Analysis Time Zone, USD amounts, and CSV values are independent of the display language.
Click any bar in the Daily Window cost chart to drill into that window (hourly breakdown, per-model-family / per-user / per-kind costs, and every event in the window). Spend charts group Models by Model Family — variant suffixes such as reasoning effort and fast mode are collapsed, and usage routed through Auto (Cursor Router) is shown as one Auto slice. Click a slice in the Model Family pie to see the Models inside it; for Auto this reveals the actual Models the Router selected. Click a user bar to filter the current analysis to that User; the selected User remains visible while other users are dimmed, and clicking the selected user again clears the filter. The selected Daily Window, user, and analysis time zone are reflected in the URL hash (#daily-window=YYYY-MM-DD&user=jnst%40example.jp&timezone=Asia%2FTokyo), so the browser back button and shareable links work after loading the same CSV.
The default port is 4321; if it is already in use, a free port is picked automatically. When --port is specified explicitly, that port is used as-is.
npx @jnst/cursor-usage serve --port 8080 --no-opennpx @jnst/cursor-usage stats team-usage-events.csvCursor Usage 2026-06-01 – 2026-06-10 (610 events, 10 daily windows)
Total Spend $1446.69 Total Tokens 1.1B
Avg Daily $144.67
Models 8 Users 4
Daily Window Spend
2026-06-01 $147.44 ████████████████▊ 10% 102.9M tok, 68 ev
2026-06-02 $246.57 ████████████████████████████ 17% 180.0M tok, 79 ev
...
By Model Family
GPT-5.5 $954.95 ████████████████████████████ 66% 804.2M tok, 472 ev
Opus 4.8 $357.92 ██████████▌ 25% 135.5M tok, 69 ev
...
Options:
| Option | Description |
|---|---|
--by <daily-window|user|model|model-family> |
Show a single breakdown axis |
--daily-window <YYYY-MM-DD> |
Drill into a single Daily Window |
--start-hour <0-23> |
Daily Window start hour (default: 0) |
--user <identifier> |
Filter analysis to a single User |
--model-family <name> |
Filter analysis to a single Model Family (e.g. Auto) |
--timezone <iana-tz> |
Group Daily Windows and hours in a specific analysis time zone |
--metric <cost|tokens> |
Selected Metric for ranking and display (default: cost) |
--json |
Output aggregated stats as JSON (pipe to jq etc.) |
--include-no-charge |
Include "Errored, No Charge" events |
# Extract key numbers
npx @jnst/cursor-usage stats usage.csv --json | jq .summary.totalCost
# Drill into a Daily Window
npx @jnst/cursor-usage stats usage.csv --daily-window 2026-06-02 --timezone Asia/Tokyo
# Filter to a single user
npx @jnst/cursor-usage stats usage.csv --user jnst@example.jp
# See the Models inside one Model Family (e.g. what Auto routed to)
npx @jnst/cursor-usage stats usage.csv --model-family Auto --by model
# Rank and display by Tokens instead of Spend
npx @jnst/cursor-usage stats usage.csv --metric tokensOr install globally to use the short cursor-usage command:
npm install -g @jnst/cursor-usage # or: bun add -g @jnst/cursor-usage
cursor-usage stats usage.csvThe four User Top 10 panels use horizontal bars in a two-column, two-row layout,
with independent high-to-low and low-to-high controls.
Spend and Tokens default to highest first; Effective Rate defaults to lowest
first. CLI User rankings accept --user-order asc|desc, for example
stats usage.csv --by user-effective-rate --user-order desc or
stats usage.csv --by user --metric tokens --user-order asc.
npx @jnst/cursor-usage stats usage.csv --by user-effective-rateShows the ten Users with the lowest aggregate reported Spend per million tokens
($ / MTok), alongside Spend and Tokens. No Charge Events and Users with
zero tokens or zero total reported Spend are excluded; there is no minimum usage threshold. Model and cache
mix affect this diagnostic, so it is not a productivity score. Overview and
Daily Window JSON expose the same ranking as topUsersByEffectiveRate.
The dashboard always shows Spend and Tokens together. Terminal
stats --metric cost|tokens still selects ranking order; legacy screenshot
--metric options and dashboard metric URL values are accepted but no longer
switch the displayed Metric.
Cloud Agent Usage Rate ranks the percentage of each User's billable event rows
with a nonempty Cloud Agent ID. Repeated IDs count for each event, No Charge
events are excluded from both counts, and 0% Users remain eligible. The default
is highest first. Use stats usage.csv --by user-cloud-agent (optionally with
--user-order asc) for terminal output. JSON includes topUsersByCloudAgentUsage
with the rate as a percentage and both event counts.
Both screenshot and daily-report accept --lang ja|en:
npx @jnst/cursor-usage screenshot usage.csv --lang en
npx @jnst/cursor-usage daily-report usage.csv --lang jaWithout --lang, the output language follows LC_ALL, LC_MESSAGES, then LANG (the first nonempty value), or the runtime locale when none is set; unsupported languages fall back to English. PNGs use the selected language and omit the language control. CLI help and terminal statistics remain in English.
The dashboard's Hide Spend / 金額を隠す button masks totals, individual costs, axes, and
tooltip costs. Averages and Effective Rate stay visible. This is display masking,
not data redaction; those values can sometimes be used to reconstruct totals.
Use screenshot usage.csv --hide-costs or daily-report usage.csv --hide-costs
to export a masked image. The interactive setting lasts for the current page.
npx @jnst/cursor-usage screenshot team-usage-events.csvCaptures the dashboard as a PNG next to the CSV. The default screenshot is an Overview. Spend and Tokens charts are stacked vertically at full width, with User Spend, Tokens, Effective Rate, and Cloud Agent Usage Rate Top 10 rankings in the same image (1400px wide). Model Family breakdowns and event details are always visible. Readability takes priority over fitting a fixed page height:
team-usage-events.csv -> team-usage-events.png
Use --daily-window to capture the detail view for one Daily Window:
npx @jnst/cursor-usage screenshot team-usage-events.csv --daily-window 2026-06-14team-usage-events.csv --daily-window 2026-06-14 -> team-usage-events-2026-06-14-daily.png
Use --start-hour when a Daily Window should start after midnight, and
--event-limit to limit the event table in the screenshot:
npx @jnst/cursor-usage screenshot usage.csv --daily-window 2026-06-14 --start-hour 5 --event-limit 20For a shareable report of the latest work session in the CSV, use
daily-report. It captures the latest 5:00-start Daily Window with both Metrics
and all four User rankings, and writes daily-report.png in the current
directory. Model Family and Kind breakdowns are visible, along with the top 10
events by Spend. The image captures the full page:
npx @jnst/cursor-usage daily-report usage.csvScreenshots use a headless browser and require an installed Chrome/Chromium.
Set CHROME_PATH if Chrome is not available on the default channel. Screenshots
can also be filtered the same way as terminal stats:
npx @jnst/cursor-usage screenshot usage.csv --daily-window 2026-06-14 --user jnst@example.jp --timezone Asia/Tokyo
npx @jnst/cursor-usage screenshot usage.csv --out dashboard.pngDevelopment tooling uses Bun (runtime code itself is Node-compatible).
bun install
bun test # core logic tests
bun run dev # dev server with hot reload
bun run build # bundle CLI and dashboard into dist/
bun dist/cli.js stats usage.csv
# Generate a dummy CSV for screenshots
bun scripts/generate-dummy-csv.ts > dummy-usage.csvRun releases from main; other branches and detached HEAD are rejected before authentication or any release steps, including with --dry-run.
The release command verifies, versions, publishes, pushes commits/tags, and creates a GitHub Release with generated notes:
bun run releaseUse --dry-run to print mutating steps without running them:
bun run release --dry-runThe release command is safe to rerun after a partial failure. The script checks the current tag, npm package version, and GitHub Release before each publishing step:
# If npm publish, git push, or GitHub Release creation failed midway,
# fix the problem and run the same command again.
bun run releasesrc/core/— CSV parsing and aggregation (pure TS, shared between terminal and browser)src/cli/— CLI entry point and terminal renderingsrc/server/— static file server built onBun.serveweb/— React + Recharts dashboard (bundled at build time)
MIT
The dashboard groups Cloud Agent IDs above the event table in a section that starts open and can be collapsed. Four charts compare Spend, Tokens, Event Count, and unique IDs per User. Summary cards show mean, median, maximum Spend and Top 10 Spend share; detail rows include Users, model event counts and first/last observations.
Only Billable Events with a nonempty ID in the current period and filters are included. Observation timestamps do not measure runtime or task completion. Shared IDs count once per participating User. The cost visibility toggle masks individual and total costs while keeping mean and median visible.
Use cursor-usage stats usage.csv --by cloud-agent for terminal analysis. Overview and Daily Window JSON include the same numeric results in cloudAgentAnalysis.
Run bun run test:browser to build the dashboard and verify language selection, persistence, view preservation, and PNG exports in Chrome. This uses the same Chrome installation and CHROME_PATH / PLAYWRIGHT_CHROME_CHANNEL overrides as screenshot export.