claude-usage-explorer 1.0.0 → 1.1.5

package/package.json

@@ -1,29 +1,18 @@
-{
-  "name": "claude-usage-explorer",
-  "version": "1.0.0",
-  "description": "Local, read-only Claude Code usage analytics CLI and plugin",
-  "type": "module",
-  "bin": {
-    "claude-usage": "./bin/claude-usage.mjs"
-  },
-  "scripts": {
-    "test": "node --test",
-    "start": "node ./bin/claude-usage.mjs",
-    "check": "node --check ./src/core.mjs && node --check ./src/statusline.mjs && node --check ./bin/claude-usage.mjs && node --check ./src/tui.mjs && node --check ./src/launcher.mjs && node --check ./src/snapshot.mjs && node --check ./hooks/usage-explorer.mjs && node --check ./src/plan-usage.mjs",
-    "prepack": "npm run check && npm test"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "MIT",
-  "files": [
-    "bin/",
-    "src/",
-    "hooks/",
-    "commands/",
-    ".claude-plugin/",
-    "scripts/",
-    "README.md",
-    "LICENSE"
-  ]
-}
+{
+  "name": "claude-usage-explorer",
+  "version": "1.1.5",
+  "description": "Local, read-only Claude Code usage analytics CLI and plugin",
+  "type": "module",
+  "bin": {
+    "claude-usage": "./bin/claude-usage.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node ./bin/claude-usage.mjs",
+    "check": "node --check ./src/core.mjs && node --check ./src/statusline.mjs && node --check ./bin/claude-usage.mjs && node --check ./src/tui.mjs && node --check ./src/launcher.mjs && node --check ./src/snapshot.mjs && node --check ./hooks/usage-explorer.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/src/core.mjs

@@ -85,11 +85,15 @@ export function costFor(model,m,rates=DEFAULT_RATES) {
   return (m.input*rate[0]+m.output*rate[1]+writeCost+m.cacheRead*rate[3])/1e6;
 }
 export function parseFile(file, rates=DEFAULT_RATES) {
-  const id=sessionIdentity(file);const requests=new Map();let title=null,cwd=null,start=null,end=null,sessionId=null;
+  const id=sessionIdentity(file);const requests=new Map();let title=null,cwd=null,start=null,end=null,sessionId=null,agentName=null;
   const bad=readLines(file,r=>{
     if(!r || typeof r!=='object') return;
     if(typeof r.cwd==='string') cwd=r.cwd;
     if(typeof r.sessionId==='string') sessionId=r.sessionId;
+    if(id.isSubagent && !agentName){
+      const candidate=r.agentType||r.agentName||r.agent_type||r.agent_name;
+      if(typeof candidate==='string' && /^[a-zA-Z][a-zA-Z0-9_-]{0,60}$/.test(candidate))agentName=candidate;
+    }
     const ts=Date.parse(r.timestamp);
     if(Number.isFinite(ts)) {start=Math.min(start??ts,ts);end=Math.max(end??ts,ts);}
     if(!title && r.type==='user') {
@@ -112,7 +116,7 @@ export function parseFile(file, rates=DEFAULT_RATES) {
       if(Number.isFinite(ts)) prev.timestamp=Math.min(prev.timestamp??ts,ts);
     } else requests.set(key,{...m,model,timestamp:Number.isFinite(ts)?ts:null});
   });
-  return {file,sessionId:sessionId||id.id,agent:id.agent,isSubagent:id.isSubagent,title,cwd,start,end,bad,requests:[...requests.values()]};
+  return {file,sessionId:sessionId||id.id,agent:id.agent,agentName,isSubagent:id.isSubagent,title,cwd,start,end,bad,requests:[...requests.values()]};
 }
 
 // Cache derived metadata and token counters only. Never persist transcript text beyond
@@ -151,8 +155,8 @@ export function ingest(roots,rates=DEFAULT_RATES) {
     if(parsed.start!==null) s.start=Math.min(s.start??parsed.start,parsed.start);
     if(parsed.end!==null) s.end=Math.max(s.end??parsed.end,parsed.end);
     let agent=s.agents.get(parsed.agent);
-    if(!agent) {agent={id:parsed.agent,requests:[]};s.agents.set(parsed.agent,agent);}
-    agent.requests.push(...parsed.requests);
+    if(!agent) {agent={id:parsed.agent,name:parsed.agentName||null,requests:[]};s.agents.set(parsed.agent,agent);}
+    agent.name=agent.name||parsed.agentName||null;agent.requests.push(...parsed.requests);
   }
   return {sessions:[...sessions.values()],files:files.length,malformed,roots};
 }
@@ -208,7 +212,7 @@ export function summarize(data,window=[-Infinity,Infinity],rates=DEFAULT_RATES)
         if(!byModel.has(r.model))byModel.set(r.model,ZERO());add(byModel.get(r.model),one);
         if(!models.has(r.model))models.set(r.model,ZERO());add(models.get(r.model),one);
       }
-      if(am.requests){add(stat,am);agents.push({id:a.id,stats:am,models:[...byModel].map(([name,stats])=>({name,stats}))});}
+      if(am.requests){add(stat,am);agents.push({id:a.id,name:a.name||null,stats:am,models:[...byModel].map(([name,stats])=>({name,stats}))});}
     }
     if(!stat.requests)continue;
     const project=s.cwd||'(unknown project)';

package/src/snapshot.mjs

@@ -3,7 +3,6 @@ import os from 'node:os';
 import path from 'node:path';
 import {DEFAULT_RATES,ingest,projectRoots,summarize,timeWindow} from './core.mjs';
 import {describePeriod} from './tui.mjs';
-import {readPlanUsage} from './plan-usage.mjs';
 
 export function snapshot(argv=[], {now=Date.now(),home=os.homedir(),roots=projectRoots()}={}) {
   const periodIndex=argv.indexOf('--period');
@@ -14,5 +13,5 @@ export function snapshot(argv=[], {now=Date.now(),home=os.homedir(),roots=projec
   const rates={...DEFAULT_RATES,...settings.rates};
   const window=timeWindow(period,now,settings.billingDay,settings.billingTimeZone||'UTC',settings.billingHour||0,settings.billingMinute||0);
   const report=summarize(ingest(roots,rates),window,rates);
-  return {period,periodLabel:describePeriod(period,settings,now),settings:{billingDay:settings.billingDay||null,billingTimeZone:settings.billingTimeZone||'UTC'},updatedAt:now,report,planUsage:readPlanUsage({now})};
+  return {savedPeriod:settings.lastPeriod||'all',period,periodLabel:describePeriod(period,settings,now),settings:{billingDay:settings.billingDay||null,billingTimeZone:settings.billingTimeZone||'UTC'},updatedAt:now,report};
 }

package/src/tui.mjs

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
+import {spawnSync} from 'node:child_process';
 import {ingest,projectRoots,summarize,timeWindow,totalTokens,number,DEFAULT_RATES} from './core.mjs';
-import {readPlanUsage} from './plan-usage.mjs';
 
 const periods=[['Current billing cycle','cycle'],['Previous billing cycle','previous-cycle'],['All time','all'],['Today','today'],['Yesterday','yesterday'],['Last 7 days','7d'],['Last 30 days','30d'],['This month','month'],['Previous month','previous-month'],['Custom dates','custom']];
 export function describePeriod(period, settings={}, now=Date.now()){
@@ -25,10 +25,8 @@ function saveSettings(s){fs.mkdirSync(path.dirname(settingFile()),{recursive:tru
 const sortColumns=[['cost','Est. USD'],['tokens','Tokens'],['requests','Requests'],['input','Input'],['output','Output'],['cacheWrite','Cache write'],['cacheRead','Cache read'],['name','Name']];
 const value=(r,key)=>key==='tokens'?totalTokens(r.stats):key==='cost'?r.stats.unknownCostRequests?null:r.stats.knownCost:key==='name'?r.label.toLowerCase():r.stats[key];
 const empty={requests:0,input:0,output:0,cacheWrite:0,cacheRead:0,knownCost:0,unknownCostRequests:0};
-export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),period='all',planReader=readPlanUsage}={}){
+export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),period=settings.lastPeriod||'all'}={}){
  let liveState={enabled:true,lastUpdated:Date.now(),lastCheck:Date.now(),error:null};
- let planUsage=null,planCheckedAt=0;
- function refreshPlan(now=Date.now()){if(now-planCheckedAt<4000)return;planCheckedAt=now;try{planUsage=planReader({now})||null;}catch{planUsage=null;}}
  let sourceData=data,view='projects',selection=0,offset=0,stack=[],sort='tokens',descending=true,filter='',message='',currentPeriod=period,project=null,session=null,agent=null,report=null;
  const rates=()=>({...DEFAULT_RATES,...settings.rates});
  function refresh(){try{report=summarize(sourceData,timeWindow(currentPeriod,Date.now(),settings.billingDay,settings.billingTimeZone||'UTC',settings.billingHour||0,settings.billingMinute||0),rates());message=report.overall.unknownCostRequests?`${fmt(report.overall.unknownCostRequests)} requests have unknown model prices. Configure rates in Settings (B).`:'';}catch(e){message=e.message;currentPeriod='all';report=summarize(sourceData,undefined,rates());}}
@@ -36,7 +34,7 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
  function rows(){let list=[];
   if(view==='projects')list=report.projects.map(x=>({...x,label:path.basename(x.name)||x.name}));
   if(view==='sessions')list=report.sessions.filter(x=>!project||x.project===project.name).map(x=>({...x,label:x.title}));
-  if(view==='agents')list=(session?.agents||[]).map(x=>({...x,label:x.id==='main'?'Main agent':`Subagent ${x.id}`}));
+  if(view==='agents')list=(session?.agents||[]).map(x=>({...x,label:x.id==='main'?'Agent (main)':(x.name||x.type||'Subagent')}));
   if(view==='models')list=(agent?.models||session?.models||project?.models||report.models).map(x=>({...x,label:x.name}));
   if(view==='periods')list=periods.map(([,v])=>({label:describePeriod(v,settings),value:v,stats:empty}));
   if(view==='settings')list=[{label:`Billing: day ${settings.billingDay||'not set'} at ${String(settings.billingHour||0).padStart(2,'0')}:${String(settings.billingMinute||0).padStart(2,'0')} ${settings.billingTimeZone||'UTC'}`,value:'billing',stats:empty},{label:`Custom model prices: ${Object.keys(settings.rates||{}).length} configured`,value:'rates',stats:empty},{label:'Rescan history (R)',value:'rescan',stats:empty}];
@@ -52,7 +50,7 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   if(view==='projects'){project=x;nav('sessions');}
   else if(view==='sessions'){session=x;nav('agents');}
   else if(view==='agents'){agent=x;nav('models');}
-  else if(view==='periods'){if(x.value==='custom')return 'custom';if(['cycle','previous-cycle'].includes(x.value)&&!(Number.isInteger(settings.billingDay)&&settings.billingDay>=1&&settings.billingDay<=31))return `billing-required:${x.value}`;currentPeriod=x.value;refresh();restore();}
+  else if(view==='periods'){if(x.value==='custom')return 'custom';if(['cycle','previous-cycle'].includes(x.value)&&!(Number.isInteger(settings.billingDay)&&settings.billingDay>=1&&settings.billingDay<=31))return `billing-required:${x.value}`;currentPeriod=x.value;settings.lastPeriod=currentPeriod;saveSettings(settings);refresh();restore();}
   else if(view==='settings')return x.value;
   else if(view==='sort'){setSort(x.value);restore();}
   else if(view==='models')message=`${x.name} · ${fmt(totalTokens(x.stats))} tokens · ${money(x.stats)} estimated USD`;
@@ -75,13 +73,12 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
  }
  function setLiveState(update){liveState={...liveState,...update};}
  function toggleLive(){liveState.enabled=!liveState.enabled;liveState.lastCheck=Date.now();}
- function setPeriod(p){currentPeriod=p;refresh();switchView('projects');}
+ function setPeriod(p){currentPeriod=p;settings.lastPeriod=p;saveSettings(settings);refresh();switchView('projects');}
  function setBillingDay(n,timeZone='UTC',hour=0,minute=0){settings.billingDay=n;settings.billingTimeZone=timeZone;settings.billingHour=hour;settings.billingMinute=minute;saveSettings(settings);refresh();message=`Billing saved: day ${n}, ${String(hour).padStart(2,'0')}:${String(minute).padStart(2,'0')} ${timeZone}.`;}
  function setModelRate(model,values){settings.rates??={};settings.rates[model]=values;saveSettings(settings);refresh();message=`Saved custom USD/million-token rates for ${model}.`;}
  function setFilter(s){filter=s;selection=0;offset=0;}
  function setSort(key){if(sort===key)descending=!descending;else{sort=key;descending=key!=='name';}selection=0;offset=0;}
  function render(width=process.stdout.columns||110,height=process.stdout.rows||30){
-  refreshPlan();
   width=Math.max(20,width);height=Math.max(8,height);
   const tty=process.stdout.isTTY && !process.env.NO_COLOR;
   const c=(text,style)=>tty?`\x1b[${style}m${text}\x1b[0m`:text;
@@ -94,9 +91,8 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   rule();
   const crumb=['Projects',project&&path.basename(project.name),session&&truncate(session.title,32),agent&&agent.label].filter(Boolean).join('  ›  ');
   line(`  ${c(crumb,'1')}     ${c('PERIOD','90')} ${describePeriod(currentPeriod,settings)}     ${c('SORT','90')} ${sort} ${descending?'↓':'↑'}`);
-  line(`  ${c('TOTAL','90')} ${fmt(totalTokens(report.overall))} tokens     ${fmt(report.overall.requests)} requests     ${c(money(report.overall),'1;32')} API-equivalent`);
-  const planLabel=planUsage?`5h ${planUsage.fiveHour??'—'}%  ·  7d ${planUsage.sevenDay??'—'}%  ·  ${Date.now()-planUsage.timestamp>15*60000?'Cached, may be outdated':'Cached, recent'}  ·  ${new Date(planUsage.timestamp).toLocaleString()}`:'Claude Desktop plan usage unavailable';
-  line(`  ${c('PLAN LIMITS','1;36')}  ${c(planLabel,'90')}`);
+  const scoped=view==='sessions'?project?.stats:view==='agents'?session?.stats:view==='models'?(agent?.stats||session?.stats||project?.stats||report.overall):report.overall;
+  line(`  ${c('TOTAL','90')} ${fmt(totalTokens(scoped))} tokens     ${fmt(scoped.requests)} requests     ${c(money(scoped),'1;32')} API-equivalent`);
   rule();
   const available=rows();selection=Math.max(0,Math.min(selection,Math.max(0,available.length-1)));
   const selected=available[selection];
@@ -104,21 +100,24 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   // Fixed-height table, model panel, and footer prevent vertical jumping on selection.
   const modelPanelHeight=7; // heading + five model rows + divider
   const footerHeight=5; // separator, two shortcuts, search, status
-  const headerHeight=7;
+  const headerHeight=6;
   const visible=Math.max(0,height-headerHeight-modelPanelHeight-footerHeight-2);
   if(selection<offset)offset=selection;if(selection>=offset+visible)offset=selection-visible+1;
   // Keep columns aligned by terminal width, shrinking the name first.
   const columns=width>=135?[['REQ',7,'requests'],['INPUT',10,'input'],['OUTPUT',10,'output'],['C.WRITE',12,'cacheWrite'],['C.READ',13,'cacheRead'],['TOKENS',14,'tokens'],['USD',13,'cost']]:width>=105?[['REQ',7,'requests'],['OUTPUT',11,'output'],['C.WRITE',13,'cacheWrite'],['C.READ',14,'cacheRead'],['TOKENS',15,'tokens'],['USD',12,'cost']]:[['REQ',7,'requests'],['TOKENS',15,'tokens'],['USD',13,'cost']];
-  const labelWidth=Math.max(17,width-5-columns.reduce((sum,[,n])=>sum+n+1,0));
+  const rightMargin=4; // Always leave a few columns clear of the terminal's right edge.
+  const labelWidth=Math.max(17,width-5-rightMargin-7-columns.reduce((sum,[,n])=>sum+n+1,0));
   if(!['periods','settings','sort'].includes(view)){
-    line(c('  '+pad('NAME',labelWidth)+' '+columns.map(([name,n,key])=>pad(name+(sort===key?(descending?'↓':'↑'):''),n,'right')).join(' '),'1;36'));
+    line(c('  '+pad('NAME',labelWidth)+' '+pad('SHARE',6,'right')+' '+columns.map(([name,n,key])=>pad(name+(sort===key?(descending?'↓':'↑'):''),n,'right')).join(' '),'1;36'));
   }
   for(let i=offset;i<Math.min(available.length,offset+visible);i++){
     const x=available[i],active=i===selection;
     let text;
     if(['periods','settings','sort'].includes(view))text=`  ${active?'❯':' '} ${x.label}${view==='periods'&&x.value===currentPeriod?'   ✓':''}`;
     else {const s=x.stats;const vals={requests:fmt(s.requests),input:fmt(s.input),output:fmt(s.output),cacheWrite:fmt(s.cacheWrite),cacheRead:fmt(s.cacheRead),tokens:fmt(totalTokens(s)),cost:money(s)};
-      text=`  ${active?'❯':' '} ${pad(x.label,labelWidth)} `+columns.map(([,n,key])=>pad(vals[key],n,'right')).join(' ');
+      const parentTotal=view==='projects'?totalTokens(report.overall):view==='sessions'?totalTokens(project?.stats):view==='agents'?totalTokens(session?.stats):totalTokens(agent?.stats||report.overall);
+      const pct=parentTotal>0?(totalTokens(s)>0&&100*totalTokens(s)/parentTotal<0.05?'<0.1%':(100*totalTokens(s)/parentTotal).toFixed(1)+'%'):'—';
+      text=`  ${active?'❯':' '} ${pad(x.label,labelWidth)} ${pad(pct,6,'right')} `+columns.map(([,n,key])=>pad(vals[key],n,'right')).join(' ');
     }
     line(active?c(truncate(text,width),'7'):truncate(text,width));
   }
@@ -128,7 +127,7 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   for(let i=renderedRows;i<visible;i++)line('');
   line(c(`  ${available.length?`${offset+1}–${Math.min(available.length,offset+visible)} of ${available.length}`:'0 rows'}   •   PgUp/PgDn scroll`,'90'));
   rule();
-  line(c('  MODEL BREAKDOWN · SELECTED ROW','1;36')+c('    (M: full model table)','90'));
+  line(c('  MODELS IN SELECTED ROW','1;36')+c('    (M: full model table)','90'));
   const models=breakdown?[...breakdown].sort((a,b)=>totalTokens(b.stats)-totalTokens(a.stats)).slice(0,5):[];
   for(let i=0;i<5;i++){
     const m=models[i];
@@ -136,12 +135,12 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   }
   rule();
   line(c('  ↑↓ Navigate   ENTER Open   BACKSPACE Back   M Models   D Dates   O Sort   / Search','1'));
-  line(c('  B Billing/settings   S Reverse sort   C Current project   R Refresh   L Live   ? Help   Q Quit','90'));
+  line(c('  B Settings   S Reverse sort   C Current project   E Open session   ? Help   Q Quit','90'));
   line(c('  '+(filter?'Search: '+truncate(filter,width-12):' '),'36'));
   line(c(`  ${liveState.enabled?'● LIVE':'Ⅱ PAUSED'} · Updated ${Math.max(0,Math.floor((Date.now()-liveState.lastUpdated)/1000))}s ago${liveState.error?' · '+liveState.error:''}`,'36')+(message?'  '+c(truncate(message,Math.max(10,width-65)),'33'):''));
   return out.slice(0,Math.max(1,height-1)).join('\n');
  }
- return {render,refreshPlan,get planUsage(){return planUsage;},rows,open,restore,switchView,nav,refresh,rescan,setLiveState,toggleLive,get liveState(){return liveState;},setPeriod,setBillingDay,setModelRate,setFilter,setSort,get view(){return view;},get currentPeriod(){return currentPeriod;},get settings(){return settings;},get cwd(){return cwd;},get selection(){return selection;},set selection(v){selection=v;},get sort(){return sort;},set sort(v){setSort(v);},get project(){return project;},set project(v){project=v;},get report(){return report;},get message(){return message;},set message(v){message=v;}};
+ return {render,rows,open,restore,switchView,nav,refresh,rescan,setLiveState,toggleLive,get liveState(){return liveState;},setPeriod,setBillingDay,setModelRate,setFilter,setSort,get view(){return view;},get currentPeriod(){return currentPeriod;},get settings(){return settings;},get cwd(){return cwd;},get selection(){return selection;},set selection(v){selection=v;},get sort(){return sort;},set sort(v){setSort(v);},get project(){return project;},set project(v){project=v;},get session(){return session;},get report(){return report;},get message(){return message;},set message(v){message=v;}};
 }
 // Clip colored output to the terminal viewport to prevent line wrapping and scroll flashes.
 export function clipAnsi(value, maxWidth) {
@@ -185,8 +184,7 @@ export async function launchTui(argv=[]){
   checking=true;
   try{
    const next=historySignature(roots);
-   if(next!==lastSignature){explorer.rescan(roots,{automatic:true});lastSignature=next;}
-   explorer.refreshPlan();draw();
+   if(next!==lastSignature){explorer.rescan(roots,{automatic:true});lastSignature=next;draw();}
    explorer.setLiveState({lastCheck:Date.now()});
   }catch(e){explorer.setLiveState({error:e.message});draw();}
   finally{checking=false;}
@@ -229,11 +227,31 @@ export async function launchTui(argv=[]){
   else if(str==='b')explorer.nav('settings');
   else if(str==='o')explorer.nav('sort');
   else if(str==='s')explorer.setSort(explorer.sort);
+  else if(str==='C'){
+   const selected=explorer.view==='sessions'?explorer.rows()[explorer.selection]:explorer.session;
+   if(selected?.id&&process.platform==='darwin'){
+    const result=spawnSync('pbcopy',[],{input:selected.id,encoding:'utf8'});
+    explorer.message=result.status===0?'Session ID copied.':'Unable to copy session ID.';
+   }else explorer.message='Select a session on macOS to copy its ID.';
+  }
+  else if(str==='e'){
+   const selected=explorer.view==='sessions'?explorer.rows()[explorer.selection]:explorer.session;
+   const directory=selected?.project||explorer.project?.name;
+   if(!selected?.id||!directory||process.platform!=='darwin')explorer.message='External resume requires a selected session on macOS.';
+   else if(!fs.existsSync(directory))explorer.message='Original project directory is missing.';
+   else {
+    const quote=x=>"'"+String(x).replaceAll("'","'\\''")+"'";
+    const command=`cd ${quote(directory)} && claude --resume ${quote(selected.id)}`;
+    const script=`tell application "Terminal" to do script ${JSON.stringify(command)}`;
+    const result=spawnSync('osascript',['-e',script],{encoding:'utf8',timeout:10000});
+    explorer.message=result.status===0?'Opened in Terminal.app.':`Unable to open Terminal: ${(result.stderr||'').slice(0,80)}`;
+   }
+  }
   else if(str==='c'){explorer.switchView('projects');const i=explorer.rows().findIndex(x=>path.resolve(x.name).toLowerCase()===path.resolve(explorer.cwd).toLowerCase());if(i>=0){explorer.selection=i;explorer.open();}else explorer.message='No exact match for current directory.';}
   else if(str==='/')explorer.setFilter(await ask('Filter table (empty clears):'));
   else if(str==='r'){explorer.rescan(roots);lastSignature=historySignature(roots);}
   else if(str==='l')explorer.toggleLive();
-  else if(str==='?'){await ask('HELP\n↑↓ select rows; Enter drills down; Backspace goes back.\nM shows models at the current level.\nD selects date range; B configures billing and model prices.\nO chooses a sort column; S reverses direction.\n/ filters; C opens current project; R rescans; L toggles live updates; Q quits.\n\nPress Enter to return.');}
+  else if(str==='?'){await ask('HELP\n↑↓ select rows; Enter drills down; Backspace goes back.\nM shows models at the current level.\nD selects date range; B configures billing and model prices.\nO chooses a sort column; S reverses direction.\n/ filters; C copies session ID; E opens selected session externally; R rescans; L toggles live updates; Q quits.\n\nPress Enter to return.');}
   draw();
  }
  process.stdin.on('keypress',onKey);process.stdout.on('resize',resize);resize();

package/tests/core.test.mjs

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';import os from 'node:os';import path from 'node:path';
+import {parseFile,ingest,summarize,timeWindow,totalTokens,projectRoots} from '../src/core.mjs';
+const dir=fs.mkdtempSync(path.join(os.tmpdir(),'claude-usage-test-'));
+const root=path.join(dir,'projects','-sample');fs.mkdirSync(root,{recursive:true});
+const file=path.join(root,'session-123.jsonl');
+const write=(f,rows)=>{fs.mkdirSync(path.dirname(f),{recursive:true});fs.writeFileSync(f,rows.map(x=>JSON.stringify(x)).join('\n')+'\n');};
+const assistant=(id,output,ts='2026-10-12T12:00:00Z')=>({type:'assistant',timestamp:ts,cwd:'/sample',sessionId:'session-123',message:{id,model:'claude-sonnet-4-5-20250929',usage:{input_tokens:100,output_tokens:output,cache_creation_input_tokens:20,cache_read_input_tokens:500}}});
+write(file,[{type:'user',timestamp:'2026-10-12T11:59:00Z',cwd:'/sample',sessionId:'session-123',message:{content:'Implement the API'}},assistant('msg1',3),assistant('msg1',10),assistant('msg2',5)]);
+test('deduplicates repeated message IDs using max observed counters',()=>{const p=parseFile(file);assert.equal(p.requests.length,2);assert.equal(p.requests[0].output,10);assert.equal(p.title,'Implement the API');});
+test('aggregates model usage without counting streaming duplicates',()=>{const d=ingest([path.join(dir,'projects')]);const s=summarize(d);assert.equal(s.overall.requests,2);assert.equal(s.overall.output,15);assert.equal(totalTokens(s.overall),100*2+15+20*2+500*2);assert.equal(s.projects.length,1);});
+test('subagent file appears in same session',()=>{const child=path.join(root,'session-123','subagents','agent-abc.jsonl');write(child,[assistant('msg3',8)]);const d=ingest([path.join(dir,'projects')]);assert.equal(d.sessions.length,1);assert.equal(d.sessions[0].agents.size,2);const s=summarize(d);assert.equal(s.overall.requests,3);assert.equal(s.sessions[0].agents.length,2);});
+test('date filtering attributes usage by request timestamp',()=>{const d=ingest([path.join(dir,'projects')]);assert.equal(summarize(d,timeWindow('2026-10-13:2026-10-14')).overall.requests,0);assert.equal(summarize(d,timeWindow('2026-10-12:2026-10-12')).overall.requests,3);});
+test('billing period clamps month end',()=>{const now=Date.parse('2026-03-02T12:00:00Z');const [a,b]=timeWindow('cycle',now,31);assert.equal(new Date(a).toISOString(),'2026-02-28T00:00:00.000Z');assert.equal(new Date(b).toISOString(),'2026-03-31T00:00:00.000Z');});
+test('config dir discovery honors custom root',()=>{const roots=projectRoots({CLAUDE_CONFIG_DIR:'/tmp/custom'},'/home/test');assert.ok(roots.includes(path.resolve('/tmp/custom/projects')));});
+test('unknown pricing is reported instead of zero-cost certainty',()=>{const unknown=path.join(root,'unknown.jsonl');write(unknown,[{...assistant('unknown',2),sessionId:'unknown',message:{...assistant('unknown',2).message,model:'claude-future-unknown'}}]);const s=summarize(ingest([path.join(dir,'projects')]));assert.equal(s.overall.unknownCostRequests,1);});
+
+test('Sonnet 5.5 official base prices yield nonzero API equivalent cost', async()=>{
+ const {costFor}=await import('../src/core.mjs');
+ const price=costFor('claude-sonnet-5-5',{input:1000000,output:1000000,cacheWrite:1000000,cacheRead:1000000});
+ assert.equal(price,14.6);
+});
+test('billing timezone and local time determine cycle boundaries',async()=>{
+ const {timeWindow}=await import('../src/core.mjs');
+ const now=Date.parse('2026-11-05T10:00:00Z');
+ const [start,end]=timeWindow('cycle',now,5,'Europe/Athens',9,0);
+ assert.equal(new Date(start).toISOString(),'2026-11-05T07:00:00.000Z');
+ assert.equal(new Date(end).toISOString(),'2026-12-05T07:00:00.000Z');
+});

package/tests/launcher.test.mjs

@@ -0,0 +1,12 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {launchSidecar} from '../src/launcher.mjs';
+test('macOS sidecar launches separate Terminal with current project',()=>{
+ let invocation;
+ const spawnProcess=(program,args,opts)=>{invocation={program,args,opts};return {on(){},unref(){}};};
+ launchSidecar({platform:'darwin',cwd:'/tmp/my project',spawnProcess});
+ assert.equal(invocation.program,'osascript');
+ assert.match(invocation.args.join(' '),/Terminal/);
+ assert.match(invocation.args.join(' '),/my project/);
+ assert.equal(invocation.opts.detached,true);
+});

package/tests/mod.test.mjs

@@ -0,0 +1,177 @@
+import {readFileSync} from 'node:fs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {drill,back,itemsFor,modelScope,register} from '../hooks/usage-explorer.mjs';
+const stats={input:5,output:2,cacheWrite:0,cacheRead:10,knownCost:0.25,unknownCostRequests:0};
+const agent={id:'main',stats,models:[{name:'sonnet',stats}]};
+const session={id:'s1',title:'Build feature',project:'/repo',stats,agents:[agent],models:agent.models};
+const report={overall:stats,projects:[{name:'/repo',stats}],sessions:[session],models:agent.models,files:1};
+test('native mod drills projects, sessions, agents and models, and navigates back',()=>{
+ let state={view:'projects',stack:[],project:null,session:null,agent:null,report,sort:'tokens',query:''};
+ state=drill(state,itemsFor(state)[0]);assert.equal(state.view,'sessions');
+ state=drill(state,itemsFor(state)[0]);assert.equal(state.view,'agents');
+ state=drill(state,itemsFor(state)[0]);assert.equal(state.view,'models');
+ assert.equal(itemsFor(state)[0].label,'sonnet');
+ state=back(state);assert.equal(state.view,'agents');
+ state=back(state);assert.equal(state.view,'sessions');
+ state=back(state);assert.equal(state.view,'projects');
+});
+test('native mod registers a model-free immediate command',async()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const start=hooks.find(x=>x.event==='session.start');
+ let command;
+ await start.fn({command:{register:async c=>{command=c;}}},{},async()=>({}));
+ assert.equal(command.name,'usage-explorer');assert.equal(command.immediate,true);
+});
+test('native sidebar render includes clickable entries and period controls',async()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,matcher,fn}));
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ assert.equal(element.type,'Box');
+ assert.ok(element.children.some(x=>x?.type==='Box'));
+ const flat=node=>[node,...(Array.isArray(node?.children)?node.children:[]).flatMap(flat)];
+ const input=flat(element).find(x=>x?.type==='Input');
+ assert.equal(input?.key,'usage-filter','host requires a stable key on Input');
+ assert.equal(typeof input?.onSubmit,'function','Claude Code 2.1.311 requires onSubmit for Input');
+});
+
+test('native sidebar collapses period choices and puts actions after entries',()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ const flat=(node)=>[node,...(Array.isArray(node?.children)?node.children:[]).flatMap(flat)];
+ const all=flat(element);
+ assert.ok(all.some(x=>x.type==='Button'&&x.label==='◷ Period'));
+ assert.ok(!all.some(x=>x.type==='Button'&&x.key==='period-cycle'));
+ assert.ok(all.some(x=>x.type==='Input'&&x.key==='usage-filter'));
+ const last=element.children[element.children.length-1];
+ assert.ok(flat(last).some(x=>x.type==='Button'&&x.label==='↻ Refresh'));
+});
+
+
+test('model scope respects project, session and agent drilldown',()=>{
+ const other={name:'opus',stats:{...stats,input:30}};
+ const scoped={...report,models:[other],projects:[{name:'/repo',stats,models:[{name:'sonnet',stats}]}]};
+ const base={view:'projects',stack:[],project:null,session:null,agent:null,report:scoped,sort:'tokens',query:''};
+ assert.equal(modelScope(base)[0].name,'opus');
+ const projectState={...base,project:'/repo'};
+ assert.equal(modelScope(projectState)[0].name,'sonnet');
+ const sessionState={...projectState,session};
+ assert.equal(modelScope(sessionState)[0].name,'sonnet');
+ const agentState={...sessionState,agent};
+ assert.equal(modelScope(agentState)[0].name,'sonnet');
+});
+
+test('models screen has a prominent back control and footer close-models action',()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ const flat=node=>[node,...(Array.isArray(node?.children)?node.children:[]).flatMap(flat)];
+ assert.match(requireSource(),/MODEL USAGE/);
+ const modSource=requireSource();
+ assert.match(modSource,/Back to previous view/);
+ assert.match(modSource,/Close models/);
+});
+function requireSource(){return requireSource.text||(requireSource.text=readFileSync(new URL('../hooks/usage-explorer.mjs',import.meta.url),'utf8'));}
+
+
+test('native sidebar uses host close-on-Escape and offers explicit exit action',async()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const run=hooks.find(x=>x.event==='command.run').fn;
+ let opened;
+ const $={session:{surfaces:async()=>['desktop']},ui:{open:async p=>{opened=p},invalidate:async()=>{},close:async()=>{}},process:{run:async()=>({exitCode:1,stderr:'fixture'})},clock:{every:()=>({cancel(){}})}};
+ await run($,{presentation:{isFullscreen:true,columns:160}});
+ assert.equal(opened.closeOnEscape,true);
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ const flat=node=>[node,...(Array.isArray(node?.children)?node.children:[]).flatMap(flat)];
+ const exit=flat(element).find(x=>x.type==='Button'&&x.label==='× Exit');
+ assert.equal(exit.hotkey,'x');assert.equal(typeof exit.onPress,'function');
+});
+
+test('period choices stack vertically and footer is outside expanding content',()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ assert.equal(element.justifyContent,'space-between');
+ assert.equal(element.height,'100%');
+ assert.equal(element.children.length,2);
+ assert.equal(element.children[0].flexGrow,1);
+ assert.equal(element.children[1].flexShrink,0);
+ const source=readFileSync(new URL('../hooks/usage-explorer.mjs',import.meta.url),'utf8');
+ assert.match(source,/flexDirection:'column',gap:0,children:periodButtons/);
+});
+
+test('official usage bars clamp percentages and show enterprise extra usage',async()=>{
+ const {usageBar,officialLimitRows}=await import('../hooks/usage-explorer.mjs');
+ assert.match(usageBar(37.66,10),/37\.7%/);
+ assert.match(usageBar(130,10),/100\.0%/);
+ assert.match(usageBar(-1,10),/0\.0%/);
+ const rows=officialLimitRows({rateLimits:[],details:['extra_usage: utilization: 37.66 · is_enabled: true']});
+ assert.deepEqual(rows,[{label:'extra_usage',percent:37.66,resetsAt:''}]);
+});
+
+test('usage response diagnostic exposes field names and types only',async()=>{
+ const {usageSchema}=await import('../hooks/usage-explorer.mjs');
+ const fields=usageSchema({extra_usage:{utilization:37.66,resets_at:'secret-date'},billing:{cycle_start:'private',cap:200},some_id:'private-id'});
+ assert.ok(fields.includes('extra_usage.utilization: number'));
+ assert.ok(fields.includes('billing.cycle_start: string'));
+ assert.ok(!fields.join(' ').includes('private'));
+ assert.ok(!fields.join(' ').includes('37.66'));
+});
+
+
+test('native mod uses only supported single-letter or digit hotkeys',()=>{
+ const hooks=[];register((event,matcher,fn)=>hooks.push({event,fn:fn||matcher}));
+ const render=hooks.find(x=>x.event==='ui.render').fn;
+ const ui={resolve:()=>Object.fromEntries(['Box','Text','Button','Input'].map(k=>[k,p=>({type:k,...p})]))};
+ const element=render({ui},{surface:'terminal'},()=>null);
+ const flat=node=>[node,...(Array.isArray(node?.children)?node.children:[]).flatMap(flat)];
+ const buttons=flat(element).filter(x=>x.type==='Button');
+ for(const b of buttons){if(b.hotkey!==undefined)assert.match(b.hotkey,/^[a-z0-9]$/,`invalid hotkey on ${b.label}`);}
+ assert.equal(buttons.some(b=>b.label==='Help'),false);
+});
+
+
+test('native sidebar removes diagnostic and provides session open actions',async()=>{
+ const {sessionResumeCommand}=await import('../hooks/usage-explorer.mjs');
+ const command=sessionResumeCommand({id:'bf9de351-f0e6-48cc-a941-21e3705fe379',project:'/Users/example/my repo'});
+ assert.match(command,/claude --resume/);
+ assert.match(command,/my repo/);
+ assert.throws(()=>sessionResumeCommand({id:'bad',project:'/repo'}));
+ const source=readFileSync(new URL('../hooks/usage-explorer.mjs',import.meta.url),'utf8');
+ assert.doesNotMatch(source,/Show response fields|Hide response fields|USAGE RESPONSE FIELD TYPES/);
+ assert.doesNotMatch(source,/session-open-terminal|session-copy-id/);
+ assert.match(source,/action\('Open session','o'/);
+ assert.match(source,/action\('Copy ID','c'/);
+});
+
+import { readFileSync as readModSource } from "node:fs";
+import { fileURLToPath as modFilePath } from "node:url";
+import { dirname as modDirname, join as modJoin } from "node:path";
+test("session actions use focused session from list and parent session deeper", async () => {
+ const {selectedSessionForAction}=await import('../hooks/usage-explorer.mjs');
+ const a={...session,id:'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa'};
+ const b={...session,id:'bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb'};
+ const s={view:'sessions',project:'/repo',report:{...report,sessions:[a,b]}};
+ assert.equal(selectedSessionForAction(s,b.id),b);
+ assert.equal(selectedSessionForAction(s,null),null);
+ assert.equal(selectedSessionForAction({...s,view:'agents',session:a},b.id),a);
+ const source=requireSource();
+ assert.match(source,/onFocus:\(\)=>\{if\(state.view==='sessions'\)focusedSessionId=item.id/);
+ assert.doesNotMatch(source,/key:'session-open-terminal'|key:'session-copy-id'/);
+});
+
+test('agent rows hide IDs until drilldown and show main label',async()=>{
+ const {agentLabel}=await import('../hooks/usage-explorer.mjs');
+ assert.equal(agentLabel({id:'main'}),'Agent (main)');
+ assert.equal(agentLabel({id:'af22fd9030fbd751f'}),'Subagent');
+ assert.equal(agentLabel({id:'af22fd9030fbd751f',name:'code-reviewer'}),'code-reviewer');
+ const state={view:'agents',stack:[],project:'/repo',session:{...session,id:'different-session',agents:[{...agent,id:'af22fd9030fbd751f',name:'code-reviewer'}]},agent:null,report,sort:'tokens',query:''};
+ assert.equal(itemsFor(state)[0].label,'code-reviewer');
+});

package/tests/official-spend.test.mjs

@@ -0,0 +1,17 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {parseOfficialSpend,usageBar} from '../hooks/usage-explorer.mjs';
+test('official spend normalizes minor currency units',()=>{
+ const value=parseOfficialSpend({spend:{used:{amount_minor:7532,currency:'USD',exponent:2},limit:{amount_minor:20000,currency:'USD',exponent:2},percent:37.66}});
+ assert.deepEqual(value,{used:75.32,limit:200,currency:'USD',percent:37.66,source:'spend'});
+});
+test('extra usage fallback and no double counting',()=>{
+ const value=parseOfficialSpend({extra_usage:{used_credits:75.32,monthly_limit:200,currency:'USD',utilization:37.66}});
+ assert.equal(value.used,75.32);assert.equal(value.limit,200);
+});
+test('mismatched currencies do not report official spend',()=>{
+ assert.equal(parseOfficialSpend({spend:{used:{amount_minor:500,currency:'EUR',exponent:2},limit:{amount_minor:1000,currency:'USD',exponent:2}}}),null);
+});
+test('bar displays filled and empty segments',()=>{
+ assert.match(usageBar(37.66,10),/^████░░░░░░  37\.7%$/);
+});

package/tests/render.test.mjs

@@ -0,0 +1,23 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {screenDiff,clipAnsi,createExplorer} from '../src/tui.mjs';
+test('only updates changed lines and never clears the full screen',()=>{
+ const result=screenDiff('one\ntwo\nthree','one\nTWO\nthree');
+ assert.equal(result,'\x1b[2;1H\x1b[2KTWO');
+ assert.ok(!result.includes('\x1b[2J'));
+});
+test('clears removed lines and renders initial frame',()=>{
+ assert.equal(screenDiff('a\nb','a'),'\x1b[2;1H\x1b[2K');
+ assert.equal(screenDiff(null,'a\nb'),'\x1b[1;1H\x1b[2Ka\x1b[2;1H\x1b[2Kb');
+});
+
+test('colored rows are clipped without breaking ANSI reset',()=>{
+ const text='\x1b[31m'+('x'.repeat(100))+'\x1b[0m';
+ assert.equal(clipAnsi(text,10),'\x1b[31mxxxxxxxxxx\x1b[0m');
+});
+test('short terminals never receive a frame filling the last row',()=>{
+ const explorer=createExplorer({sessions:[],files:0,malformed:0,roots:[]},{cwd:process.cwd()});
+ const lines=explorer.render(45,18).split('\n');
+ assert.ok(lines.length<=17);
+ assert.ok(lines.every(line=>line.replace(/\x1b\[[0-9;]*m/g,'').length<=44));
+});

package/tests/snapshot.test.mjs

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {snapshot} from '../src/snapshot.mjs';
+test('snapshot reads configured billing cycle and reports no external data',()=>{
+ const home=fs.mkdtempSync(path.join(os.tmpdir(),'usage-mod-'));
+ try {
+  fs.mkdirSync(path.join(home,'.claude-usage-explorer'));
+  fs.writeFileSync(path.join(home,'.claude-usage-explorer','settings.json'),JSON.stringify({billingDay:1,billingTimeZone:'UTC'}));
+  const data=snapshot(['--period','cycle'],{now:Date.UTC(2026,10,5),home,roots:[]});
+  assert.match(data.periodLabel,/Nov 1, 2026/);assert.equal(data.report.overall.requests,0);
+ }finally{fs.rmSync(home,{recursive:true,force:true});}
+});

package/tests/statusline.test.mjs

@@ -0,0 +1,19 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {formatStatusLine,installStatusLine} from '../src/statusline.mjs';
+test('statusline distinguishes live session cost and historical cycle estimate',()=>{
+ const result=formatStatusLine({model:{display_name:'Claude Sonnet'},cost:{total_cost_usd:1.234}}, {cycle:{input:1000,output:0,cacheWrite:0,cacheRead:0,knownCost:12.5,unknownCostRequests:0}});
+ assert.match(result,/Session \$1\.23/);assert.match(result,/Cycle \$12\.50/);
+});
+test('install preserves other settings, refuses overwrite, and backs up',()=>{
+ const dir=fs.mkdtempSync(path.join(os.tmpdir(),'usage-status-'));
+ try{const file=path.join(dir,'settings.json');fs.writeFileSync(file,JSON.stringify({theme:'dark',statusLine:{type:'command',command:'echo previous'}}));
+ assert.throws(()=>installStatusLine({settingsPath:file,scriptPath:'/tmp/usage.mjs'}),/already/);
+ installStatusLine({settingsPath:file,scriptPath:'/tmp/usage.mjs',force:true});
+ const settings=JSON.parse(fs.readFileSync(file));assert.equal(settings.theme,'dark');assert.match(settings.statusLine.command,/statusline/);
+ assert.ok(fs.readdirSync(dir).some(f=>f.includes('backup')));
+ }finally{fs.rmSync(dir,{recursive:true,force:true});}
+});