@jnst/cursor-usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jun Sato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# cursor-usage
+
+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
+
+![Dashboard](docs/dashboard.png)
+
+Runs on Node.js 20+ (`npx`) or [Bun](https://bun.sh) (`bunx`).
+
+## Usage
+
+### Dashboard (default)
+
+```bash
+npx @jnst/cursor-usage   # or: bunx @jnst/cursor-usage
+```
+
+Starts 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.
+
+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.
+
+```bash
+npx @jnst/cursor-usage serve --port 8080 --no-open
+```
+
+### Terminal stats
+
+```bash
+npx @jnst/cursor-usage stats team-usage-events.csv
+```
+
+```
+Cursor Usage  2026-06-01 – 2026-06-10  (610 events, 10 days)
+
+  Total Cost    $1446.69      Total Tokens  1.1B
+  Avg/Day       $144.67       Max Mode      96%
+  Users         4             Models        8
+
+Daily Cost
+  2026-06-01  $147.44  ████████████████▊            10% 102.9M tok, 68 ev
+  2026-06-02  $246.57  ████████████████████████████ 17% 180.0M tok, 79 ev
+  ...
+
+By Model
+  gpt-5.5-medium                 $954.95  ████████████████████████████ 66% 804.2M tok, 472 ev
+  claude-opus-4-8-thinking-high  $357.92  ██████████▌                  25% 135.5M tok, 69 ev
+  ...
+```
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `--by <day\|user\|model>` | Show a single breakdown axis |
+| `--json` | Output aggregated stats as JSON (pipe to jq etc.) |
+| `--include-no-charge` | Include "Errored, No Charge" events |
+
+```bash
+# Extract key numbers
+npx @jnst/cursor-usage stats usage.csv --json | jq .summary.totalCost
+```
+
+Or install globally to use the short `cursor-usage` command:
+
+```bash
+npm install -g @jnst/cursor-usage   # or: bun add -g @jnst/cursor-usage
+cursor-usage stats usage.csv
+```
+
+## Development
+
+Development tooling uses [Bun](https://bun.sh) (runtime code itself is Node-compatible).
+
+```bash
+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.csv
+```
+
+## Architecture
+
+- `src/core/` — CSV parsing and aggregation (pure TS, shared between terminal and browser)
+- `src/cli/` — CLI entry point and terminal rendering
+- `src/server/` — static file server built on `Bun.serve`
+- `web/` — React + Recharts dashboard (bundled at build time)
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import{readFile as pn}from"node:fs/promises";import{parseArgs as E}from"node:util";var Q="Errored, No Charge";function F(n){return n.toISOString().slice(0,10)}function M(n){return n.filter((g)=>g.kind!==Q)}function Z(n){let g=0,p=0,o=0,f=new Set,c=new Set,S=new Set;for(let $ of n){if(g+=$.cost,p+=$.totalTokens,$.maxMode)o++;f.add(F($.date)),c.add($.user),S.add($.model)}let I=[...f].sort();return{totalCost:g,totalTokens:p,eventCount:n.length,firstDay:I[0]??null,lastDay:I[I.length-1]??null,dayCount:f.size,avgCostPerDay:f.size>0?g/f.size:0,maxModeRatio:n.length>0?o/n.length:0,userCount:c.size,modelCount:S.size}}function j(n,g){let p=new Map;for(let o of n){let f=g(o),c=p.get(f);if(!c)c={key:f,cost:0,totalTokens:0,inputTokens:0,outputTokens:0,cacheRead:0,eventCount:0},p.set(f,c);c.cost+=o.cost,c.totalTokens+=o.totalTokens,c.inputTokens+=o.inputWithCacheWrite+o.inputWithoutCacheWrite,c.outputTokens+=o.outputTokens,c.cacheRead+=o.cacheRead,c.eventCount++}return[...p.values()]}function N(n){return j(n,(g)=>F(g.date)).sort((g,p)=>g.key.localeCompare(p.key))}function X(n){return j(n,(g)=>g.user).sort((g,p)=>p.cost-g.cost)}function Y(n){return j(n,(g)=>g.model).sort((g,p)=>p.cost-g.cost)}function R(n){let g=[],p=[],o="",f=!1,c=0,S=()=>{p.push(o),o=""},I=()=>{S(),g.push(p),p=[]};while(c<n.length){let $=n[c];if(f){if($==='"'){if(n[c+1]==='"'){o+='"',c+=2;continue}f=!1,c++;continue}o+=$,c++;continue}if($==='"'){f=!0,c++;continue}if($===","){S(),c++;continue}if($==="\r"){c++;continue}if($===`
+`){I(),c++;continue}o+=$,c++}if(o.length>0||p.length>0)I();return g}var i=["Date","User","Cloud Agent ID","Automation ID","Kind","Model","Max Mode","Input (w/ Cache Write)","Input (w/o Cache Write)","Cache Read","Output Tokens","Total Tokens","Cost"];function J(n){if(!n)return 0;let g=Number(n);return Number.isFinite(g)?g:0}function L(n){let g=R(n.trim());if(g.length===0)return[];let p=g[0],o=new Map;p.forEach((S,I)=>o.set(S.trim(),I));for(let S of["Date","User","Model","Cost"])if(!o.has(S))throw Error(`Invalid CSV: missing column "${S}". Expected a Cursor usage-events export with columns: ${i.join(", ")}`);let f=(S,I)=>{let $=o.get(I);return $===void 0?"":(S[$]??"").trim()},c=[];for(let S of g.slice(1)){if(S.length===1&&S[0]==="")continue;let I=f(S,"Date"),$=new Date(I);if(Number.isNaN($.getTime()))continue;c.push({date:$,user:f(S,"User"),cloudAgentId:f(S,"Cloud Agent ID")||null,automationId:f(S,"Automation ID")||null,kind:f(S,"Kind"),model:f(S,"Model"),maxMode:f(S,"Max Mode").toLowerCase()==="yes",inputWithCacheWrite:J(f(S,"Input (w/ Cache Write)")),inputWithoutCacheWrite:J(f(S,"Input (w/o Cache Write)")),cacheRead:J(f(S,"Cache Read")),outputTokens:J(f(S,"Output Tokens")),totalTokens:J(f(S,"Total Tokens")),cost:J(f(S,"Cost"))})}return c}import{spawn as k}from"node:child_process";import{createReadStream as x,existsSync as h}from"node:fs";import{stat as l}from"node:fs/promises";import{createServer as r}from"node:http";import{dirname as b,extname as w,join as K,normalize as d}from"node:path";import{fileURLToPath as y}from"node:url";var _=4321,m={".html":"text/html; charset=utf-8",".js":"text/javascript; charset=utf-8",".css":"text/css; charset=utf-8",".svg":"image/svg+xml",".png":"image/png",".ico":"image/x-icon",".map":"application/json"};function v(){let n=b(y(import.meta.url)),g=[K(n,"web"),K(n,"../../dist/web")];for(let p of g)if(h(K(p,"index.html")))return p;throw Error("Dashboard assets not found. Run `bun run build` first (expected dist/web/index.html).")}function a(n){let[g,...p]=process.platform==="darwin"?["open",n]:process.platform==="win32"?["cmd","/c","start","",n]:["xdg-open",n];try{k(g,p,{stdio:"ignore",detached:!0}).unref()}catch{}}function T(n){let g=v(),p=r(async(f,c)=>{let S=decodeURIComponent(new URL(f.url??"/","http://localhost").pathname),I=d(K(g,S==="/"?"/index.html":S));if(!I.startsWith(g)){c.writeHead(403),c.end("Forbidden");return}try{let $=await l(I);if(!$.isFile())throw Error("not a file");c.writeHead(200,{"Content-Type":m[w(I)]??"application/octet-stream","Content-Length":$.size}),x(I).pipe(c)}catch{c.writeHead(404),c.end("Not Found")}}),o=()=>{let{port:f}=p.address(),c=`http://localhost:${f}`;if(console.log(`cursor-usage dashboard running at ${c}`),console.log("Drop a Cursor usage-events CSV onto the page. Ctrl+C to stop."),n.open)a(c)};if(n.port!==void 0){p.listen(n.port,o);return}p.once("error",(f)=>{if(f.code!=="EADDRINUSE")throw f;console.log(`port ${_} is in use, picked a free port instead`),p.listen(0)}),p.once("listening",o),p.listen(_)}var s=process.stdout.isTTY&&!process.env.NO_COLOR,G=(n)=>(g)=>s?`\x1B[${n}m${g}\x1B[0m`:g,z=G("1"),V=G("2"),e=G("36"),Zn=G("32"),jn=G("33");function P(n){return`$${n.toFixed(2)}`}function t(n){if(n>=1e9)return`${(n/1e9).toFixed(1)}B`;if(n>=1e6)return`${(n/1e6).toFixed(1)}M`;if(n>=1000)return`${(n/1000).toFixed(1)}K`;return String(n)}function nn(n,g,p){if(g<=0||n<=0)return"";let o=Math.round(n/g*p*8),f=Math.floor(o/8),c=o%8,S=["","▏","▎","▍","▌","▋","▊","▉"];return"█".repeat(f)+(S[c]??"")}function C(n,g){return n.length>=g?n:n+" ".repeat(g-n.length)}function gn(n){let g=n.firstDay&&n.lastDay?`${n.firstDay} – ${n.lastDay}`:"no data",p=(f)=>V(C(f,14)),o=(f)=>z(C(f,12));return[`${z("Cursor Usage")}  ${g}  ${V(`(${n.eventCount} events, ${n.dayCount} days)`)}`,"",`  ${p("Total Cost")}${o(P(n.totalCost))}  ${p("Total Tokens")}${o(t(n.totalTokens))}`,`  ${p("Avg/Day")}${o(P(n.avgCostPerDay))}  ${p("Max Mode")}${o(`${Math.round(n.maxModeRatio*100)}%`)}`,`  ${p("Users")}${o(String(n.userCount))}  ${p("Models")}${o(String(n.modelCount))}`]}function q(n,g,p={totalCost:0}){let{totalCost:o,barWidth:f=28,maxRows:c=15}=p,S=g.slice(0,c),I=Math.max(...S.map((A)=>A.key.length),4),$=Math.max(...S.map((A)=>A.cost),0),W=[z(n)];for(let A of S){let u=o>0?` ${V(`${Math.round(A.cost/o*100)}%`)}`:"";W.push(`  ${C(A.key,I)}  ${C(P(A.cost),8)} ${e(C(nn(A.cost,$,f),f))}${u} ${V(`${t(A.totalTokens)} tok, ${A.eventCount} ev`)}`)}if(g.length>c)W.push(V(`  … and ${g.length-c} more`));return W}function B(n,g){let p=Z(n),o=[gn(p)],f={day:()=>q("Daily Cost",N(n),{totalCost:p.totalCost,maxRows:31}),model:()=>q("By Model",Y(n),{totalCost:p.totalCost}),user:()=>q("By User",X(n),{totalCost:p.totalCost})};if(g)o.push(f[g]());else o.push(f.day(),f.model(),f.user());return o.map((c)=>c.join(`
+`)).join(`
+
+`)+`
+`}function D(n){return JSON.stringify({summary:Z(n),byDay:N(n),byModel:Y(n),byUser:X(n)},null,2)}var O=`cursor-usage — visualize Cursor usage-events CSV
+
+Usage:
+  cursor-usage [serve] [--port <n>] [--no-open]   Start the drag & drop dashboard (default)
+  cursor-usage stats <csv> [options]              Show usage statistics in the terminal
+
+Stats options:
+  --by <day|user|model>   Show a single breakdown axis (default: all)
+  --json                  Output aggregated stats as JSON
+  --include-no-charge     Include "Errored, No Charge" events
+
+Serve options:
+  --port <n>              Fixed port to listen on
+                          (default: 4321, falls back to a free port if busy)
+  --no-open               Do not open the browser automatically
+
+  -h, --help              Show this help
+`;function H(n){console.error(`Error: ${n}
+`),console.error(O),process.exit(1)}async function fn(n){let{values:g,positionals:p}=E({args:n,allowPositionals:!0,options:{by:{type:"string"},json:{type:"boolean",default:!1},"include-no-charge":{type:"boolean",default:!1}}}),o=p[0];if(!o)H("stats requires a path to a CSV file");let f;try{f=await pn(o,"utf8")}catch{H(`file not found: ${o}`)}let c=g.by;if(c&&!["day","user","model"].includes(c))H(`invalid --by value: ${c} (expected day, user or model)`);let S=L(f);if(!g["include-no-charge"])S=M(S);if(S.length===0)console.error("No usage events found in the CSV."),process.exit(1);console.log(g.json?D(S):B(S,c))}function U(n){let{values:g}=E({args:n,allowPositionals:!1,options:{port:{type:"string"},"no-open":{type:"boolean",default:!1}}}),p;if(g.port!==void 0){if(p=Number(g.port),!Number.isInteger(p)||p<0||p>65535)H(`invalid --port value: ${g.port}`)}T({port:p,open:!g["no-open"]})}async function cn(){let n=process.argv.slice(2);if(n.includes("-h")||n.includes("--help")){console.log(O);return}let[g,...p]=n;switch(g){case"stats":await fn(p);break;case"serve":U(p);break;case void 0:U([]);break;default:H(`unknown command: ${g}`)}}await cn();