claude-usage-explorer 1.0.1 → 1.1.5

package/.claude-plugin/marketplace.json

@@ -1,30 +1,5 @@
-{
-  "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"
-      ]
-    }
-  ]
-}
+{
+  "name": "claude-usage-explorer-marketplace",
+  "owner": {"name": "Claude Usage Explorer contributors"},
+  "plugins": [{"name": "claude-usage", "source": "./", "description": "Local Claude Code usage explorer"}]
+}

package/.claude-plugin/plugin.json

@@ -1,11 +1,5 @@
-{
-  "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"
-}
+{
+  "name": "claude-usage",
+  "description": "Interactive native Claude Code usage sidebar and standalone TUI",
+  "version": "1.0.11"
+}

package/README.md

@@ -1,116 +1,125 @@
-# 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.
+# 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" "$@"