ai-usage-analyzer 0.2.0 → 0.2.1

package/README.md

@@ -17,60 +17,13 @@ TUI analyzer for local AI coding agent token consumption. Auto-detects
 
 Requires **Node.js ≥ 22.5** (for built-in `node:sqlite`).
 
-Pick whichever fits your workflow:
-
-### Option 1: `npx` from GitHub (zero install, fastest to try)
-
 ```bash
+# Try it (no install)
 npx -y github:adetxt/ai-usage-analyzer
-# or with a specific ref
-npx -y github:adetxt/ai-usage-analyzer#v0.1.0
-```
-
-No clone, no `node_modules`, no global install. npx downloads the repo
-on first run and caches it. Subsequent runs are instant.
 
-### Option 2: Clone + install (best for development / contribution)
-
-```bash
-git clone https://github.com/adetxt/ai-usage-analyzer.git
-cd ai-usage-analyzer
-pnpm install
-pnpm link --global   # exposes the `ai-usage` command globally
-```
-
-> Uses `pnpm` (declared in the `packageManager` field). `pnpm-lock.yaml`
-> is committed as the source of truth for reproducible installs.
-
-### Option 3: Install globally from GitHub (no clone)
-
-```bash
+# Or install globally
 pnpm add -g git+https://github.com/adetxt/ai-usage-analyzer.git
-# or with npm
-npm install -g git+https://github.com/adetxt/ai-usage-analyzer.git
-# then
-ai-usage
-```
-
-### Option 4: From npm registry (when published)
-
-```bash
-npx -y ai-usage-analyzer
-# or
-pnpm add -g ai-usage-analyzer
-```
-
-To publish your own copy: `npm login && npm publish --access public`
-(requires the `ai-usage-analyzer` name to be available on npmjs.com,
-or use a scoped name like `@yourname/ai-usage-analyzer` and update
-the `name` field in `package.json` first).
-
-### Verify install
-
-```bash
 ai-usage --help
-# or via npx
-npx -y github:adetxt/ai-usage-analyzer --help
 ```
 
 ## Usage
@@ -78,139 +31,48 @@ npx -y github:adetxt/ai-usage-analyzer --help
 ```bash
 ai-usage                  # default TUI
 ai-usage --top 10         # show top 10 heaviest sessions
-ai-usage --json           # machine-readable JSON output
-ai-usage --markdown       # GitHub-flavored Markdown report
-ai-usage --md > report.md # same, save to file
-ai-usage -h               # help (also --help)
+ai-usage --json           # machine-readable JSON
+ai-usage --md > report.md # save as markdown
 ```
 
-### Environment overrides
+## Supported tools
 
-If a tool's data lives outside the default location, override its base path:
+| Tool | Default path | Tokens |
+|---|---|---|
+| Claude Code    | `~/.claude/projects`                | presence only |
+| Codex          | `~/.codex/sessions/YYYY/MM/DD/`    | yes |
+| OpenCode       | `~/.local/share/opencode/opencode.db` | yes (+cost) |
+| MimoCode       | `~/.local/share/mimocode/mimocode.db` | yes (+cost) |
+| GitHub Copilot | `~/.copilot/session-state/`        | presence only |
+| Antigravity    | `~/Library/Application Support/Antigravity` | presence only |
+| Gemini CLI     | `~/.gemini/antigravity/conversations` | presence only |
 
-```bash
-export CLAUDE_HOME=/custom/path/to/.claude
-export CODEX_HOME=/custom/path/to/.codex
-export OPENCODE_HOME=/custom/path/to/.local/share/opencode
-export MIMOCODE_HOME=/custom/path/to/.local/share/mimocode
-export COPILOT_HOME=/custom/path/to/.copilot
-export ANTIGRAVITY_HOME=/custom/path/to/Antigravity
-export GEMINI_HOME=/custom/path/to/.gemini
-```
+## Path overrides
 
-Or pass all at once via JSON:
+Override any tool's base path with an env var (`CLAUDE_HOME`, `CODEX_HOME`,
+`OPENCODE_HOME`, `MIMOCODE_HOME`, `COPILOT_HOME`, `ANTIGRAVITY_HOME`,
+`GEMINI_HOME`), or pass all at once via JSON:
 
 ```bash
 export AI_USAGE_PATHS_JSON='{"codex":"/data/codex","opencode":"/data/oc.db"}'
 ```
 
-## Supported tools
-
-| Tool | Path | Token data | Source format |
-|---|---|---|---|
-| Claude Code    | `~/.claude/transcripts`             | presence only | `ses_*.jsonl` |
-| Codex          | `~/.codex/sessions/YYYY/MM/DD/`    | **yes** | `rollout-*.jsonl` `token_count` events |
-| OpenCode       | `~/.local/share/opencode/opencode.db` | **yes** (+cost) | SQLite |
-| MimoCode       | `~/.local/share/mimocode/mimocode.db` | **yes** (+cost, when present) | SQLite |
-| GitHub Copilot | `~/.copilot/session-state/`        | presence only | `events.jsonl` |
-| Antigravity    | `~/Library/Application Support/Antigravity` | presence only | dir scan |
-| Gemini CLI     | `~/.gemini/antigravity/conversations` | presence only | `*.pb` protobuf |
-
 ## Token breakdown
 
-For tools that record token data, the analyzer shows the full breakdown:
+For tools that record token data, the analyzer shows input, output, cache
+read, cache write, and reasoning tokens. Cache hits are cheap; reasoning is
+the extended-thinking/chain-of-thought cost.
 
-- **Input** — prompt tokens sent to the model
-- **Output** — completion tokens generated by the model
-- **Cache Read** — prompt tokens served from the provider's cache (cheap)
-- **Cache Write** — prompt tokens cached for future use (OpenCode only)
-- **Reasoning** — extended thinking / chain-of-thought tokens
-
-The TUI is adaptive: at terminal widths below 110 columns it drops
-non-essential columns; at 110+ it shows the full breakdown with project
-paths, per-tool token columns, and longer distribution bars.
-
-## Architecture
+## How it works
 
 ```
 src/
-├── detectors.js    auto-path discovery (env → well-known locations)
-├── loaders.js      SQLite + JSONL parsers → unified session record
-├── aggregate.js    per-project / per-week / per-month grouping
-├── render.js       TUI (chalk + cli-table3 + boxen + gradient-string)
+├── detectors.js   auto-path discovery (env → well-known locations)
+├── loaders.js     SQLite + JSONL parsers → unified session record
+├── aggregate.js   per-project / per-week / per-month grouping
+├── render.js      TUI  •  markdown.js  →  Markdown report
 bin/
-└── ai-usage.js     entry point
-```
-
-The loader produces a unified record shape:
-
-```ts
-{
-  tool, sessionId, project, title, week, month, ts,
-  tokensInput, tokensOutput, tokensCacheRead, tokensCacheWrite,
-  tokensReasoning, tokensTotal, cost, model
-}
-```
-
-The aggregator then groups by project / week / month, and the renderer
-turns each grouping into a colored table with a distribution bar.
-
-## Output modes
-
-### TUI (default)
-
-Color-coded, boxed tables with bar charts. Adapts to terminal width.
-
-### JSON (`--json`)
-
-Single JSON object with detection results, summary, raw sessions, and errors.
-Suitable for piping into `jq` or feeding a dashboard.
-
-```bash
-ai-usage --json | jq '.summary'
-# {
-#   "n": 411,
-#   "tokensTotal": 1558000000,
-#   "tokensInput": 420900000,
-#   "tokensOutput": 4450000,
-#   "tokensCacheRead": 1130000000,
-#   "tokensCacheWrite": 49000,
-#   "tokensReasoning": 2210000,
-#   "cost": 29.4,
-#   "avg": 3790000
-# }
-```
-
-### Markdown (`--markdown` / `--md`)
-
-GitHub-flavored markdown report with the same sections as the TUI (header,
-detected tools, overview, token breakdown, per-project, per-month, per-week,
-top sessions, notes). Designed to be pasted into GitHub issues, PRs, or
-Notion pages.
-
-```bash
-ai-usage --md > report.md
-cat report.md   # or just paste the output into a GitHub comment
-```
-
-Distribution bars use Unicode block characters (`█░`) so they render in
-plain markdown without colors. Sample output:
-
-```markdown
-# AI Token Usage Report
-
-**Range**: 2026-04-01 → 2026-06-27  
-**Sessions**: 411  
-**Total tokens**: 1.58B  
-**Cost**: $29.40 (opencode only)  
-
-## Detected AI Tools
-
-| Tool | Status | Path | Count | Tokens |
-|---|---|---|---:|---|
-| Codex | ✅ present | `~/.codex/sessions` | 94 | ✅ |
-| OpenCode | ✅ present | `~/.local/share/opencode/opencode.db` | 328 | ✅ |
-| ...
+└── ai-usage.js    entry point
 ```
 
 ## License

package/bin/ai-usage.js

@@ -49,7 +49,7 @@ Environment overrides (per-tool data path):
   AI_USAGE_PATHS_JSON='{"codex":"/custom/path",...}'
 
 Supported tools:
-  • Claude Code    — ~/.claude/transcripts  (presence only)
+  • Claude Code    — ~/.claude/projects  (presence only)
   • Codex          — ~/.codex/sessions      (tokens from token_count events)
   • OpenCode       — ~/.local/share/opencode/opencode.db  (tokens + cost)
   • MimoCode       — ~/.local/share/mimocode/mimocode.db  (tokens + cost)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-usage-analyzer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TUI analyzer for local AI coding agent token usage. Auto-detects Claude Code, Codex, OpenCode, MimoCode, Copilot, Antigravity, and Gemini.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/src/detectors.js

@@ -56,25 +56,28 @@ const DETECTORS = [
     name: 'Claude Code',
     kind: 'jsonl',
     envVar: 'CLAUDE_HOME',
-    candidatePaths: () => {
-      const base = env.CLAUDE_HOME || join(HOME, '.claude');
-      return [
-        join(base, 'transcripts'),
-        join(base, 'projects'),
-      ];
-    },
+    candidatePaths: () => [
+      env.CLAUDE_HOME
+        ? join(env.CLAUDE_HOME, 'projects')
+        : join(HOME, '.claude', 'projects'),
+    ],
     count: (p) => {
       if (!p) return 0;
       let n = 0;
-      try {
-        for (const f of readdirSync(p)) {
-          if (f.startsWith('ses_') && f.endsWith('.jsonl')) n++;
-        }
-      } catch {}
+      function walk(dir) {
+        try {
+          for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) walk(full);
+            else if (e.isFile() && e.name.endsWith('.jsonl')) n++;
+          }
+        } catch {}
+      }
+      walk(p);
       return n;
     },
     hasTokens: false,  // transcripts only contain text, no token counts
-    description: '~/.claude/transcripts/*.jsonl  (no token data stored locally)',
+    description: '~/.claude/projects/*/<UUID>.jsonl  (no token data stored locally)',
   },
 
   // -----------------------------------------------------------------------