claude-usage-explorer 1.1.5 → 1.1.6

package/.claude-plugin/marketplace.json

@@ -1,5 +1,30 @@
 {
   "name": "claude-usage-explorer-marketplace",
-  "owner": {"name": "Claude Usage Explorer contributors"},
-  "plugins": [{"name": "claude-usage", "source": "./", "description": "Local Claude Code usage explorer"}]
+  "description": "Local, read-only Claude Code token usage analytics and terminal tools",
+  "owner": {
+    "name": "IliasPol",
+    "url": "https://github.com/IliasPol"
+  },
+  "plugins": [
+    {
+      "name": "claude-usage",
+      "source": "./",
+      "description": "Explore Claude Code projects, sessions, token usage, model breakdowns and estimated costs locally",
+      "version": "1.1.6",
+      "author": {
+        "name": "IliasPol"
+      },
+      "homepage": "https://github.com/IliasPol/claude-usage",
+      "repository": "https://github.com/IliasPol/claude-usage",
+      "license": "MIT",
+      "category": "development",
+      "tags": [
+        "claude-code",
+        "usage",
+        "analytics",
+        "tokens",
+        "terminal"
+      ]
+    }
+  ]
 }

package/.claude-plugin/plugin.json

@@ -1,5 +1,11 @@
 {
   "name": "claude-usage",
-  "description": "Interactive native Claude Code usage sidebar and standalone TUI",
-  "version": "1.0.11"
+  "description": "Local, read-only Claude Code usage analytics with a native sidebar and standalone terminal UI",
+  "version": "1.1.6",
+  "author": {
+    "name": "IliasPol"
+  },
+  "homepage": "https://github.com/IliasPol/claude-usage",
+  "repository": "https://github.com/IliasPol/claude-usage",
+  "license": "MIT"
 }

package/README.md

@@ -1,125 +1,127 @@
-# Claude Usage Explorer v1.0.4
+# Claude Usage Explorer
 
-Local, read-only analytics for Claude Code sessions. No external npm dependencies and no tmux requirement.
+**Explore Claude Code token usage, estimated API-equivalent costs, projects, sessions, and agents — locally.** Use a native Claude Code sidebar or a standalone terminal dashboard. No uploads, telemetry, or external npm dependencies.
 
-## Requirements
+[![npm version](https://img.shields.io/npm/v/claude-usage-explorer.svg)](https://www.npmjs.com/package/claude-usage-explorer)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-- Node.js 20 or newer (22 LTS recommended).
-- Claude Code **2.1.287+** for native Mods (newer versions recommended).
-- Access to the same machine/filesystem where Claude stores its JSONL transcripts.
+## What's new in v1.1.6
 
-## Install and run
+- **Session actions:** open or copy session identifiers from supported views.
+- **Account usage diagnostics:** optional official usage-limit and extra-spend information when accessible; not the same as estimated API-equivalent cost.
+- **Cleaner agent navigation:** the main agent appears as **Agent (main)**; subagents use a recorded name when available, or **Subagent** when metadata is missing. Opaque agent IDs are shown only after opening an agent.
+- **Native sidebar and standalone terminal explorer:** navigate projects, sessions, agents, and models with token and API-equivalent cost breakdowns.
+- **Live refresh and flexible views:** filter and sort usage, switch reporting periods, and see per-model summaries.
+- **Privacy-first:** transcript processing stays on your computer. Account plan-limit information, when available, is separate from local estimated API-equivalent cost.
 
-1. Extract the ZIP into a permanent folder, e.g. `~/tools/claude-usage-explorer`.
-2. Run `./claude-usage tui` in that folder for the standalone full-screen explorer. On macOS, optionally run `./scripts/install-command.sh` once, then use `claude-usage tui` from any folder (ensure `~/.local/bin` is on your PATH).
-3. Start Claude with `claude --plugin-dir "$HOME/tools/claude-usage-explorer"`.
-4. In Claude Code type **`/usage-explorer`** to open the **native interactive sidebar**. In CLI, run `/tui fullscreen` first and use a wide terminal (100+ columns). Claude Desktop Code may dock the pane automatically if mods are supported locally.
-5. Optional: **`/claude-usage:open`** launches the standalone TUI in a separate terminal. This skill requires one model invocation; the native mod `/usage-explorer` is registered directly and does not need one.
+**Important:** Subagent names depend on metadata in the local Claude transcript; names are not inferred when absent. Estimated API costs are not the amount billed for a Claude subscription.
 
-**asdf users:** switch to a compatible Node before starting Claude, e.g. `asdf shell nodejs 22.22.2`, or `export ASDF_NODEJS_VERSION=22.22.2` if your asdf lacks `shell`. The native mod starts `node` from Claude's environment.
+## Preview
 
-## Native sidebar
+### Native Claude Code sidebar
 
-- Click projects → sessions → agents → models, and Back to return.
-- Switch periods (including current/previous billing cycle), filter entries, sort by tokens/cost, refresh.
-- Automatic refresh every five seconds while the pane is open.
-- Shows model usage and API-equivalent estimated cost (not subscription billing).
-- Billing renewal date/time/timezone and custom date ranges are configured in the standalone TUI (`B`); the sidebar reads those saved settings.
-- Unknown model prices are displayed as N/A rather than $0.
+![Claude Usage Explorer inside the Claude Code sidebar](docs/screenshots/native-sidebar.png)
 
-## Standalone TUI
+Use `/usage-explorer` to inspect local usage without leaving your Claude Code session.
 
-`./claude-usage tui`
+### Standalone terminal dashboard
 
-Supports all original navigation, custom dates, settings, live refresh and model breakdowns. `./claude-usage open` opens another terminal window when supported. `split` and its Claude skill were removed.
+![Claude Usage Explorer standalone terminal dashboard](docs/screenshots/standalone-tui.png)
 
-## Notes and limitations
+Run `claude-usage tui` to explore projects, sessions, token usage, model breakdowns, and estimated costs.
 
-The mod is implemented against Anthropic's current Mod API (session.start, command.run, ui.render, ui.open, ui.invalidate, process.run, clock.every). **It has not been verified in a live Claude Code or Claude Desktop installation**, so treat this as an integration candidate and report any host API errors. The standalone TUI is independently tested. The native sidebar uses clickable rows; arrow-key selection parity with the standalone TUI is not yet complete. Native mod availability depends on the Claude Code version and host.
+## Quick start
 
-The plugin reads local Claude transcript files and does not send them to an external service. Costs are estimates based on configured per-model pricing, not actual Claude subscription charges. Pricing defaults may need verification or overrides.
+**Standalone CLI (Node.js 20+):**
 
-## Validation
+```sh
+npm install -g claude-usage-explorer
+claude-usage tui
+```
 
-Run `npm test` and `npm run check`. For native mod validation on a machine with Claude Code installed: `claude plugin validate .`.
+**Claude Code community plugin marketplace:**
 
-## v1.0.4 sidebar fix
+```sh
+claude plugin marketplace add IliasPol/claude-usage
+claude plugin install claude-usage@claude-usage-explorer-marketplace
+```
+
+Then run `/usage-explorer` in a compatible Claude Code session.
+
+## Requirements
 
-Adds the required `onSubmit` handler as well as a stable `key` for the filter `<Input>` component in Claude Code 2.1.311. If the sidebar remains blank after upgrading, restart Claude Code with the updated plugin folder. The native mod still invokes `node` from Claude’s own environment, so start Claude under Node 20+ (e.g. Node 22).
+- Node.js 20+ (Node 22 recommended)
+- Claude Code with native Mods support for the sidebar
+- Local Claude Code JSONL transcript history
 
-## Fixing old asdf commands and terminal flashes (v1.0.4)
+## Standalone CLI: other ways to run
 
-The installer now creates a small executable wrapper instead of a symlink. This avoids resolving `bin/claude-usage.mjs` relative to `~/.local/bin`.
+Run without a global installation:
 
 ```sh
-./scripts/install-command.sh
-export PATH="$HOME/.local/bin:$PATH"
-hash -r
-type -a claude-usage
-claude-usage tui
+npx --yes --package claude-usage-explorer claude-usage tui
 ```
 
-If an old asdf shim still appears first, ensure `~/.local/bin` is prepended *after* asdf initialization in your shell startup file. The standalone TUI now clips terminal output, reserves the last terminal row, and ignores duplicate resize events to reduce blank-screen flashes.
+**Note:** On Windows PowerShell, use `npm.cmd` and `claude-usage.cmd` if execution policy blocks the `.ps1` shims.
+
+To run directly from a local checkout, use:
+
+```sh
+node ./bin/claude-usage.mjs tui
+```
 
-## Sidebar controls (v1.0.4)
+Run the TUI in an **interactive terminal**, not inside a noninteractive Claude tool shell. The optional macOS/Linux installer `./scripts/install-command.sh` is still available for source checkouts but is not needed for npm installations.
 
-The sidebar keeps its period picker collapsed by default, with the usage summary and drill-down list at the top and actions at the bottom. Click **◷ Period** (or use its host-supported `p` hotkey while the panel is focused) to choose a billing period. Other actions: Back (`h`), Refresh (`r`), Models (`m`), and Sort (`s`). Click a project or session to drill down. These shortcuts depend on Claude Code focus and hotkey handling.
+## Claude Code plugin installation
 
-### Native sidebar keyboard and exit (v1.0.6)
+Alternatively, from inside Claude Code use `/plugin marketplace add IliasPol/claude-usage`, followed by `/plugin install claude-usage@claude-usage-explorer-marketplace`.
 
-- **Esc** closes the pane and returns focus to Claude (native `closeOnEscape`).
-- **X** or **× Exit** closes the pane; **H** or **← Back** navigates up one level.
-- **Backspace cannot be registered as a custom pane shortcut** in the current Claude mod interface.
-- **Ctrl+X, then X** is the host-level close shortcut.
-- The action bar is placed after a flex-growing results area, to anchor it near the bottom where supported by the host layout. Terminal dimensions and host rendering may affect placement.
-- Claude’s built-in **/usage** shows account plan usage limits; Usage Explorer shows local history and API-equivalent cost estimates.
+This repository hosts a **community marketplace**, not an Anthropic-curated listing. After installation, use `/usage-explorer` in compatible Claude Code environments. Native mod/sidebar support may depend on the installed Claude Code version; if it is unavailable, the standalone `claude-usage tui` remains an option.
 
-### Install both native sidebar and standalone CLI (v1.0.7)
+## Native sidebar: local development
 
-Extract the release archive into `~/claude-usage-explorer-1.0.7`, then:
+Start Claude Code with the local plugin directory:
 
 ```sh
-cd ~/claude-usage-explorer-1.0.7
-./scripts/install-command.sh
-export PATH="$HOME/.local/bin:$PATH"
-hash -r
-type -a claude-usage
-claude-usage tui
+claude --plugin-dir /absolute/path/to/claude-usage-explorer
 ```
 
-Place `export PATH="$HOME/.local/bin:$PATH"` **after asdf initialization** in your shell startup file to keep the CLI command ahead of old asdf shims. Run `claude --plugin-dir "$HOME/claude-usage-explorer-1.0.7"`, enter `/tui fullscreen` if needed, then `/usage-explorer` to open the native sidebar.
+Then use `/usage-explorer`. In Claude Code CLI, `/tui fullscreen` may be required for the sidebar to appear. The native command is **`/usage-explorer`**, not `/claude-usage:open`.
 
-### v1.0.8 display updates
+The optional `/claude-usage:tui` skill attempts to open a **separate** terminal. This requires one model invocation and depends on your terminal environment. If no terminal appears, launch `node ./bin/claude-usage.mjs tui` directly in PowerShell or Terminal.
 
-The selected period persists across standalone TUI and native sidebar launches in `~/.claude-usage-explorer/settings.json` (`lastPeriod`). Each usage row shows a token percentage of its parent scope; the standalone TUI reserves four terminal columns on the right. Enterprise plan limits remain unavailable when no supported source provides them; no estimated spend is misrepresented as an official limit.
+## Features
 
-### Experimental official usage diagnostic (v1.0.9)
+- Drill down into projects, sessions, agents and models
+- Periods, sorting, filtering and auto-refresh
+- Token totals and estimated API-equivalent cost by model
+- Optional cached 5-hour and 7-day Claude Desktop plan-limit percentages (not live usage)
+- Read-only, local processing; no uploads or external analytics
 
-Inside `/usage-explorer`, select **Check official limits (opt-in)**. It first reads `$.session.usage()` and then, if Claude supplies an opaque first-party authorization handle, calls Anthropic's undocumented OAuth usage endpoint through `$.http.fetch`. The mod never reads or stores the token and only renders allowlisted numeric usage fields and reset timestamps; no raw response is logged or persisted. Enterprise monthly spending limits may not be included. This is an experimental diagnostic, not a stable public API integration. No automatic polling.
+**Important:** Estimated API-equivalent cost is not what your Claude subscription was charged. Cached plan percentages can be stale. Claude Desktop Chat history is not included in Claude Code's local transcript analytics.
 
-### Official account usage (v1.0.10)
+## Windows
 
-Native sidebar automatically loads official utilization through Claude-hosted authorization when available, refreshes no more often than every 3 minutes, and supports manual refresh. It shows a percentage bar for recognized limits (including Enterprise `extra_usage`) but does not infer a dollar amount or billing cap. The endpoint is undocumented and may change; credentials and raw responses are never stored. Standalone TUI remains local-only.
+In PowerShell, from the extracted project directory (or use the npm installation above):
 
-### Usage response schema diagnostic (v1.0.11)
+```powershell
+node .\bin\claude-usage.mjs tui
+claude --plugin-dir "$PWD"
+```
 
-The native sidebar displays official account spending and available limit bars without the developer-only response field diagnostic. No automatic billing-period override is applied.
+## Development
 
-## v1.1.0 changes
+```sh
+npm test
+npm run check
+```
 
-- Native sidebar now reads official `spend.used` and `spend.limit` in minor currency units, with `extra_usage` as a fallback, and displays actual used/limit/remaining amounts with a higher-contrast utilization bar. This is separate from estimated local API cost.
-- Native sidebar has a `? Help` control, and the summary follows the selected project/session scope.
-- Standalone TUI summary follows the selected scope; tiny nonzero shares display `<0.1%`.
-- In the standalone macOS TUI, select a session and press `e` to open it in Terminal.app; press uppercase `C` to copy its ID. These actions do not call a model. Terminal.app is used even if the current terminal is PortX.
-- Native in-place session resume is **not implemented** because a supported session-switching Mods API has not been verified. Official billing-cycle reset timestamps also remain unverified; locally configured dates are not represented as official.
-- `stats-cache.json` versus transcript token reconciliation remains open. Local transcript counts should not be treated as official account totals.
+The GitHub Actions workflow tests on Windows, macOS and Ubuntu.
 
-## v1.1.1 hotfix
-- Fix native sidebar render failure: Help uses `z` instead of unsupported `?` button hotkey. Standalone TUI still uses `?` for Help.
-- Add a regression test for Mods UI hotkey restrictions.
+## Contributing, security, and license
 
-### Native session actions (v1.1.2)
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Please report vulnerabilities following [SECURITY.md](SECURITY.md). This project is licensed under the [MIT License](LICENSE).
 
-Drill into a project and select a session. Use **Open session in Terminal** to resume in a new macOS Terminal window from the original project directory, or **Copy session ID** to copy the identifier. In-place switching of the active Claude Code session is not supported.
+## Support
 
-Agent rows display a readable agent type when available in local transcripts, otherwise “Subagent”; raw subagent IDs appear only after opening an agent. Session shortcuts O/C apply inside a session, not to highlighted Sessions-list entries.
+If Claude Usage Explorer is useful, consider [starring the repository](https://github.com/IliasPol/claude-usage). The tool is free and open source.

package/commands/tui.md

@@ -0,0 +1,12 @@
+---
+description: Launch the interactive Claude Usage Explorer in a separate terminal window, without model calls for navigation
+allowed-tools: Bash
+---
+
+Launch the local TUI sidecar once, without asking the user any questions. Use the following command via Bash, passing the current project directory as CLAUDE_PROJECT_DIR when available:
+
+```sh
+node "${CLAUDE_PLUGIN_ROOT}/bin/claude-usage.mjs" open
+```
+
+Do not run the `tui` command directly in the Bash tool (it needs an interactive terminal). The `open` command starts a separate terminal process and exits immediately. Report only whether the launch succeeded. This slash command requires one Claude invocation; subsequent navigation and refreshes use zero model calls. Do not pretend it embeds inside the Claude Code conversation. If a terminal emulator is unsupported, advise running `node "${CLAUDE_PLUGIN_ROOT}/bin/claude-usage.mjs" tui` in a separate terminal.

package/hooks/usage-explorer.mjs

@@ -1,5 +1,13 @@
 // Claude Code native mod. The UI uses host components; local analytics run in a child Node process.
 // No model requests are made when opening, navigating or refreshing this pane.
+// Native hooks run in a restricted loader; use web-standard URL APIs instead of node: imports.
+export function scriptPathFromModuleUrl(moduleUrl){
+  const url=new URL('../bin/claude-usage.mjs',moduleUrl);
+  let p=decodeURIComponent(url.pathname);
+  if(/^\/[A-Za-z]:\//.test(p))p=p.slice(1);
+  if(url.host&&url.host!=='localhost')p=`//${url.host}${p}`;
+  return p;
+}
 const PANE='claude-usage-explorer';
 const PERIODS=[['Billing cycle','cycle'],['Previous cycle','previous-cycle'],['All time','all'],['Today','today'],['Yesterday','yesterday'],['7 days','7d'],['30 days','30d'],['This month','month'],['Previous month','previous-month']];
 let state={period:'all',view:'projects',stack:[],project:null,session:null,agent:null,report:null,periodLabel:'All time',loading:false,error:'',updatedAt:0,sort:'tokens',query:'',periodMenu:false};
@@ -52,7 +60,7 @@ export function back(s){
   return {...s,...last,stack:s.stack.slice(0,-1),query:''};
 }
 async function persistPeriod($,period){
-  try {const script=decodeURIComponent(new URL('../bin/claude-usage.mjs',import.meta.url).pathname);await $.process.run(['node',script,'preference','period',period],{timeoutMs:5000});}catch{}
+  try {const script=scriptPathFromModuleUrl(import.meta.url);await $.process.run(['node',script,'preference','period',period],{timeoutMs:5000});}catch{}
 }
 async function refresh($){
   if(inFlight)return inFlight;
@@ -60,7 +68,7 @@ async function refresh($){
   inFlight=(async()=>{
     try {
       // Module location resolves to the plugin's installed directory, independent of cwd.
-      const script=decodeURIComponent(new URL('../bin/claude-usage.mjs',import.meta.url).pathname);
+      const script=scriptPathFromModuleUrl(import.meta.url);
       const result=await $.process.run(['node',script,'snapshot','--period',state.period],{timeoutMs:30000});
       if(result.exitCode!==0)throw new Error((result.stderr||'Unable to read usage').trim().slice(0,240));
       const snap=JSON.parse(result.stdout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-explorer",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Local, read-only Claude Code usage analytics CLI and plugin",
   "type": "module",
   "bin": {
@@ -9,10 +9,40 @@
   "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"
+    "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"
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "src/",
+    "hooks/",
+    "commands/",
+    ".claude-plugin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/IliasPol/claude-usage#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IliasPol/claude-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/IliasPol/claude-usage/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "usage-tracker",
+    "token-usage",
+    "cost-tracking",
+    "terminal-ui",
+    "analytics",
+    "developer-tools",
+    "cli"
+  ]
 }

package/src/core.mjs

@@ -90,10 +90,7 @@ export function parseFile(file, rates=DEFAULT_RATES) {
     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;
-    }
+    if(id.isSubagent&&!agentName){const candidate=r.agentType||r.agentName||r.agent_type||r.agent_name;if(typeof candidate==='string'&&candidate.trim()&&candidate.length<=100)agentName=candidate.trim();}
     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') {
@@ -116,12 +113,12 @@ 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,agentName,isSubagent:id.isSubagent,title,cwd,start,end,bad,requests:[...requests.values()]};
+  return {file,sessionId:sessionId||id.id,agent:id.agent,isSubagent:id.isSubagent,agentName,title,cwd,start,end,bad,requests:[...requests.values()]};
 }
 
 // Cache derived metadata and token counters only. Never persist transcript text beyond
 // the short session title. Cache invalidates when file size/mtime changes.
-const CACHE_VERSION=3;
+const CACHE_VERSION=4;
 const cacheDir=()=>path.join(os.homedir(),'.claude-usage-explorer','cache-v3');
 function readCachedFile(file){
   const st=fs.statSync(file);
@@ -156,7 +153,8 @@ export function ingest(roots,rates=DEFAULT_RATES) {
     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,name:parsed.agentName||null,requests:[]};s.agents.set(parsed.agent,agent);}
-    agent.name=agent.name||parsed.agentName||null;agent.requests.push(...parsed.requests);
+    if(!agent.name&&parsed.agentName)agent.name=parsed.agentName;
+    agent.requests.push(...parsed.requests);
   }
   return {sessions:[...sessions.values()],files:files.length,malformed,roots};
 }

package/src/plan-usage.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Claude Desktop's plan-usage-history.json is undocumented, optional cached data.
+// Read only known numeric utilization fields; never expose organization identifiers.
+export function planUsageFromSamples(samples, now=Date.now()) {
+  if (!Array.isArray(samples)) return null;
+  const valid=samples.filter(s=>s && Number.isFinite(s.t) && s.u &&
+    (Number.isFinite(s.u.fh)||Number.isFinite(s.u.sd)))
+    .map(s=>({timestamp:s.t<1e12?s.t*1000:s.t,
+      fiveHour:Number.isFinite(s.u.fh)?s.u.fh:null,
+      sevenDay:Number.isFinite(s.u.sd)?s.u.sd:null}))
+    .filter(s=>s.timestamp>0 && s.timestamp<=now+86400000)
+    .sort((a,b)=>a.timestamp-b.timestamp);
+  if (!valid.length)return null;
+  const latest=valid.at(-1);
+  return { ...latest, stale:now-latest.timestamp>15*60*1000,
+    samples:valid.slice(-100),source:'Claude Desktop cached history'};
+}
+export function readPlanUsage({platform=process.platform,localAppData=process.env.LOCALAPPDATA,home=process.env.HOME,now=Date.now()}={}){
+  const roots=[];
+  if(platform==='win32'&&localAppData)roots.push(path.join(localAppData,'Claude-Data'));
+  if(platform==='darwin'&&home){roots.push(path.join(home,'Library','Application Support','Claude-Data'));roots.push(path.join(home,'Library','Application Support','Claude'));}
+  let best=null;
+  for(const root of roots){
+    let folders=[];
+    try{folders=fs.readdirSync(root,{withFileTypes:true}).filter(x=>x.isDirectory()&&x.name.startsWith('claude_')).map(x=>path.join(root,x.name));}catch{continue;}
+    for(const folder of folders){
+      try{
+        const file=path.join(folder,'plan-usage-history.json');
+        if(fs.statSync(file).size>2_000_000)continue;
+        const data=JSON.parse(fs.readFileSync(file,'utf8'));
+        const result=planUsageFromSamples(data.samples,now);
+        if(result&&(!best||result.timestamp>best.timestamp))best=result;
+      }catch{}
+    }
+  }
+  return best;
+}

package/src/snapshot.mjs

@@ -3,6 +3,7 @@ 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');
@@ -13,5 +14,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 {savedPeriod:settings.lastPeriod||'all',period,periodLabel:describePeriod(period,settings,now),settings:{billingDay:settings.billingDay||null,billingTimeZone:settings.billingTimeZone||'UTC'},updatedAt:now,report};
+  return {period,periodLabel:describePeriod(period,settings,now),settings:{billingDay:settings.billingDay||null,billingTimeZone:settings.billingTimeZone||'UTC'},updatedAt:now,report,planUsage:readPlanUsage({now})};
 }

package/src/tui.mjs

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
 import {spawnSync} from 'node:child_process';
+import {readPlanUsage} from './plan-usage.mjs';
 import {ingest,projectRoots,summarize,timeWindow,totalTokens,number,DEFAULT_RATES} from './core.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']];
@@ -25,7 +26,9 @@ 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=settings.lastPeriod||'all'}={}){
+export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),period=settings.lastPeriod||'all',planReader=readPlanUsage}={}){
+ 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 liveState={enabled:true,lastUpdated:Date.now(),lastCheck:Date.now(),error: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});
@@ -79,6 +82,7 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
  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;
@@ -93,6 +97,8 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   line(`  ${c(crumb,'1')}     ${c('PERIOD','90')} ${describePeriod(currentPeriod,settings)}     ${c('SORT','90')} ${sort} ${descending?'↓':'↑'}`);
   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`);
+  const planLabel=planUsage?`5h ${planUsage.fiveHour??'—'}% · 7d ${planUsage.sevenDay??'—'}% · ${planUsage.stale?'Cached, may be outdated':'Cached, recent'}`:'Claude Desktop plan usage unavailable';
+  line(`  ${c('PLAN LIMITS','1;36')}  ${c(planLabel,'90')}`);
   rule();
   const available=rows();selection=Math.max(0,Math.min(selection,Math.max(0,available.length-1)));
   const selected=available[selection];
@@ -100,7 +106,7 @@ 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=6;
+  const headerHeight=7;
   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.
@@ -140,7 +146,7 @@ export function createExplorer(data,{cwd=process.cwd(),settings=readSettings(),p
   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,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;}};
+ 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 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) {

package/claude-usage

@@ -1,20 +0,0 @@
-#!/bin/sh
-# Portable launcher: run directly from this folder, without npm global shims.
-set -eu
-ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-if [ -n "${CLAUDE_USAGE_NODE:-}" ]; then
-  NODE="$CLAUDE_USAGE_NODE"
-elif command -v node >/dev/null 2>&1 && node -e 'process.exit(Number(process.versions.node.split(".")[0]) < 20)' >/dev/null 2>&1; then
-  NODE=$(command -v node)
-else
-  NODE=''
-  for candidate in "$HOME"/.asdf/installs/nodejs/22.22.2/bin/node "$HOME"/.asdf/installs/nodejs/22.22.1/bin/node "$HOME"/.asdf/installs/nodejs/24.18.0/bin/node "$HOME"/.asdf/installs/nodejs/20.19.5/bin/node; do
-    if [ -x "$candidate" ]; then NODE="$candidate"; break; fi
-  done
-  if [ -z "$NODE" ]; then
-    printf '%s\n' 'Claude Usage Explorer requires Node.js 20+. Set CLAUDE_USAGE_NODE to its executable path.' >&2
-    exit 1
-  fi
-fi
-if [ "$#" -eq 0 ]; then set -- tui; fi
-exec "$NODE" "$ROOT/bin/claude-usage.mjs" "$@"

package/tests/core.test.mjs

@@ -1,30 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,177 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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});}
-});

package/tests/tui.test.mjs

@@ -1,104 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import {createExplorer,describePeriod} from '../src/tui.mjs';
-const z={input:3,output:2,cacheRead:5,cacheWrite:1,model:'claude-sonnet-4-5',timestamp:Date.now()};
-const data={sessions:[{id:'s1',title:'Example session',cwd:'/tmp/demo',start:Date.now(),end:Date.now(),agents:new Map([['main',{id:'main',requests:[z]}]])}],files:1,malformed:0,roots:[]};
-test('TUI drills from project to session to agent to model without LLM',()=>{
- const x=createExplorer(data,{period:'all',cwd:'/tmp/demo',settings:{}});
- assert.equal(x.rows().length,1);
- assert.match(x.render(115,30),/CLAUDE USAGE EXPLORER/);
- x.open();assert.equal(x.view,'sessions');assert.equal(x.rows()[0].title,'Example session');
- x.open();assert.equal(x.view,'agents');assert.equal(x.rows()[0].id,'main');
- x.open();assert.equal(x.view,'models');assert.equal(x.rows()[0].name,'claude-sonnet-4-5');
- x.restore();assert.equal(x.view,'agents');
-});
-test('TUI switches dates and shows model columns',()=>{
- const x=createExplorer(data,{period:'all',settings:{}});
- x.nav('periods');const i=x.rows().findIndex(x=>x.value==='today');x.selection=i;x.open();
- assert.equal(x.currentPeriod,'today');assert.match(x.render(120,30),/C.READ/);
-});
-test('TUI shows models for selected project without drilling into sessions',()=>{
- const x=createExplorer(data,{period:'all',settings:{}});
- assert.match(x.render(130,32),/MODELS IN SELECTED ROW/);
- assert.match(x.render(130,32),/claude-sonnet-4-5/);
- x.setSort('output');assert.equal(x.sort,'output');
-});
-test('TUI displays unknown model pricing as N/A, never a misleading zero',()=>{
- const unknown={...z,model:'claude-unknown-9-9'};
- const d={...data,sessions:[{...data.sessions[0],agents:new Map([['main',{id:'main',requests:[unknown]}]])}]};
- const x=createExplorer(d,{period:'all',settings:{}});
- assert.match(x.render(130,32),/N\/A/);
-});
-test('TUI footer and model panel remain at fixed rows as selection changes',()=>{
- const extra={...data.sessions[0],id:'s2',title:'Another session',cwd:'/tmp/other'};
- const x=createExplorer({...data,sessions:[...data.sessions,extra]},{period:'all',settings:{}});
- const a=x.render(120,32).split('\n');
- x.selection=1;
- const b=x.render(120,32).split('\n');
- for(const label of ['MODELS IN SELECTED ROW','Billing/settings','PgUp/PgDn scroll']){
-  const index=lines=>lines.findIndex(line=>line.includes(label));
-  assert.equal(index(a),index(b),label);
- }
- assert.equal(a.length,b.length);
-});
-
-test('billing periods appear first and require configuration before selection',()=>{
- const x=createExplorer(data,{period:'all',settings:{}});
- x.nav('periods');
- assert.equal(x.rows()[0].value,'cycle');
- assert.equal(x.rows()[1].value,'previous-cycle');
- assert.equal(x.open(),'billing-required:cycle');
- assert.equal(x.currentPeriod,'all');
- x.setBillingDay(5,'Europe/Athens',10,30);
- assert.equal(x.open(),null);
- assert.equal(x.currentPeriod,'cycle');
-});
-test('custom date selection requests input instead of navigating or quitting',()=>{
- const x=createExplorer(data,{period:'all',settings:{}});
- x.nav('periods');
- x.selection=x.rows().findIndex(r=>r.value==='custom');
- assert.equal(x.open(),'custom');
- assert.equal(x.view,'periods');
- x.setPeriod('2026-11-01:2026-11-05');
- assert.equal(x.currentPeriod,'2026-11-01:2026-11-05');
-});
-
-test('billing date choices and header show descriptive date ranges',()=>{
- const settings={billingDay:1,billingTimeZone:'UTC',billingHour:0,billingMinute:0};
- assert.equal(describePeriod('cycle',settings,Date.UTC(2026,10,5)),'Current billing cycle · Nov 1, 2026 – Nov 30, 2026');
- assert.equal(describePeriod('previous-cycle',settings,Date.UTC(2026,10,5)),'Previous billing cycle · Oct 1, 2026 – Oct 31, 2026');
- assert.match(describePeriod('cycle',{},Date.UTC(2026,10,5)),/Set renewal date/);
- const x=createExplorer(data,{settings,period:'cycle'});
- assert.match(x.render(130,32),/Current billing cycle/);
- x.nav('periods');
- assert.match(x.rows()[0].label,/Nov/);
-});
-
-test('live refresh preserves project, session, sorting, and period',()=>{
- const x=createExplorer(data,{cwd:'/tmp/demo',settings:{}});
- x.open();x.open();
- x.setSort('output');x.setPeriod('today');
- // Date changes intentionally reset the view; navigate back into the session.
- x.open();x.open();
- assert.equal(x.view,'agents');
- x.rescan([], {automatic:true});
- assert.equal(x.currentPeriod,'today');
- assert.equal(x.sort,'output');
- assert.equal(x.view,'projects'); // source was removed by rescan
- x.toggleLive();assert.equal(x.liveState.enabled,false);
- x.toggleLive();assert.equal(x.liveState.enabled,true);
-});
-
-test('file signature changes only when JSONL metadata changes', async()=>{
- const {historySignature}=await import('../src/tui.mjs');
- const fs=await import('node:fs');
- const os=await import('node:os');
- const path=await import('node:path');
- const root=fs.mkdtempSync(path.join(os.tmpdir(),'claude-live-'));
- try{
-  const file=path.join(root,'a.jsonl');
-  fs.writeFileSync(file,'a');const a=historySignature([root]);
-  assert.equal(a,historySignature([root]));
-  fs.appendFileSync(file,'bc');assert.notEqual(a,historySignature([root]));
- }finally{fs.rmSync(root,{recursive:true,force:true});}
-});