claude-burn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,82 @@
+# claude-burn
+
+See which Claude Code sessions are eating your tokens and how fast.
+
+Zero dependencies. Reads local JSONL files. Nothing leaves your machine.
+
+![claude-burn dashboard](screenshot.png)
+
+## Quick start
+
+```bash
+npx claude-burn
+```
+
+Opens a dashboard at `http://localhost:8787` with auto-refresh.
+
+To install globally:
+
+```bash
+npm install -g claude-burn
+claude-burn
+```
+
+## Features
+
+- **Active session detection** — see which sessions are running right now
+- **Token breakdown** — input, output, cache read, cache write per session
+- **Burn rate** — recent (last 3 min) and average (active time) tokens/min
+- **Active vs idle time** — excludes idle gaps from duration calculations
+- **Subagent tracking** — token usage per agent with model info on hover
+- **Session share bar** — proportional token distribution across sessions
+- **API cost equivalent** — what your usage would cost at API pricing (per model)
+- **Timeline chart** — cumulative token growth over time
+- **Search and sort** — filter sessions by title, sort by recent/tokens/burn rate
+- **Keyboard shortcuts** — `R` refresh, `J/K` navigate, `/` search, `1-7` time filter
+- **Auto-refresh** — every 5s for 24h and under, manual for longer ranges
+
+## Options
+
+```
+claude-burn [options]
+
+--port <n>        Server port (default: 8787)
+--data-dir <path> Claude data directory (default: ~/.claude/projects)
+--no-open         Don't auto-open browser
+--version, -v     Show version
+--help, -h        Show help
+```
+
+## Keyboard shortcuts
+
+| Key | Action |
+|-----|--------|
+| `R` | Refresh data |
+| `J` / `K` | Navigate sessions down / up |
+| `/` | Focus search |
+| `Esc` | Clear search |
+| `1` - `7` | Time filter (1h, 6h, 12h, 24h, 3d, 7d, 30d) |
+
+## How it works
+
+Claude Code stores a `.jsonl` file for every session in `~/.claude/projects/`. Each line contains timestamps, token usage, model info, and message content. This tool parses those files and displays the data in a local web dashboard.
+
+Pricing is calculated per model:
+| Model | Input | Output | Cache read | Cache write |
+|-------|-------|--------|------------|-------------|
+| Opus 4.6 | $5/M | $25/M | $0.50/M | $6.25/M |
+| Sonnet 4.6 | $3/M | $15/M | $0.30/M | $3.75/M |
+| Haiku 4.5 | $1/M | $5/M | $0.10/M | $1.25/M |
+
+## Requirements
+
+- Node.js 18+
+- Claude Code (session data must exist in `~/.claude/projects/`)
+
+## Privacy
+
+All data stays on your machine. No analytics, no network calls, no telemetry. The server binds to `127.0.0.1` only.
+
+## License
+
+MIT

package/bin/claude-burn.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+const { createServer, getAllSessions } = require('../src/server');
+const { exec } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const pkg = require('../package.json');
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  \x1b[32mclaude-burn\x1b[0m v${pkg.version}
+  Monitor Claude Code token usage
+
+  Usage:
+    claude-burn [options]
+
+  Options:
+    --port <n>        Server port (default: 8787)
+    --data-dir <path> Claude data directory (default: ~/.claude/projects)
+    --no-open         Don't auto-open browser
+    --version, -v     Show version
+    --help, -h        Show this help
+`);
+  process.exit(0);
+}
+
+function getArg(flag, defaultVal) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return defaultVal;
+}
+
+const port = parseInt(getArg('--port', '8787'), 10);
+const dataDir = getArg('--data-dir',
+  process.env.CLAUDE_CONFIG_DIR
+    ? path.join(process.env.CLAUDE_CONFIG_DIR, 'projects')
+    : path.join(os.homedir(), '.claude', 'projects')
+);
+const noOpen = args.includes('--no-open');
+
+// Check if data directory exists
+if (!fs.existsSync(dataDir)) {
+  console.log(`\n  \x1b[32mclaude-burn\x1b[0m v${pkg.version}\n`);
+  console.log(`  \x1b[31mNo Claude Code data found at:\x1b[0m ${dataDir}`);
+  console.log(`  Make sure Claude Code is installed and has been used at least once.`);
+  console.log(`  Or specify a custom path: claude-burn --data-dir /path/to/projects\n`);
+  process.exit(1);
+}
+
+// Count sessions
+let sessionCount = 0;
+try {
+  for (const dir of fs.readdirSync(dataDir)) {
+    const dirPath = path.join(dataDir, dir);
+    if (fs.statSync(dirPath).isDirectory()) {
+      for (const f of fs.readdirSync(dirPath)) {
+        if (f.endsWith('.jsonl')) sessionCount++;
+      }
+    }
+  }
+} catch {}
+
+const server = createServer({ port, dataDir });
+
+server.listen(port, '127.0.0.1', () => {
+  const url = `http://localhost:${port}`;
+  console.log(`\n  \x1b[32mclaude-burn\x1b[0m v${pkg.version}\n`);
+  console.log(`  Dashboard:  \x1b[4m${url}\x1b[0m`);
+  console.log(`  Scanning:   ${dataDir} (${sessionCount} sessions)`);
+  console.log(`\n  Press \x1b[2mCtrl+C\x1b[0m to stop\n`);
+
+  if (!noOpen) {
+    const cmd = process.platform === 'darwin' ? `open "${url}"`
+      : process.platform === 'win32' ? `start "${url}"`
+      : `xdg-open "${url}"`;
+    exec(cmd, () => {});
+  }
+});
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.log(`\n  \x1b[31mPort ${port} is already in use.\x1b[0m`);
+    console.log(`  Try: claude-burn --port ${port + 1}\n`);
+    process.exit(1);
+  }
+  throw err;
+});
+
+// Graceful shutdown
+function shutdown() {
+  console.log('\n  Stopped.\n');
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 1000);
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claude-burn",
+  "version": "1.0.0",
+  "description": "Monitor Claude Code token usage, burn rate, and session attribution. Zero dependencies.",
+  "bin": {
+    "claude-burn": "./bin/claude-burn.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "token-monitor",
+    "usage",
+    "anthropic",
+    "burn-rate",
+    "dashboard",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "annsheronova",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/annsheronova/claude-burn.git"
+  },
+  "homepage": "https://github.com/annsheronova/claude-burn",
+  "bugs": {
+    "url": "https://github.com/annsheronova/claude-burn/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}