claude-usage-explorer 1.0.0 → 1.1.5

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-usage",
   "description": "Interactive native Claude Code usage sidebar and standalone TUI",
-  "version": "1.0.0"
+  "version": "1.0.11"
 }

package/README.md

@@ -1,84 +1,125 @@
-# Claude Usage Explorer
-
-A local, read-only usage explorer for Claude Code. Browse projects, sessions, agents and models, inspect token usage and estimated API-equivalent costs, and optionally view cached Claude Desktop plan-limit percentages. No external npm dependencies or telemetry.
-
-> **Release candidate:** v1.0.0. The standalone terminal UI is automated-test verified. Native Claude Code mod integration and the external-terminal launcher require final host verification before a stable release.
-
-## Requirements
-
-- Node.js 20+ (Node 22 recommended)
-- Claude Code with native Mods support for the sidebar
-- Local Claude Code JSONL transcript history
-
-## Install the standalone CLI (npm)
-
-Once this package is published on npm, install it globally with Node.js 20+:
-
-```sh
-npm install -g claude-usage-explorer
-claude-usage tui
-```
-
-Or run it without a global installation:
-
-```sh
-npx --yes --package claude-usage-explorer claude-usage tui
-```
-
-**Note:** These commands will work only after the package is published to the npm registry. The GitHub repository alone does not publish an npm package. 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.
-
-## Run the native Claude Code sidebar
-
-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 and security
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). Licensed under [MIT](LICENSE).
-
-## Support
-
-If this project is useful, you can star the repository. GitHub Sponsors may be enabled later; no donation or payment service is required to use the project.
+# Claude Usage Explorer v1.0.4
+
+Local, read-only analytics for Claude Code sessions. No external npm dependencies and no tmux requirement.
+
+## Requirements
+
+- 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.
+
+## Install and run
+
+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.
+
+**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.
+
+## Native 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.
+
+## Standalone TUI
+
+`./claude-usage tui`
+
+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.
+
+## Notes and limitations
+
+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.
+
+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.
+
+## Validation
+
+Run `npm test` and `npm run check`. For native mod validation on a machine with Claude Code installed: `claude plugin validate .`.
+
+## v1.0.4 sidebar fix
+
+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).
+
+## Fixing old asdf commands and terminal flashes (v1.0.4)
+
+The installer now creates a small executable wrapper instead of a symlink. This avoids resolving `bin/claude-usage.mjs` relative to `~/.local/bin`.
+
+```sh
+./scripts/install-command.sh
+export PATH="$HOME/.local/bin:$PATH"
+hash -r
+type -a claude-usage
+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.
+
+## Sidebar controls (v1.0.4)
+
+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.
+
+### Native sidebar keyboard and exit (v1.0.6)
+
+- **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.
+
+### Install both native sidebar and standalone CLI (v1.0.7)
+
+Extract the release archive into `~/claude-usage-explorer-1.0.7`, then:
+
+```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
+```
+
+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.
+
+### v1.0.8 display updates
+
+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.
+
+### Experimental official usage diagnostic (v1.0.9)
+
+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.
+
+### Official account usage (v1.0.10)
+
+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.
+
+### Usage response schema diagnostic (v1.0.11)
+
+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.
+
+## v1.1.0 changes
+
+- 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.
+
+## 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.
+
+### Native session actions (v1.1.2)
+
+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.
+
+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.

package/bin/claude-usage.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 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; });
+(process.argv[2] === 'preference' ? Promise.resolve().then(()=>{const file=path.join(os.homedir(),'.claude-usage-explorer','settings.json');let obj={};try{obj=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}if(process.argv[3]==='period' && ['all','cycle','previous-cycle','today','yesterday','7d','30d','month','previous-month'].includes(process.argv[4])){obj.lastPeriod=process.argv[4];fs.mkdirSync(path.dirname(file),{recursive:true,mode:0o700});fs.writeFileSync(file,JSON.stringify(obj,null,2)+'\n',{mode:0o600});}else throw Error('Invalid preference');}) : 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/claude-usage

@@ -0,0 +1,20 @@
+#!/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/hooks/usage-explorer.mjs

@@ -1,23 +1,24 @@
 // 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 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};
+let limitState={status:'not checked',source:'',rateLimits:[],details:[],checkedAt:0};
+let limitInFlight=null;
+let usageFieldSchema=[];
+
+let officialSpend=null;
+let sessionActionStatus='';
+let focusedSessionId=null;
+const LIMIT_REFRESH_MS=180000;
 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 share=(part,whole)=>whole>0?(part>0&&100*part/whole<0.05?'<0.1%':`${(100*part/whole).toFixed(1)}%`):'—';
 const price=s=>s?.unknownCostRequests?'N/A':`$${(s?.knownCost||0).toFixed(2)}`;
 const name=p=>String(p||'').replace(/\\/g,'/').split('/').filter(Boolean).pop()||p;
+export const agentLabel=a=>a?.id==='main'?'Agent (main)':(a?.name||a?.type||'Subagent');
 const change=($,patch)=>{state={...state,...patch};void $.ui.invalidate('ui.render');};
 export function itemsFor(s=state){
   const r=s.report;
@@ -25,7 +26,7 @@ export function itemsFor(s=state){
   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==='agents'){const current=r.sessions.find(x=>x.id===s.session?.id)||s.session;items=(current?.agents||[]).map(x=>({id:x.id,label:agentLabel(x),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));
@@ -50,23 +51,153 @@ export function back(s){
   const last=s.stack[s.stack.length-1];
   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{}
+}
 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 script=decodeURIComponent(new URL('../bin/claude-usage.mjs',import.meta.url).pathname);
       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);
+      if(!state.preferencesLoaded){state.period=snap.savedPeriod||state.period;state.preferencesLoaded=true;if(state.period!==snap.period){inFlight=null;return refresh($);}}
       // 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:''});
+      change($,{report:snap.report,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($);}
+// Opt-in diagnostic: never store or display the raw response, credentials or identifiers.
+// The first-party OAuth usage route is undocumented; a failure is not fatal.
+export function summarizeLimits(payload){
+  if(!payload||typeof payload!=='object')return [];
+  const lines=[];
+  for(const [key,val] of Object.entries(payload)){
+    if(!/^(five_hour|seven_day|seven_day_[a-z_]+|extra_usage|monthly|billing|usage|rate_limits)$/i.test(key))continue;
+    if(val&&typeof val==='object'&&!Array.isArray(val)){
+      const fields=[];
+      for(const field of ['utilization','percentUsed','limit','used','remaining','resets_at','resetsAt','is_enabled']){
+        const v=val[field];
+        if(typeof v==='number'&&Number.isFinite(v))fields.push(`${field}: ${v}`);
+        else if(typeof v==='boolean')fields.push(`${field}: ${v}`);
+        else if((field==='resets_at'||field==='resetsAt')&&typeof v==='string'&&/^\d{4}-\d{2}-\d{2}/.test(v))fields.push(`${field}: ${v.slice(0,25)}`);
+      }
+      if(fields.length)lines.push(`${key}: ${fields.join(' · ')}`);
+    }
+  }
+  return lines.slice(0,12);
+}
+// Diagnostic exposes only structural metadata, never values, identifiers or credentials.
+export function usageSchema(payload){
+  if(!payload||typeof payload!=='object'||Array.isArray(payload))return [];
+  const rows=[];
+  const walk=(obj,prefix,depth)=>{
+    for(const [key,value] of Object.entries(obj)){
+      if(rows.length>=90)return;
+      // Only keys with conventional field-name syntax; avoid leaking arbitrary map keys.
+      if(!/^[a-zA-Z][a-zA-Z0-9_]{0,49}$/.test(key))continue;
+      const path=prefix?`${prefix}.${key}`:key;
+      const type=value===null?'null':Array.isArray(value)?'array':typeof value;
+      rows.push(`${path}: ${type}`);
+      if(depth<2&&type==='object')walk(value,path,depth+1);
+    }
+  };
+  walk(payload,'',0);
+  return rows;
+}
+// Normalize money using currency minor units. Never add spend and extra_usage together.
+export function parseOfficialSpend(payload){
+  const spend=payload?.spend;
+  const money=(obj)=>{
+    if(!obj||!Number.isFinite(obj.amount_minor)||!Number.isInteger(obj.exponent)||obj.exponent<0||obj.exponent>8||typeof obj.currency!=='string')return null;
+    return {amount:obj.amount_minor/10**obj.exponent,currency:obj.currency.toUpperCase()};
+  };
+  const used=money(spend?.used),limit=money(spend?.limit);
+  if(used&&limit&&used.currency===limit.currency&&limit.amount>0){
+    return {used:used.amount,limit:limit.amount,currency:used.currency,percent:Number.isFinite(spend?.percent)?spend.percent:100*used.amount/limit.amount,source:'spend'};
+  }
+  const extra=payload?.extra_usage;
+  if(extra&&Number.isFinite(extra.used_credits)&&Number.isFinite(extra.monthly_limit)&&extra.monthly_limit>0&&typeof extra.currency==='string'){
+    return {used:extra.used_credits,limit:extra.monthly_limit,currency:extra.currency.toUpperCase(),percent:Number.isFinite(extra.utilization)?extra.utilization:100*extra.used_credits/extra.monthly_limit,source:'extra_usage'};
+  }
+  return null;
+}
+const currencyAmount=(amount,currency)=>{try{return new Intl.NumberFormat('en-US',{style:'currency',currency}).format(amount);}catch{return `${amount.toFixed(2)} ${currency}`;}};
+async function checkLimits($,{force=false}={}){
+  if(limitInFlight)return limitInFlight;
+  if(!force&&limitState.checkedAt&&Date.now()-limitState.checkedAt<LIMIT_REFRESH_MS)return;
+  limitState={...limitState,status:'checking'};void $.ui.invalidate('ui.render');
+  limitInFlight=(async()=>{try{
+    const usage=await $.session.usage();
+    const rateLimits=Array.isArray(usage?.rateLimits)?usage.rateLimits:[];
+    limitState={status:rateLimits.length?'available':'no rate limits returned',source:'session.usage',rateLimits:rateLimits.map(x=>({kind:String(x.kind||'limit').slice(0,40),percentUsed:Number(x.percentUsed)||0,resetsAt:typeof x.resetsAt==='string'?x.resetsAt.slice(0,25):''})),details:[]};
+    const authorization=await $.session.authorize();
+    if(!authorization?.handle){limitState.status='No first-party authorization handle';return;}
+    const response=await $.http.fetch('https://api.anthropic.com/api/oauth/usage',{auth:authorization.handle});
+    if(!response.ok){limitState.status=`HTTP ${response.status}`;return;}
+    const payload=JSON.parse(response.text);
+    officialSpend=parseOfficialSpend(payload);
+    const details=summarizeLimits(payload);
+    limitState={...limitState,status:details.length?'available':'No recognized fields (Enterprise may differ)',source:'Claude session + OAuth usage',details};
+  }catch(err){limitState={...limitState,status:`Unavailable: ${String(err?.message||err).slice(0,100)}`};}
+  finally{limitState.checkedAt=Date.now();void $.ui.invalidate('ui.render');}
+  })().finally(()=>{limitInFlight=null});
+  return limitInFlight;
+}
+export function usageBar(percent,width=24){
+  const value=Math.max(0,Math.min(100,Number.isFinite(percent)?percent:0));
+  const count=Math.round(value/100*width);
+  return `${'█'.repeat(count)}${'░'.repeat(width-count)}  ${value.toFixed(1)}%`;
+}
+export function officialLimitRows(limits){
+  const rows=[];
+  for(const limit of limits.rateLimits||[]){
+    if(Number.isFinite(limit.percentUsed))rows.push({label:limit.kind,percent:limit.percentUsed,resetsAt:limit.resetsAt||''});
+  }
+  for(const line of limits.details||[]){
+    const match=/^([^:]+):.*?utilization: ([0-9]+(?:\.[0-9]+)?)/.exec(line);
+    if(match){
+      const resets=/resets_(?:at|At): ([^·]+)/.exec(line);
+      rows.push({label:match[1],percent:Number(match[2]),resetsAt:resets?.[1]?.trim()||''});
+    }
+  }
+  return rows;
+}
+// Session resume opens a separate terminal; no supported in-place Mods session switch is assumed.
+export function sessionResumeCommand(session){
+  if(!session?.id||!/^[a-f0-9-]{36}$/i.test(session.id))throw new Error('Invalid session ID');
+  if(!session.project||typeof session.project!=='string'||!session.project.startsWith('/'))throw new Error('Original project directory unavailable');
+  const quote=value=>"'"+String(value).replaceAll("'","'\\''")+"'";
+  return `cd ${quote(session.project)} && claude --resume ${quote(session.id)}`;
+}
+export function selectedSessionForAction(s,focusedId){
+  if(s.view==='sessions')return s.report?.sessions?.find(x=>x.id===focusedId&&(!s.project||x.project===s.project))||null;
+  return s.report?.sessions?.find(x=>x.id===s.session?.id)||s.session||null;
+}
+async function sessionAction($,mode){
+  const selected=selectedSessionForAction(state,focusedSessionId);
+  try{
+    if(!selected)throw new Error('Select a session first');
+    if(mode==='copy'){
+      const result=await $.process.run(['osascript','-e',`set the clipboard to ${JSON.stringify(selected.id)}`],{timeoutMs:5000});
+      if(result.exitCode!==0)throw new Error('Clipboard unavailable');
+      sessionActionStatus='Session ID copied';
+    }else{
+      const command=sessionResumeCommand(selected);
+      // osascript argument is encoded as an AppleScript string, never shell-interpolated.
+      const script=`tell application "Terminal" to do script ${JSON.stringify(command)}`;
+      const result=await $.process.run(['osascript','-e',script],{timeoutMs:10000});
+      if(result.exitCode!==0)throw new Error((result.stderr||'Unable to open Terminal').slice(0,120));
+      sessionActionStatus='Opened session in Terminal.app';
+    }
+  }catch(error){sessionActionStatus=String(error?.message||error).slice(0,140);}
+  void $.ui.invalidate('ui.render');
+}
+async function show($){await $.ui.open({id:PANE,title:'Claude Usage Explorer',focus:true,closeOnEscape:true});void refresh($);void checkLimits($);}
 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});
@@ -77,7 +208,7 @@ export function register(on){
     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($));
+    timer?.cancel();timer=$.clock.every(5000,()=>{void refresh($);void checkLimits($);});
     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);});
@@ -86,71 +217,77 @@ export function register(on){
     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 press=item=>{sessionActionStatus='';if(state.view==='sessions')focusedSessionId=item.id;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 periodButtons=PERIODS.map(([label,id])=>Button({key:`period-${id}`,plain:true,label:id===state.period?`● ${label}`:`  ${label}`,onPress:()=>{change($,{period:id,periodMenu:false});void persistPeriod($,id);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 path=[state.project&&name(state.project),state.session?.title,state.agent?agentLabel(state.agent):null].filter(Boolean);
     const breadcrumb=`${state.view.toUpperCase()}${path.length?'  /  '+path.join(' / '):''}`;
-    const stats=state.report?.overall;
-    const plan=state.planUsage;
+    const stats=state.view==='projects'?state.report?.overall:state.view==='sessions'?state.report?.projects?.find(x=>x.name===state.project)?.stats:state.view==='agents'?state.session?.stats:state.view==='models'?(state.agent?.stats||state.session?.stats||state.report?.projects?.find(x=>x.name===state.project)?.stats||state.report?.overall):state.report?.overall;
+    const scopeTotal=state.view==='projects'?total(stats):state.view==='sessions'?total(state.report?.projects?.find(x=>x.name===state.project)?.stats):state.view==='agents'?total(state.session?.stats):state.view==='models'?total(state.agent?.stats||state.session?.stats||state.report?.projects?.find(x=>x.name===state.project)?.stats||stats):total(stats);
     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)`})]:[]),
+      Text({bold:true,children:'MODEL USAGE'}),
+      ...scopeModels.slice(0,4).map((model,i)=>Text({key:`model-summary-${i}`,dimColor:true,wrap:'truncate-end',children:`${model.name}  ·  ${compact(total(model.stats))} tokens  ·  ${price(model.stats)} · ${share(total(model.stats),scopeTotal)}`})),
+      ...(scopeModels.length>4?[Text({dimColor:true,children:`+${scopeModels.length-4} more · Select Models to view all`})]:[]),
     ]}):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 header=Box({flexDirection:'column',children:[
+      Box({flexDirection:'row',gap:2,children:[Text({bold:true,children:'USAGE EXPLORER'}),Text({dimColor:true,children:state.loading?'⟳ Updating':'● Live · 5s'})]}),
+      Text({dimColor:true,wrap:'truncate-end',children:state.periodLabel}),
+      stats?Text({bold:true,children:`${compact(total(stats))} tokens   ${price(stats)} estimated API cost`}):Text({dimColor:true,children:'Loading local usage…'}),
+      stats?Text({dimColor:true,children:`${stats.requests} requests · ${state.report.files} transcript files`}):null,
+      Text({bold:true,children:'OFFICIAL ACCOUNT USAGE'}),
+      ...(officialSpend?[
+        Text({key:'official-spend-heading',bold:true,children:`${currencyAmount(officialSpend.used,officialSpend.currency)} / ${currencyAmount(officialSpend.limit,officialSpend.currency)} · ${officialSpend.percent.toFixed(1)}%`}),
+        Text({key:'official-spend-bar',children:usageBar(officialSpend.percent,30)}),
+        Text({key:'official-spend-left',dimColor:true,children:`${currencyAmount(Math.max(0,officialSpend.limit-officialSpend.used),officialSpend.currency)} remaining · official ${officialSpend.source}`}),
+      ]:[]),
+      ...officialLimitRows(limitState).filter(l=>!(officialSpend&&l.label==='extra_usage')).flatMap((l,i)=>[
+        Text({key:`limit-name-${i}`,dimColor:true,children:`${l.label.replaceAll('_',' ')}${l.resetsAt?' · resets '+l.resetsAt:''}`}),
+        Text({key:`limit-bar-${i}`,children:usageBar(l.percent)}),
+      ]),
+      ...(officialLimitRows(limitState).length===0?[Text({dimColor:true,children:`${limitState.status} · No supported limit values`})]:[]),
+      Text({dimColor:true,children:'Official account spend and local API-equivalent estimates are separate.'}),
+      Button({key:'check-official-limits',plain:true,label:'↻ Refresh official usage',onPress:()=>void checkLimits($,{force:true})}),
+    ].filter(Boolean)});
     const footer=Box({flexDirection:'column',flexShrink:0,children:[
-      divider(),
-      Box({flexDirection:'row',gap:1,flexWrap:'wrap',children:[
+      Text({dimColor:true,children:'────────────────────────────────────────'}),
+      Box({flexDirection:'row',gap:2,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'})),
+        ...(state.session?[
+          action('Open session','o',()=>void sessionAction($,'open')),
+          action('Copy ID','c',()=>void sessionAction($,'copy')),
+        ]:[]),
         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'}),
+      Text({dimColor:true,children:'Esc: close · H: back · O: open current session · C: copy ID · X: exit'}),
     ]});
-    return Box({flexDirection:'column',paddingX:1,flexGrow:1,minHeight:0,height:paneHeight,justifyContent:'space-between',children:[
+    return Box({flexDirection:'column',paddingX:1,flexGrow:1,minHeight:0,height:'100%',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]:[]),
+      header,
+      Text({dimColor:true,children:'────────────────────────────────────────'}),
+      Text({bold:true,wrap:'truncate-end',children:breadcrumb}),
+      Input({key:'usage-filter',placeholder:'Filter entries…',value:state.query,onInput:v=>change($,{query:v}),onSubmit:v=>change($,{query:typeof v==='string'?v:state.query})}),
+      ...(state.periodMenu?[
+        Text({bold:true,children:'SELECT PERIOD'}),
+        Box({flexDirection:'column',gap:0,children:periodButtons}),
+        Text({dimColor:true,children:'────────────────────────────────────────'}),
+      ]:[]),
+      ...(state.error?[Text({color:'red',wrap:'wrap',children:state.error})]:[]),
+      ...(state.view==='models'?[action('← Back to previous view','h',()=>change($,back(state)))]:[]),
+      ...(state.session?[Text({dimColor:true,children:`Session ID: ${state.session.id}`})]:[]),
+      ...(state.agent&&state.agent.id!=='main'?[Text({dimColor:true,children:`Agent ID: ${state.agent.id}`})]:[]),
+      ...(sessionActionStatus?[Text({dimColor:true,children:sessionActionStatus})]:[]),
+      ...(modelSummary?[modelSummary]:[]),
+      Box({flexDirection:'column',flexGrow:1,minHeight:0,children:[
+        ...rows.slice(0,80).map((item,i)=>Button({key:`entry-${i}-${item.id}`,plain:true,onFocus:()=>{if(state.view==='sessions')focusedSessionId=item.id;},onPress:()=>press(item),label:`${item.label.slice(0,40)}  ·  ${compact(total(item.stats))}  ·  ${price(item.stats)} · ${share(total(item.stats),scopeTotal)}`})),
+        ...(rows.length===0?[Text({dimColor:true,children:state.loading?'Loading entries…':'No matching entries.'})]:[]),
+      ]}),
       ].filter(Boolean)}),
       footer,
     ]});