claude-usage-explorer 0.0.0-stage → 1.0.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,30 @@
+{
+  "name": "claude-usage-explorer-marketplace",
+  "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.0.0",
+      "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

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

package/LICENSE

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

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Claude Usage Explorer
+
+**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.
+
+[![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)
+
+## Preview
+
+### Native Claude Code sidebar
+
+![Claude Usage Explorer inside the Claude Code sidebar](docs/screenshots/native-sidebar.png)
+
+Use `/usage-explorer` to inspect local usage without leaving your Claude Code session.
+
+### Standalone terminal dashboard
+
+![Claude Usage Explorer standalone terminal dashboard](docs/screenshots/standalone-tui.png)
+
+Run `claude-usage tui` to explore projects, sessions, token usage, model breakdowns, and estimated costs.
+
+## Quick start
+
+**Standalone CLI (Node.js 20+):**
+
+```sh
+npm install -g claude-usage-explorer
+claude-usage tui
+```
+
+**Claude Code community plugin marketplace:**
+
+```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
+
+- Node.js 20+ (Node 22 recommended)
+- Claude Code with native Mods support for the sidebar
+- Local Claude Code JSONL transcript history
+
+## Standalone CLI: other ways to run
+
+Run without a global installation:
+
+```sh
+npx --yes --package claude-usage-explorer claude-usage tui
+```
+
+**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
+```
+
+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.
+
+## Claude Code plugin installation
+
+Alternatively, from inside Claude Code use `/plugin marketplace add IliasPol/claude-usage`, followed by `/plugin install claude-usage@claude-usage-explorer-marketplace`.
+
+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.
+
+## Native sidebar: local development
+
+Start Claude Code with the local plugin directory:
+
+```sh
+claude --plugin-dir /absolute/path/to/claude-usage-explorer
+```
+
+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`.
+
+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.
+
+## Features
+
+- 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
+
+**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.
+
+## Windows
+
+In PowerShell, from the extracted project directory (or use the npm installation above):
+
+```powershell
+node .\bin\claude-usage.mjs tui
+claude --plugin-dir "$PWD"
+```
+
+## Development
+
+```sh
+npm test
+npm run check
+```
+
+The GitHub Actions workflow tests on Windows, macOS and Ubuntu.
+
+## Contributing, security, and license
+
+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).
+
+## Support
+
+If Claude Usage Explorer is useful, consider [starring the repository](https://github.com/IliasPol/claude-usage). The tool is free and open source.

package/bin/claude-usage.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/core.mjs';
+import { launchTui } from '../src/tui.mjs';
+import { snapshot } from '../src/snapshot.mjs';
+import {runStatusLine,installStatusLine} from '../src/statusline.mjs';
+import {launchSidecar} from '../src/launcher.mjs';
+(process.argv[2] === 'open' ? Promise.resolve(launchSidecar({cwd:process.env.CLAUDE_PROJECT_DIR||process.cwd()})).then(()=>console.log('Opened Claude Usage Explorer in a separate terminal.')) : process.argv[2] === 'snapshot' ? Promise.resolve(snapshot(process.argv.slice(3))).then(data=>console.log(JSON.stringify(data))) : process.argv[2] === 'tui' ? launchTui(process.argv.slice(3)) : process.argv[2] === 'statusline' ? runStatusLine() : process.argv[2] === 'statusline-install' ? Promise.resolve(console.log('Installed status line in',installStatusLine({force:process.argv.includes('--force')}))) : main(process.argv.slice(2))).catch(err => { console.error('Error:', err.message); process.exitCode = 1; });

package/commands/open.md

@@ -0,0 +1,12 @@
+---
+description: Open 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/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/hooks.json

@@ -0,0 +1,5 @@
+{
+  "modules": [
+    "./usage-explorer.mjs"
+  ]
+}

package/hooks/usage-explorer.mjs

@@ -0,0 +1,159 @@
+// 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: no node: built-in imports.
+// Convert the file URL using web-standard URL APIs, preserving Windows drive paths.
+export function scriptPathFromModuleUrl(moduleUrl){
+  const url=new URL('../bin/claude-usage.mjs',moduleUrl);
+  let path=decodeURIComponent(url.pathname);
+  if(/^\/[A-Za-z]:\//.test(path))path=path.slice(1);
+  if(url.host&&url.host!=='localhost')path=`//${url.host}${path}`;
+  return path;
+}
+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,planUsage:null};
+let timer=null;
+let inFlight=null;
+const total=s=>(s?.input||0)+(s?.output||0)+(s?.cacheRead||0)+(s?.cacheWrite||0);
+const compact=n=>Intl.NumberFormat('en-US',{notation:'compact',maximumFractionDigits:1}).format(n||0);
+const price=s=>s?.unknownCostRequests?'N/A':`$${(s?.knownCost||0).toFixed(2)}`;
+const name=p=>String(p||'').replace(/\\/g,'/').split('/').filter(Boolean).pop()||p;
+const change=($,patch)=>{state={...state,...patch};void $.ui.invalidate('ui.render');};
+export function itemsFor(s=state){
+  const r=s.report;
+  if(!r)return [];
+  let items=[];
+  if(s.view==='projects')items=r.projects.map(x=>({id:x.name,label:name(x.name),stats:x.stats,source:x}));
+  if(s.view==='sessions')items=r.sessions.filter(x=>!s.project||x.project===s.project).map(x=>({id:x.id,label:x.title,stats:x.stats,source:x}));
+  if(s.view==='agents'){const current=r.sessions.find(x=>x.id===s.session?.id)||s.session;items=(current?.agents||[]).map(x=>({id:x.id,label:x.id==='main'?'Main agent':x.id,stats:x.stats,source:x}));}
+  if(s.view==='models'){const current=r.sessions.find(x=>x.id===s.session?.id)||s.session;items=modelScope(s).map(x=>({id:x.name,label:x.name,stats:x.stats,source:x}));}
+  if(s.query)items=items.filter(x=>x.label.toLowerCase().includes(s.query.toLowerCase()));
+  return items.sort((a,b)=>s.sort==='cost'?(b.stats.knownCost-a.stats.knownCost):total(b.stats)-total(a.stats));
+}
+export function drill(s,item){
+  const previous={view:s.view,project:s.project,session:s.session,agent:s.agent};
+  if(s.view==='projects')return {...s,stack:[...s.stack,previous],view:'sessions',project:item.id,session:null,agent:null,query:''};
+  if(s.view==='sessions')return {...s,stack:[...s.stack,previous],view:'agents',session:item.source,agent:null,query:''};
+  if(s.view==='agents')return {...s,stack:[...s.stack,previous],view:'models',agent:item.source,query:''};
+  return s;
+}
+export function modelScope(s){
+  const r=s.report;
+  if(!r)return [];
+  const session=r.sessions.find(x=>x.id===s.session?.id)||s.session;
+  const agent=session?.agents?.find(x=>x.id===s.agent?.id)||s.agent;
+  const project=r.projects.find(x=>x.name===s.project);
+  return agent?.models||session?.models||project?.models||r.models||[];
+}
+export function back(s){
+  if(!s.stack.length)return {...s,view:'projects',project:null,session:null,agent:null,query:''};
+  const last=s.stack[s.stack.length-1];
+  return {...s,...last,stack:s.stack.slice(0,-1),query:''};
+}
+async function refresh($){
+  if(inFlight)return inFlight;
+  change($,{loading:true,error:''});
+  inFlight=(async()=>{
+    try {
+      // Module location resolves to the plugin's installed directory, independent of cwd.
+      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);
+      // Refresh preserves the active drilldown; a missing session is handled by an empty list.
+      change($,{report:snap.report,planUsage:snap.planUsage||null,periodLabel:snap.periodLabel,updatedAt:snap.updatedAt,loading:false,error:''});
+    }catch(err){change($,{loading:false,error:String(err?.message||err).slice(0,260)});}
+  })().finally(()=>{inFlight=null});
+  return inFlight;
+}
+async function show($){await $.ui.open({id:PANE,title:'Claude Usage Explorer',focus:true,closeOnEscape:true});void refresh($);}
+export function register(on){
+  on('session.start',async ($,e,next)=>{
+    await $.command.register({name:'usage-explorer',description:'Open the native interactive Claude Usage Explorer sidebar',immediate:true});
+    return next(e);
+  });
+  on('command.run',{command:'usage-explorer'},async ($,e)=>{
+    const surfaces=await $.session.surfaces().catch(()=>[]);
+    if(surfaces.includes('terminal')&&!e.presentation.isFullscreen)return {text:'Use /tui fullscreen, then /usage-explorer. The native sidebar needs fullscreen layout.'};
+    if(surfaces.includes('terminal')&&e.presentation.columns<100)return {text:'Widen the terminal to at least 100 columns, then /usage-explorer.'};
+    await show($);
+    timer?.cancel();timer=$.clock.every(5000,()=>void refresh($));
+    return {text:'Usage Explorer opened in the sidebar. Navigation and refresh do not call the model.'};
+  });
+  on('ui.close',async ($,e,next)=>{if(e.id===PANE){timer?.cancel();timer=null;}return next(e);});
+  on('session.end',async ($,e,next)=>{timer?.cancel();timer=null;return next(e);});
+  on('ui.render',{component:'Pane',requestId:PANE},($,e,next)=>{
+    if(e.surface!=='terminal'&&e.surface!=='desktop')return next(e);
+    const {Box,Text,Button,Input}=$.ui.resolve(e);
+    const rows=itemsFor();
+    // Prefer the actual viewport row count when the host exposes it.
+    // Percent heights are not consistently resolved in Claude terminal panes.
+    const viewportRows=Number(e.presentation?.rows??e.viewport?.height??e.rows);
+    const paneHeight=Number.isFinite(viewportRows)&&viewportRows>=16?Math.max(12,viewportRows-3):'100%';
+    const press=item=>change($,drill(state,item));
+    const models=()=>{if(state.view==='models'){change($,back(state));return;}change($,{...state,stack:[...state.stack,{view:state.view,project:state.project,session:state.session,agent:state.agent}],view:'models',query:''});};
+    const periodButtons=PERIODS.map(([label,id])=>Button({key:`period-${id}`,plain:true,label:id===state.period?`● ${label}`:`  ${label}`,onPress:()=>{change($,{period:id,periodMenu:false});void refresh($);}}));
+    const action=(label,hotkey,fn)=>Button({key:`action-${label}`,plain:true,label,hotkey,onPress:fn});
+    const path=[state.project&&name(state.project),state.session?.title,state.agent?.id].filter(Boolean);
+    const breadcrumb=`${state.view.toUpperCase()}${path.length?'  /  '+path.join(' / '):''}`;
+    const stats=state.report?.overall;
+    const plan=state.planUsage;
+    const scopeModels=modelScope(state).slice().sort((a,b)=>total(b.stats)-total(a.stats));
+    const showModelSummary=state.view!=='models'&&scopeModels.length>0;
+    const divider=()=>Text({dimColor:true,children:'────────────────────────────────'});
+    const header=Box({flexDirection:'column',gap:0,children:[
+      Box({flexDirection:'row',gap:2,children:[Text({bold:true,children:'USAGE EXPLORER'}),Text({dimColor:true,children:state.loading?'Updating…':'● Auto · 5s'})]}),
+      Text({dimColor:true,wrap:'truncate-end',children:state.periodLabel}),
+      stats?Text({bold:true,children:`${compact(total(stats))} tokens  ·  ${price(stats)} est. API cost`}):Text({dimColor:true,children:'Loading local usage…'}),
+      stats?Text({dimColor:true,children:`${stats.requests} requests  ·  ${state.report.files} files`}):null,
+    ].filter(Boolean)});
+    const planSection=Box({flexDirection:'column',gap:0,children:[
+      Text({bold:true,children:'PLAN LIMITS'}),
+      plan?Text({children:`5-hour ${plan.fiveHour??'—'}%   ·   7-day ${plan.sevenDay??'—'}%`}):Text({dimColor:true,children:'Desktop usage cache unavailable'}),
+      plan?Text({dimColor:true,wrap:'truncate-end',children:`${plan.stale?'Cached · May be outdated':'Cached · Recently updated'} · ${new Date(plan.timestamp).toLocaleString()}`}):null,
+    ].filter(Boolean)});
+    const modelSummary=showModelSummary?Box({flexDirection:'column',children:[
+      Text({bold:true,children:'MODEL BREAKDOWN'}),
+      ...scopeModels.slice(0,3).map((model,i)=>Text({key:`model-summary-${i}`,dimColor:true,wrap:'truncate-end',children:`${model.name} · ${compact(total(model.stats))} · ${price(model.stats)}`})),
+      ...(scopeModels.length>3?[Text({dimColor:true,children:`+${scopeModels.length-3} more (M to view)`})]:[]),
+    ]}):null;
+    // Keep the action strip separate from the growing list. Host layout decides
+    // whether a 100%-height pane is available; do not claim fixed positioning.
+    const footer=Box({flexDirection:'column',flexShrink:0,children:[
+      divider(),
+      Box({flexDirection:'row',gap:1,flexWrap:'wrap',children:[
+        action('← Back','h',()=>change($,back(state))),
+        action('↻ Refresh','r',()=>void refresh($)),
+        action('◷ Period','p',()=>change($,{periodMenu:!state.periodMenu})),
+        action(state.view==='models'?'← Close models':'▤ Models','m',models),
+        action(state.sort==='tokens'?'↓ Tokens':'↓ Cost','s',()=>change($,{sort:state.sort==='tokens'?'cost':'tokens'})),
+        action('× Exit','x',()=>void $.ui.close({id:PANE})),
+      ]}),
+      Text({dimColor:true,wrap:'truncate-end',children:'Esc close · H back · R refresh · P period · M models · S sort'}),
+    ]});
+    return Box({flexDirection:'column',paddingX:1,flexGrow:1,minHeight:0,height:paneHeight,justifyContent:'space-between',children:[
+      Box({flexDirection:'column',flexGrow:1,minHeight:0,children:[
+        header,
+        divider(),
+        planSection,
+        divider(),
+        Text({bold:true,wrap:'truncate-end',children:breadcrumb}),
+        Input({key:'usage-filter',placeholder:'Search projects / sessions…',value:state.query,onInput:v=>change($,{query:v}),onSubmit:v=>change($,{query:typeof v==='string'?v:state.query})}),
+        ...(state.periodMenu?[
+          Text({bold:true,children:'CHOOSE PERIOD'}),
+          Box({flexDirection:'column',gap:0,children:periodButtons}),
+          divider(),
+        ]:[]),
+        ...(state.error?[Text({color:'red',wrap:'wrap',children:state.error})]:[]),
+        ...(state.view==='models'?[action('← Back to previous view','h',()=>change($,back(state)))]:[]),
+        Box({flexDirection:'column',flexGrow:1,minHeight:0,children:[
+          ...rows.slice(0,80).map((item,i)=>Button({key:`entry-${i}-${item.id}`,plain:true,onPress:()=>press(item),label:`${item.label.slice(0,36)} · ${compact(total(item.stats))} · ${price(item.stats)}`})),
+          ...(rows.length===0?[Text({dimColor:true,children:state.loading?'Loading entries…':'No matching entries.'})]:[]),
+        ]}),
+        ...(modelSummary?[divider(),modelSummary]:[]),
+      ].filter(Boolean)}),
+      footer,
+    ]});
+
+  });
+}

package/package.json

@@ -1,6 +1,48 @@
-{
-  "name": "claude-usage-explorer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "claude-usage-explorer",
+  "version": "1.0.1",
+  "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"
+  ],
+  "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/scripts/install-command.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Install a stable wrapper, not a symlink: symlinks break dirname-based launchers.
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+mkdir -p "$HOME/.local/bin"
+TARGET="$HOME/.local/bin/claude-usage"
+# Quote the installation directory safely for POSIX sh.
+QUOTED_ROOT=$(printf '%s' "$ROOT" | sed "s/'/'\\''/g")
+printf '#!/bin/sh\nexec '''%s/claude-usage''' "$@"\n' "$QUOTED_ROOT" > "$TARGET"
+chmod +x "$TARGET"
+printf 'Installed: %s -> %s/claude-usage\n' "$TARGET" "$ROOT"
+printf '%s\n' 'Put ~/.local/bin before ~/.asdf/shims in PATH, then run: hash -r'

package/src/core.mjs

@@ -0,0 +1,285 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+
+const day = 86400000;
+export const DEFAULT_RATES = {
+  // USD per million tokens. Indicative defaults, not an authoritative historical price table.
+  'claude-opus-4': [15,75,18.75,1.5],
+  'claude-opus-4-1': [15,75,18.75,1.5],
+  'claude-opus-4-5': [5,25,6.25,0.5],
+  'claude-opus-4-6': [5,25,6.25,0.5],
+  'claude-sonnet-4': [3,15,3.75,0.3],
+  'claude-sonnet-4-5': [3,15,3.75,0.3],
+  'claude-sonnet-4-6': [3,15,3.75,0.3],
+  // Official standard 5-minute-cache API rates (USD / million), checked 2026-11-05.
+  'claude-sonnet-5-5': [2,10,2.5,0.1],
+  'claude-sonnet-5': [2,10,2.5,0.2],
+  'claude-opus-5-5': [4,20,5,0.2],
+  'claude-opus-5': [5,25,6.25,0.5],
+  'claude-haiku-5-5': [0.1,0.5,0.125,0.01],
+  'claude-haiku-4-5': [1,5,1.25,0.1],
+  'claude-3-7-sonnet': [3,15,3.75,0.3],
+  'claude-3-5-sonnet': [3,15,3.75,0.3],
+  'claude-3-5-haiku': [0.8,4,1,0.08],
+};
+const ZERO = () => ({ input:0, output:0, cacheWrite:0, cacheRead:0, requests:0, knownCost:0, unknownCostRequests:0 });
+export function add(a,b) { for (const k of Object.keys(a)) a[k] += b[k] ?? 0; return a; }
+export function totalTokens(a) { return a.input+a.output+a.cacheWrite+a.cacheRead; }
+export function money(n) { return '$'+n.toFixed(4); }
+export function number(n) { return Math.round(n).toLocaleString('en-US'); }
+export function projectRoots(env=process.env,home=os.homedir()) {
+  const roots = [env.CLAUDE_CONFIG_DIR, path.join(home,'.claude')].filter(Boolean).map(x=>path.resolve(x,'projects'));
+  return [...new Set(roots)];
+}
+export function walk(dir, result=[], depth=0) {
+  if(depth>12) return result;
+  let items; try { items=fs.readdirSync(dir,{withFileTypes:true}); } catch { return result; }
+  for(const item of items) {
+    const f=path.join(dir,item.name);
+    if(item.isDirectory()) walk(f,result,depth+1);
+    else if(item.isFile() && item.name.endsWith('.jsonl')) result.push(f);
+  }
+  return result;
+}
+export function readLines(file,onRecord) {
+  // Synchronous bounded-memory line iterator for portability; skips malformed and incomplete lines.
+  const fd=fs.openSync(file,'r'); const buf=Buffer.allocUnsafe(128*1024); let carry=''; let bad=0;
+  const decoder=new TextDecoder('utf-8');
+  try { let n; while((n=fs.readSync(fd,buf,0,buf.length,null))>0) {
+    carry += decoder.decode(buf.subarray(0,n),{stream:true});
+    let pos; while((pos=carry.indexOf('\n'))!==-1) {
+      const line=carry.slice(0,pos);carry=carry.slice(pos+1);
+      if(!line.trim()) continue;
+      try {onRecord(JSON.parse(line));} catch {bad++;}
+    }
+    // A single exceptionally large line is possible; keep it until newline, never truncate silently.
+  }
+  carry+=decoder.decode();
+  if(carry.trim()) {try {onRecord(JSON.parse(carry));} catch {bad++;}}
+  } finally {fs.closeSync(fd);} return bad;
+}
+export function sessionIdentity(file) {
+  const name=path.basename(file,'.jsonl');
+  const segments=file.split(path.sep);
+  const idx=segments.lastIndexOf('subagents');
+  return {id:idx>=0 ? segments[idx-1] : name, agent:idx>=0 ? name.replace(/^agent-/,'') : 'main', isSubagent:idx>=0};
+}
+function metrics(usage) {
+  const u=usage||{};
+  return {input:Number(u.input_tokens)||0,output:Number(u.output_tokens)||0,
+    cacheWrite:Number(u.cache_creation_input_tokens)||0,cacheRead:Number(u.cache_read_input_tokens)||0,
+    cacheWrite5m:Number(u.cache_creation?.ephemeral_5m_input_tokens)||0,cacheWrite1h:Number(u.cache_creation?.ephemeral_1h_input_tokens)||0};
+}
+function normalizeModel(model) {
+  if(!model || typeof model!=='string' || model.startsWith('<')) return null;
+  return model.replace(/-20\d{6}$/, '');
+}
+export function costFor(model,m,rates=DEFAULT_RATES) {
+  const normalized=normalizeModel(model);const rate=normalized && rates[normalized];
+  if(!rate) return null;
+  // Prefer tier-specific cache creation counters when present; fallback to aggregate.
+  const w5=Number(m.cacheWrite5m)||0,w1=Number(m.cacheWrite1h)||0;
+  const writeCost=(w5||w1) ? w5*rate[2]+w1*(rate[4]??rate[2]*1.6) : m.cacheWrite*rate[2];
+  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 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;
+    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') {
+      const c=r.message?.content;
+      const s=typeof c==='string' ? c : Array.isArray(c)? c.filter(x=>x?.type==='text').map(x=>x.text).join(' '):'';
+      const trimmed=s?.replace(/\s+/g,' ').trim();
+      if(trimmed && !trimmed.startsWith('<') && !trimmed.startsWith('[Request interrupted') && !trimmed.startsWith('<command-name>')) title=trimmed.slice(0,110);
+    }
+    if(r.type==='custom-title' && typeof r.customTitle==='string') title=r.customTitle;
+    if(r.type!=='assistant') return;
+    const msg=r.message||{};if(!msg.usage || !msg.id) return;
+    const model=normalizeModel(msg.model);if(!model) return;
+    const m=metrics(msg.usage);
+    const key=String(msg.id);
+    const prev=requests.get(key);
+    // Multiple records for the same message ID are snapshots, not separate requests.
+    // Preserve the highest observed counters, including streaming partial updates.
+    if(prev) {
+      for(const k of ['input','output','cacheWrite','cacheRead','cacheWrite5m','cacheWrite1h']) prev[k]=Math.max(prev[k],m[k]);
+      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()]};
+}
+
+// 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 cacheDir=()=>path.join(os.homedir(),'.claude-usage-explorer','cache-v3');
+function readCachedFile(file){
+  const st=fs.statSync(file);
+  const key=Buffer.from(file).toString('hex');
+  // A filename derived from SHA-256 avoids excessively long paths.
+  const name=hashPath(file)+'.json';
+  const dest=path.join(cacheDir(),name);
+  try {const obj=JSON.parse(fs.readFileSync(dest,'utf8'));
+    if(obj.version===CACHE_VERSION && obj.size===st.size && obj.mtime===st.mtimeMs)return obj.parsed;
+  } catch {}
+  const parsed=parseFile(file);
+  try {fs.mkdirSync(cacheDir(),{recursive:true,mode:0o700});
+    const tmp=dest+'.'+process.pid+'.tmp';
+    fs.writeFileSync(tmp,JSON.stringify({version:CACHE_VERSION,size:st.size,mtime:st.mtimeMs,parsed}),{mode:0o600});
+    fs.renameSync(tmp,dest);
+  }catch{};
+  return parsed;
+}
+function hashPath(s){return createHash('sha256').update(s).digest('hex');}
+
+export function ingest(roots,rates=DEFAULT_RATES) {
+  const files=[...new Set(roots.flatMap(r=>walk(r)))];const sessions=new Map();let malformed=0;
+  for(const file of files) {
+    let parsed;try {parsed=readCachedFile(file);} catch {malformed++;continue;}
+    malformed+=parsed.bad;
+    // Distinct files are attributed by session and agent, not only by filename.
+    const key=parsed.sessionId;
+    let s=sessions.get(key);
+    if(!s) {s={id:key,title:null,cwd:null,start:null,end:null,agents:new Map(),files:[]};sessions.set(key,s);}
+    s.files.push(file);s.title=s.title||parsed.title;s.cwd=s.cwd||parsed.cwd;
+    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);
+  }
+  return {sessions:[...sessions.values()],files:files.length,malformed,roots};
+}
+function zonedBoundary(year,month,dayOfMonth,hour,minute,zone){
+  const last=new Date(Date.UTC(year,month+1,0)).getUTCDate();
+  const target=Date.UTC(year,month,Math.min(dayOfMonth,last),hour,minute);
+  const fmt=new Intl.DateTimeFormat('en-US',{timeZone:zone,year:'numeric',month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',hourCycle:'h23'});
+  let candidate=target;
+  for(let i=0;i<4;i++){
+    const parts=Object.fromEntries(fmt.formatToParts(candidate).filter(p=>p.type!=='literal').map(p=>[p.type,Number(p.value)]));
+    const represented=Date.UTC(parts.year,parts.month-1,parts.day,parts.hour,parts.minute);
+    const diff=target-represented;
+    candidate+=diff;
+    if(!diff)break;
+  }
+  return candidate;
+}
+export function timeWindow(value,now=Date.now(),billingDay=null,billingTimeZone='UTC',billingHour=0,billingMinute=0) {
+  if(!value||value==='all') return [-Infinity,Infinity];
+  const d=new Date(now);const utcStart=Date.UTC(d.getUTCFullYear(),d.getUTCMonth(),d.getUTCDate());
+  if(value==='today')return [utcStart,utcStart+day];
+  if(value==='yesterday')return [utcStart-day,utcStart];
+  if(value==='7d')return [now-7*day,now];
+  if(value==='30d')return [now-30*day,now];
+  if(value==='month')return [Date.UTC(d.getUTCFullYear(),d.getUTCMonth(),1),Date.UTC(d.getUTCFullYear(),d.getUTCMonth()+1,1)];
+  if(value==='previous-month')return [Date.UTC(d.getUTCFullYear(),d.getUTCMonth()-1,1),Date.UTC(d.getUTCFullYear(),d.getUTCMonth(),1)];
+  if(value==='cycle'||value==='previous-cycle') {
+    if(!Number.isInteger(billingDay)||billingDay<1||billingDay>31) throw new Error('Billing cycle requires --billing-day 1..31 (UTC-based approximation)');
+    const zone=billingTimeZone||'UTC';
+    const local=new Intl.DateTimeFormat('en-US',{timeZone:zone,year:'numeric',month:'numeric'}).formatToParts(now);
+    const parts=Object.fromEntries(local.filter(p=>p.type==='year'||p.type==='month').map(p=>[p.type,Number(p.value)]));
+    let y=parts.year,m=parts.month-1;
+    const boundary=(yy,mm)=>zonedBoundary(yy,mm,billingDay,billingHour,billingMinute,zone);
+    let current=boundary(y,m);
+    if(now<current){m--;current=boundary(y,m);}
+    if(value==='cycle')return [current,boundary(y,m+1)];
+    return [boundary(y,m-1),current];
+  }
+  const match=/^(\d{4}-\d\d-\d\d):(\d{4}-\d\d-\d\d)$/.exec(value);
+  if(match){const a=Date.parse(match[1]+'T00:00:00Z'),b=Date.parse(match[2]+'T00:00:00Z');if(!Number.isFinite(a)||!Number.isFinite(b)||a>b)throw new Error('Invalid date range');return [a,b+day];}
+  throw new Error('Invalid --period. Use all,today,yesterday,7d,30d,month,previous-month,cycle,previous-cycle,YYYY-MM-DD:YYYY-MM-DD');
+}
+export function summarize(data,window=[-Infinity,Infinity],rates=DEFAULT_RATES) {
+  const projects=new Map(), sessions=[];const models=new Map();const overall=ZERO();
+  for(const s of data.sessions){
+    const stat=ZERO(),agents=[];
+    for(const a of s.agents.values()){
+      const am=ZERO();const byModel=new Map();
+      for(const r of a.requests){if(r.timestamp===null||r.timestamp<window[0]||r.timestamp>=window[1])continue;
+        const one=ZERO();Object.assign(one,{input:r.input,output:r.output,cacheWrite:r.cacheWrite,cacheRead:r.cacheRead,requests:1});
+        const cost=costFor(r.model,r,rates);if(cost===null)one.unknownCostRequests=1;else one.knownCost=cost;
+        add(am,one);add(overall,one);
+        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(!stat.requests)continue;
+    const project=s.cwd||'(unknown project)';
+    if(!projects.has(project))projects.set(project,{name:project,stats:ZERO(),sessions:0,models:new Map()});
+    const pr=projects.get(project);add(pr.stats,stat);pr.sessions++;
+    for(const a of agents)for(const m of a.models){if(!pr.models.has(m.name))pr.models.set(m.name,ZERO());add(pr.models.get(m.name),m.stats);}
+    const sm=new Map();for(const a of agents)for(const m of a.models){if(!sm.has(m.name))sm.set(m.name,ZERO());add(sm.get(m.name),m.stats);}
+    sessions.push({id:s.id,title:s.title||s.id,project,start:s.start,end:s.end,stats:stat,agents,models:[...sm].map(([name,stats])=>({name,stats}))});
+  }
+  return {overall,projects:[...projects.values()].map(p=>({...p,models:[...p.models].map(([name,stats])=>({name,stats}))})),sessions,models:[...models].map(([name,stats])=>({name,stats})),files:data.files,malformed:data.malformed,roots:data.roots};
+}
+export function selectCurrentProject(report,cwd) {
+  const normalized=p=>path.resolve(p).toLowerCase();
+  const exact=report.projects.filter(p=>p.name!=='(unknown project)' && normalized(p.name)===normalized(cwd));
+  return exact;
+}
+export function selectCurrentSession(report,sessionId) {
+  if(!sessionId) return [];
+  return report.sessions.filter(s=>s.id===sessionId);
+}
+function table(headers,rows){
+  const widths=headers.map((h,i)=>Math.min(62,Math.max(h.length,...rows.map(r=>String(r[i]??'').length))));
+  const line=r=>'| '+r.map((v,i)=>String(v??'').slice(0,widths[i]).padEnd(widths[i])).join(' | ')+' |';
+  console.log(line(headers));console.log('| '+widths.map(w=>'-'.repeat(w)).join(' | ')+' |');
+  for(const r of rows)console.log(line(r));
+  if(!rows.length)console.log('(no matching usage)');
+}
+function formatStats(s){return `${number(totalTokens(s))} tokens | ${number(s.input)} in / ${number(s.output)} out / ${number(s.cacheWrite)} cache-write / ${number(s.cacheRead)} cache-read | ${money(s.knownCost)} estimated${s.unknownCostRequests?' + unknown pricing ('+s.unknownCostRequests+')':''}`;}
+function rank(items){return items.sort((a,b)=>b.stats.knownCost-a.stats.knownCost || totalTokens(b.stats)-totalTokens(a.stats));}
+function show(title,items,limit=25){console.log('\n'+title);for(const [i,x] of rank(items).slice(0,limit).entries())console.log(`${String(i+1).padStart(2)}. ${x.name||x.title} — ${formatStats(x.stats)}`);if(!items.length)console.log('  No matching usage.');}
+export async function main(argv){
+  const command=argv[0]||'overview';const opts={};
+  for(let i=1;i<argv.length;i++){const v=argv[i];if(v.startsWith('--')){const [key,inline]=v.slice(2).split('=',2);opts[key]=inline??(argv[i+1]&&!argv[i+1].startsWith('--')?argv[++i]:true);}}
+  if(['help','--help','-h'].includes(command)){console.log(`Claude Usage Explorer v0.1.0\n\nCommands: overview | projects | sessions | models | high | diagnostics | current-project | current-session\nOptions: --root PATH --period all|today|yesterday|7d|30d|month|previous-month|cycle|previous-cycle|YYYY-MM-DD:YYYY-MM-DD\n         --billing-day 1..31 --limit N --json --rates PATH\n\nExamples:\n  claude-usage overview --period 7d\n  claude-usage sessions --period cycle --billing-day 15\n  claude-usage projects --json`);return;}
+  if(!['overview','projects','sessions','models','high','diagnostics','current-project','current-session'].includes(command))throw new Error('Unknown command: '+command);
+  let rates=DEFAULT_RATES;
+  if(opts.rates){const custom=JSON.parse(fs.readFileSync(path.resolve(opts.rates),'utf8'));rates={...rates,...custom};}
+  const roots=opts.root?[path.resolve(opts.root)]:projectRoots();
+  const data=ingest(roots,rates),window=timeWindow(opts.period||'all',Date.now(),opts['billing-day']?Number(opts['billing-day']):null);
+  const report=summarize(data,window,rates);const limit=Math.max(1,Math.min(500,Number(opts.limit)||25));
+  if(command==='current-project') {
+    const cwd=path.resolve(String(opts.cwd||process.cwd()));
+    const selected=selectCurrentProject(report,cwd);
+    if(opts.json){console.log(JSON.stringify({cwd,projects:selected,sessions:report.sessions.filter(s=>selected.some(p=>p.name===s.project))},null,2));return;}
+    console.log('Current project: '+cwd);
+    table(['Project','Tokens','Input','Output','Cache write','Cache read','Est. USD'],selected.map(p=>[path.basename(p.name),number(totalTokens(p.stats)),number(p.stats.input),number(p.stats.output),number(p.stats.cacheWrite),number(p.stats.cacheRead),money(p.stats.knownCost)]));
+    if(!selected.length)console.log('No usage found for this exact project path. Use --cwd PATH if needed.');
+    else table(['Session','Tokens','Est. USD'],rank(report.sessions.filter(s=>s.project===selected[0].name)).slice(0,limit).map(s=>[s.title,number(totalTokens(s.stats)),money(s.stats.knownCost)]));
+    return;
+  }
+  if(command==='current-session') {
+    const id=String(opts['session-id']||process.env.CLAUDE_SESSION_ID||'');
+    if(!id) {console.log('Current session ID is unavailable. Supply --session-id UUID (do not guess from latest activity).');return;}
+    const selected=selectCurrentSession(report,id);
+    if(opts.json){console.log(JSON.stringify({sessionId:id,sessions:selected},null,2));return;}
+    console.log('Current session: '+id);
+    table(['Session','Tokens','Input','Output','Cache write','Cache read','Est. USD'],selected.map(s=>[s.title,number(totalTokens(s.stats)),number(s.stats.input),number(s.stats.output),number(s.stats.cacheWrite),number(s.stats.cacheRead),money(s.stats.knownCost)]));
+    for(const s of selected){table(['Agent','Tokens','Est. USD'],s.agents.map(a=>[a.id,number(totalTokens(a.stats)),money(a.stats.knownCost)]));}
+    return;
+  }
+  if(opts.json){console.log(JSON.stringify({...report,period:opts.period||'all'},null,2));return;}
+  console.log('Claude Usage Explorer | '+(opts.period||'all')+' | estimated API-equivalent costs (USD)');
+  if(command==='diagnostics'){console.log('Roots:',roots.join(', '));console.log('JSONL files:',data.files,'Malformed records/files:',data.malformed,'Sessions:',data.sessions.length);console.log('All source data is read-only. Unknown models have no price.');return;}
+  if(command==='overview'){console.log('\nTotal: '+formatStats(report.overall));show('Top projects',report.projects,Math.min(10,limit));show('Top models',report.models,Math.min(10,limit));show('Top sessions',report.sessions,Math.min(10,limit));}
+  if(command==='projects')table(['Project','Sessions','Tokens','Est. USD'],rank(report.projects).slice(0,limit).map(p=>[p.name,p.sessions,number(totalTokens(p.stats)),money(p.stats.knownCost)]));
+  if(command==='sessions')table(['Session','Project','Tokens','Est. USD'],rank(report.sessions).slice(0,limit).map(s=>[s.title,path.basename(s.project),number(totalTokens(s.stats)),money(s.stats.knownCost)]));
+  if(command==='models')table(['Model','Requests','Input','Output','Cache write','Cache read','Tokens','Est. USD'],rank(report.models).slice(0,limit).map(m=>[m.name,m.stats.requests,number(m.stats.input),number(m.stats.output),number(m.stats.cacheWrite),number(m.stats.cacheRead),number(totalTokens(m.stats)),money(m.stats.knownCost)]));
+  if(command==='high'){
+    const sorted=rank(report.sessions);show('Highest-consumption sessions',sorted,limit);
+    console.log('\nNote: ranked by known estimated cost, then tokens; statistical percentile classification is planned.');
+  }
+  if(data.malformed)console.log(`\nWarning: ${data.malformed} malformed JSONL records or unreadable files skipped.`);
+  if(report.overall.unknownCostRequests)console.log('Warning: some models lack pricing; cost rankings may be incomplete.');
+}

package/src/launcher.mjs

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {spawn,spawnSync} from 'node:child_process';
+
+const cliPath=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'../bin/claude-usage.mjs');
+const shQuote=s=>`'${String(s).replaceAll("'", "'\\''")}'`;
+const appleQuote=s=>`"${String(s).replaceAll('\\','\\\\').replaceAll('"','\\"')}"`;
+
+/** Opens a real interactive TTY beside Claude; cannot embed a TUI in Claude's tool output. */
+export function launchSidecar({cwd=process.cwd(),platform=process.platform,spawnProcess=spawn,probe=spawnSync}={}){
+ const command=[shQuote(process.execPath),shQuote(cliPath),'tui','--cwd',shQuote(cwd)].join(' ');
+ let program,args;
+ if(platform==='darwin'){
+  program='osascript';args=['-e',`tell application "Terminal" to do script ${appleQuote(command)}`,'-e','tell application "Terminal" to activate'];
+ }else if(platform==='win32'){
+  // Pass arguments as a PowerShell literal array; do not interpolate a shell command.
+  const psQuote=s=>`'${String(s).replaceAll("'","''")}'`;
+  const ps=`Start-Process -FilePath ${psQuote('cmd.exe')} -ArgumentList @('/k', ${psQuote('"'+process.execPath+'" "'+cliPath+'" tui --cwd "'+cwd+'"')})`;
+  program='powershell.exe';args=['-NoProfile','-NonInteractive','-Command',ps];
+ }else{
+  const choices=[['x-terminal-emulator',['-e','sh','-c',command]],['gnome-terminal',['--','sh','-c',command]],['konsole',['-e','sh','-c',command]],['xterm',['-e','sh','-c',command]]];
+  const chosen=choices.find(([name])=>probe('which',[name],{stdio:'ignore'}).status===0);
+  if(!chosen)throw new Error('No supported terminal emulator found. Run `claude-usage tui` in another terminal.');
+  [program,args]=chosen;
+ }
+ const child=spawnProcess(program,args,{detached:true,stdio:'ignore',windowsHide:false});
+ child.on?.('error',err=>console.error('Unable to launch terminal:',err.message));
+ child.unref?.();
+ return {program,args};
+}

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

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+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');
+  const period=periodIndex>=0 ? argv[periodIndex+1] : 'all';
+  const settingsPath=path.join(home,'.claude-usage-explorer','settings.json');
+  let settings={};
+  try {settings=JSON.parse(fs.readFileSync(settingsPath,'utf8'));}catch{}
+  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})};
+}

package/src/statusline.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {ingest,projectRoots,summarize,timeWindow,totalTokens,DEFAULT_RATES} from './core.mjs';
+
+const HOME=()=>path.join(os.homedir(),'.claude-usage-explorer');
+const SUMMARY=()=>path.join(HOME(),'status-summary.json');
+const SETTINGS=()=>path.join(HOME(),'settings.json');
+const MAX_AGE=60_000;
+const readJson=p=>{try{return JSON.parse(fs.readFileSync(p,'utf8'));}catch{return {};}};
+const usd=n=>'$'+Number(n).toFixed(2);
+const compact=n=>new Intl.NumberFormat('en-US',{notation:'compact',maximumFractionDigits:1}).format(n);
+export function formatStatusLine(input,summary={}) {
+  const cost=Number(input?.cost?.total_cost_usd);
+  const session=Number.isFinite(cost)&&cost>=0?usd(cost):'—';
+  const model=input?.model?.display_name||input?.model?.id||'Claude';
+  const cycle=summary.cycle;
+  const cycleText=cycle ? (cycle.unknownCostRequests ? `${usd(cycle.knownCost)}+` : usd(cycle.knownCost)) : '—';
+  const tokens=cycle?compact(totalTokens(cycle)):'—';
+  const status=summary.error?' (history unavailable)':'';
+  return `${model}  │  Session ${session}  │  Cycle ${cycleText} est. · ${tokens} tokens${status}`;
+}
+export function computeSummary(now=Date.now(),settings=readJson(SETTINGS())){
+  if(!Number.isInteger(settings.billingDay)||settings.billingDay<1||settings.billingDay>31) return {error:'Set billing date in TUI (B → Billing)'};
+  const window=timeWindow('cycle',now,settings.billingDay,settings.billingTimeZone||'UTC',settings.billingHour||0,settings.billingMinute||0);
+  const report=summarize(ingest(projectRoots()),window,{...DEFAULT_RATES,...(settings.rates||{})});
+  return {cycle:report.overall,window,computedAt:now};
+}
+function cachedSummary(now=Date.now()){
+  const existing=readJson(SUMMARY());
+  const settings=readJson(SETTINGS());
+  let stat;
+  try{stat=fs.statSync(SETTINGS());}catch{}
+  const settingsMtime=stat?.mtimeMs||0;
+  if(existing.computedAt && now-existing.computedAt<MAX_AGE && existing.settingsMtime===settingsMtime) return existing;
+  let result;
+  try{result=computeSummary(now,settings);}catch(e){result={error:e.message};}
+  result.computedAt=now;result.settingsMtime=settingsMtime;
+  try{fs.mkdirSync(HOME(),{recursive:true,mode:0o700});fs.writeFileSync(SUMMARY(),JSON.stringify(result),{mode:0o600});}catch{}
+  return result;
+}
+export async function runStatusLine(){
+  // Claude Code passes a JSON status payload via stdin. Never log it or store it.
+  let raw='';for await(const chunk of process.stdin){raw+=chunk;if(raw.length>2_000_000)break;}
+  let input={};try{input=JSON.parse(raw);}catch{}
+  process.stdout.write(formatStatusLine(input,cachedSummary())+'\n');
+}
+export function installStatusLine({settingsPath=path.join(os.homedir(),'.claude','settings.json'),force=false,scriptPath=fileURLToPath(new URL('../bin/claude-usage.mjs',import.meta.url))}={}){
+  const settings=readJson(settingsPath);
+  if(settings.statusLine && !force) throw new Error('Claude already has a statusLine configured. To replace it, run statusline-install --force (a backup will be saved).');
+  fs.mkdirSync(path.dirname(settingsPath),{recursive:true});
+  if(fs.existsSync(settingsPath)) fs.copyFileSync(settingsPath,settingsPath+'.claude-usage-backup-'+Date.now());
+  // Node's executable resolved during install may be an asdf shim; prefer the current absolute Node executable.
+  const quote=s=>`"${String(s).replace(/"/g,'\\"')}"`;
+  settings.statusLine={type:'command',command:`${quote(process.execPath)} ${quote(scriptPath)} statusline`,padding:0};
+  fs.writeFileSync(settingsPath,JSON.stringify(settings,null,2)+'\n',{mode:0o600});
+  return settingsPath;
+}

package/src/tui.mjs

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+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()){
+ const base=periods.find(([,id])=>id===period)?.[0]||period;
+ if(!['cycle','previous-cycle'].includes(period))return base;
+ if(!Number.isInteger(settings.billingDay)||settings.billingDay<1||settings.billingDay>31)return base+' · Set renewal date';
+ try{
+  const [start,end]=timeWindow(period,now,settings.billingDay,settings.billingTimeZone||'UTC',settings.billingHour||0,settings.billingMinute||0);
+  const format=new Intl.DateTimeFormat('en-US',{timeZone:settings.billingTimeZone||'UTC',month:'short',day:'numeric',year:'numeric'});
+  return `${base} · ${format.format(start)} – ${format.format(end-1)}`;
+ }catch{return base+' · Invalid billing settings';}
+}
+const fmt=n=>number(n||0);
+const truncate=(s,n)=>{s=String(s??'');return s.length>n?s.slice(0,Math.max(0,n-1))+'…':s;};
+const money=s=>s.unknownCostRequests?`${s.knownCost?'$'+s.knownCost.toFixed(2)+' + ':''}N/A`:`$${s.knownCost.toFixed(2)}`;
+const settingFile=()=>path.join(os.homedir(),'.claude-usage-explorer','settings.json');
+function readSettings(){try{return JSON.parse(fs.readFileSync(settingFile(),'utf8'));}catch{return {};}}
+function saveSettings(s){fs.mkdirSync(path.dirname(settingFile()),{recursive:true,mode:0o700});fs.writeFileSync(settingFile(),JSON.stringify(s,null,2),{mode:0o600});}
+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}={}){
+ 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());}}
+ refresh();
+ 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==='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}];
+  if(view==='sort')list=sortColumns.map(([value,label])=>({value,label,stats:empty}));
+  if(filter&&!['periods','settings','sort'].includes(view))list=list.filter(x=>x.label.toLowerCase().includes(filter.toLowerCase()));
+  if(!['periods','settings','sort'].includes(view))list.sort((a,b)=>{const av=value(a,sort),bv=value(b,sort);if(av===null&&bv!==null)return 1;if(bv===null&&av!==null)return -1;let v=typeof av==='string'?av.localeCompare(bv):av-bv;return descending?-v:v;});
+  return list;
+ }
+ function nav(next){stack.push({view,selection,offset,project,session,agent,filter});view=next;selection=0;offset=0;filter='';}
+ function restore(){if(!stack.length){switchView('projects');return;}const p=stack.pop();view=p.view;selection=p.selection;offset=p.offset;project=p.project;session=p.session;agent=p.agent;filter=p.filter;}
+ function switchView(next){view=next;selection=0;offset=0;stack=[];filter='';project=null;session=null;agent=null;}
+ function open(){const x=rows()[selection];if(!x)return null;
+  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==='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`;
+  return null;
+ }
+ function rescan(roots,{automatic=false}={}){
+  const selectedProject=project?.name,selectedSession=session?.id,selectedAgent=agent?.id;
+  const selectedRow=rows()[selection];const selectedId=selectedRow?.id??selectedRow?.name??selectedRow?.value;
+  sourceData=ingest(roots);refresh();
+  project=report.projects.find(p=>p.name===selectedProject)||null;
+  session=report.sessions.find(s=>s.id===selectedSession&&(!project||s.project===project.name))||null;
+  agent=session?.agents.find(a=>a.id===selectedAgent)||null;
+  if(view==='sessions'&&!project)view='projects';
+  if(view==='agents'&&!session)view=project?'sessions':'projects';
+  if(view==='models'&&!agent&&!session&&!project){/* all-model scope is valid */}
+  const updatedRows=rows();const index=updatedRows.findIndex(r=>(r.id??r.name??r.value)===selectedId);
+  selection=index>=0?index:Math.min(selection,Math.max(0,updatedRows.length-1));
+  liveState.lastUpdated=Date.now();liveState.error=null;
+  if(!automatic)message='History refreshed.';
+ }
+ 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 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;
+  const line=(str='')=>out.push(clipAnsi(str,Math.max(1,width-1)));
+  const rule=()=>line(c('─'.repeat(width),'90'));
+  const out=[];
+  const pad=(str,n,align='left')=>{str=truncate(str,n);return align==='right'?str.padStart(n):str.padEnd(n);};
+  const title=['PROJECTS','SESSIONS','AGENTS','MODELS','DATES','SETTINGS','SORT'][['projects','sessions','agents','models','periods','settings','sort'].indexOf(view)]||view.toUpperCase();
+  line(c('  ◈ CLAUDE USAGE EXPLORER','1;36')+c(`     ${title}     LOCAL • NO AI CALLS`,'90'));
+  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')}`);
+  rule();
+  const available=rows();selection=Math.max(0,Math.min(selection,Math.max(0,available.length-1)));
+  const selected=available[selection];
+  const breakdown=view==='models'?null:selected?.models|| (view==='projects'?report.models:view==='sessions'?project?.models:view==='agents'?session?.models:agent?.models);
+  // 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 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));
+  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'));
+  }
+  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(' ');
+    }
+    line(active?c(truncate(text,width),'7'):truncate(text,width));
+  }
+  if(!available.length)line(c('  No matching records. Press / to clear your search.','33'));
+  // Fill the table viewport so the model panel and help never move.
+  const renderedRows=Math.min(available.length-offset,visible);
+  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'));
+  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];
+    line(m?`  ${pad(m.name,30)} ${pad(fmt(totalTokens(m.stats)),16,'right')} tokens   ${pad(money(m.stats),14,'right')}`:'');
+  }
+  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('  '+(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;}};
+}
+// Clip colored output to the terminal viewport to prevent line wrapping and scroll flashes.
+export function clipAnsi(value, maxWidth) {
+ const tokens=String(value).match(/\x1b\[[0-9;]*m|[^\x1b]+/g)||[];
+ let output='', count=0, styled=false;
+ for(const token of tokens){
+  if(token.startsWith('\x1b[')){output+=token;styled=token!=='\x1b[0m';continue;}
+  for(const char of token){
+   const size=char.codePointAt(0)>0xffff?2:1;
+   if(count+size>maxWidth){if(styled)output+='\x1b[0m';return output;}
+   output+=char;count+=size;
+  }
+ }
+ return output;
+}
+// Update only changed terminal rows. Never clear the entire screen for navigation.
+export function screenDiff(previous, next, {force=false}={}) {
+ const old=previous===null?[]:previous.split('\n');
+ const current=next.split('\n');
+ let output='';
+ for(let i=0;i<Math.max(old.length,current.length);i++){
+  if(!force && old[i]===current[i])continue;
+  output+=`\x1b[${i+1};1H\x1b[2K${current[i]??''}`;
+ }
+ return output;
+}
+export async function launchTui(argv=[]){
+ if(!process.stdin.isTTY||!process.stdout.isTTY)throw new Error('Requires an interactive terminal (TTY). Run claude-usage tui in a terminal.');
+ const i=argv.indexOf('--root');const roots=i>=0&&argv[i+1]?[path.resolve(argv[i+1])]:projectRoots();const ci=argv.indexOf('--cwd');const cwd=ci>=0&&argv[ci+1]?path.resolve(argv[ci+1]):process.cwd();const explorer=createExplorer(ingest(roots),{cwd});
+ readline.emitKeypressEvents(process.stdin);process.stdin.setRawMode(true);process.stdin.resume();process.stdout.write('\x1b[?1049h\x1b[?25l');
+ let previousFrame=null;
+ const draw=()=>{const frame=explorer.render();const changes=screenDiff(previousFrame,frame);if(changes)process.stdout.write(changes);previousFrame=frame;};
+ let lastDimensions='';
+ const resize=()=>{const dimensions=`${process.stdout.columns}x${process.stdout.rows}`;if(dimensions===lastDimensions)return;lastDimensions=dimensions;previousFrame=null;process.stdout.write('\x1b[H\x1b[J');draw();};
+ const close=()=>{clearInterval(liveTimer);process.stdin.off('keypress',onKey);process.stdout.off('resize',resize);process.stdin.setRawMode(false);process.stdin.pause();process.stdout.write('\x1b[?25h\x1b[?1049l');};
+ let prompting=false,checking=false;
+ // Cheap metadata scans; only reparse transcripts when their size/mtime changes.
+ let lastSignature=historySignature(roots);
+ const liveTimer=setInterval(()=>{
+  if(!explorer.liveState.enabled||prompting||checking)return;
+  checking=true;
+  try{
+   const next=historySignature(roots);
+   if(next!==lastSignature){explorer.rescan(roots,{automatic:true});lastSignature=next;}
+   explorer.refreshPlan();draw();
+   explorer.setLiveState({lastCheck:Date.now()});
+  }catch(e){explorer.setLiveState({error:e.message});draw();}
+  finally{checking=false;}
+ },5000);
+ liveTimer.unref();
+ async function ask(q){prompting=true;process.stdin.setRawMode(false);previousFrame=null;process.stdout.write('\x1b[?25h\x1b[H\x1b[2J'+q+'\n> ');const rl=readline.createInterface({input:process.stdin,output:process.stdout,terminal:true});return new Promise(resolve=>rl.question('',a=>{rl.close();process.stdin.resume();process.stdin.setRawMode(true);prompting=false;process.stdout.write('\x1b[?25l');resolve(a);}));}
+ async function onKey(str,key={}){
+  if(prompting)return;if((key.ctrl&&key.name==='c')||str==='q'){close();return;}
+  const len=explorer.rows().length;
+  if(key.name==='up'||str==='k')explorer.selection=Math.max(0,explorer.selection-1);
+  else if(key.name==='down'||str==='j')explorer.selection=Math.min(len-1,explorer.selection+1);
+  else if(key.name==='pageup')explorer.selection=Math.max(0,explorer.selection-10);
+  else if(key.name==='pagedown')explorer.selection=Math.min(len-1,explorer.selection+10);
+  else if(key.name==='return'){
+   const action=explorer.open();
+   if(action==='custom'){const s=(await ask('Custom inclusive dates YYYY-MM-DD:YYYY-MM-DD (Enter to cancel):')).trim();if(s){try{timeWindow(s);explorer.setPeriod(s);}catch(e){explorer.message=e.message;}}}
+   if(action==='rescan')explorer.rescan(roots);
+   if(action==='billing'||action?.startsWith('billing-required:')){
+    const n=Number(await ask('Billing renewal day of month (1–31):'));
+    const zone=(await ask('IANA timezone (e.g. Europe/Athens, Europe/Amsterdam, UTC):')).trim()||'UTC';
+    const time=(await ask('Renewal time HH:MM (24h, default 00:00):')).trim()||'00:00';
+    const match=/^([01]\d|2[0-3]):([0-5]\d)$/.exec(time);
+    let validZone=true;try{new Intl.DateTimeFormat('en-US',{timeZone:zone});}catch{validZone=false;}
+    if(Number.isInteger(n)&&n>=1&&n<=31&&match&&validZone){explorer.setBillingDay(n,zone,Number(match[1]),Number(match[2]));if(action?.startsWith('billing-required:'))explorer.setPeriod(action.split(':')[1]);}
+    else explorer.message='Invalid billing day, timezone, or time; nothing saved.';
+   }
+   if(action==='rates'){
+    const model=await ask('Exact model ID (e.g. claude-sonnet-5-5):');
+    const raw=await ask('Verified USD per 1M tokens: input,output,cache-write,cache-read (comma separated):');
+    const nums=raw.split(',').map(x=>Number(x.trim()));
+    if(model.trim()&&nums.length===4&&nums.every(n=>Number.isFinite(n)&&n>=0))explorer.setModelRate(model.trim(),nums);else explorer.message='Invalid rates; no changes saved.';
+   }
+  }
+  else if(key.name==='backspace'||key.name==='escape')explorer.restore();
+  else if(str==='1')explorer.switchView('projects');
+  else if(str==='2')explorer.switchView('sessions');
+  else if(str==='3')explorer.switchView('models');
+  else if(str==='m'){explorer.nav('models');}
+  else if(str==='d')explorer.nav('periods');
+  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'){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.');}
+  draw();
+ }
+ process.stdin.on('keypress',onKey);process.stdout.on('resize',resize);resize();
+}
+
+// Scan only metadata on a 5-second interval. The ingestion cache handles unchanged JSONL.
+export function historySignature(roots){
+ const entries=[];
+ for(const root of roots){
+  const pending=[root];
+  while(pending.length){
+   const dir=pending.pop();let children;
+   try{children=fs.readdirSync(dir,{withFileTypes:true});}catch{continue;}
+   for(const child of children){
+    const file=path.join(dir,child.name);
+    if(child.isDirectory())pending.push(file);
+    else if(child.isFile()&&child.name.endsWith('.jsonl')){
+     try{const stat=fs.statSync(file);entries.push(`${file}:${stat.size}:${stat.mtimeMs}`);}catch{}
+    }
+   }
+  }
+ }
+ entries.sort();return entries.join('\n');
+}