kerf-cli 0.1.4 → 0.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,198 @@
+# kerf-cli Architecture
+
+## Overview
+
+kerf-cli is a TypeScript CLI tool that provides cost intelligence for Claude Code. It parses Claude Code's JSONL session logs, calculates token costs, and presents the data through an interactive terminal UI.
+
+## System Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      kerf-cli                           │
+│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌─────┐ │
+│  │watch │ │esti- │ │budget│ │audit │ │report│ │init │ │
+│  │      │ │mate  │ │      │ │      │ │      │ │     │ │
+│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬──┘ │
+├─────┼────────┼────────┼────────┼────────┼────────┼────┤
+│     ▼        ▼        ▼        ▼        ▼        ▼    │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │              Core Engine Layer                   │   │
+│  │  ┌────────┐ ┌──────────┐ ┌───────────────────┐ │   │
+│  │  │ JSONL  │ │   Cost   │ │    Token          │ │   │
+│  │  │ Parser │ │Calculator│ │   Counter         │ │   │
+│  │  └────────┘ └──────────┘ └───────────────────┘ │   │
+│  │  ┌────────┐ ┌──────────┐ ┌───────────────────┐ │   │
+│  │  │Estimat-│ │  Budget  │ │   Cache           │ │   │
+│  │  │  or    │ │ Manager  │ │  Analyzer         │ │   │
+│  │  └────────┘ └──────────┘ └───────────────────┘ │   │
+│  └─────────────────────────────────────────────────┘   │
+├────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  │
+│  │ ~/.claude/    │  │ ~/.kerf/    │  │  .claude/    │  │
+│  │ projects/     │  │ kerf.db    │  │ settings.json│  │
+│  │ *.jsonl       │  │ (SQLite)   │  │ (hooks)      │  │
+│  └──────────────┘  └─────────────┘  └──────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+```
+kerf-cli/
+├── src/
+│   ├── cli/                    # CLI layer
+│   │   ├── index.ts            # Entry point (Commander.js)
+│   │   ├── commands/
+│   │   │   ├── watch.ts        # Real-time dashboard
+│   │   │   ├── estimate.ts     # Pre-flight cost estimation
+│   │   │   ├── budget.ts       # Budget management
+│   │   │   ├── audit.ts        # Ghost token audit
+│   │   │   ├── report.ts       # Historical reports
+│   │   │   └── init.ts         # Setup & hook installation
+│   │   └── ui/
+│   │       ├── Dashboard.tsx   # Main Ink dashboard
+│   │       ├── CostMeter.tsx   # Token burn rate gauge
+│   │       ├── ContextBar.tsx  # Context window fill bar
+│   │       ├── BudgetAlert.tsx # Budget threshold warnings
+│   │       └── EstimateCard.tsx# Pre-flight estimate display
+│   ├── core/                   # Business logic
+│   │   ├── parser.ts           # JSONL session log parser
+│   │   ├── costCalculator.ts   # Per-model pricing engine
+│   │   ├── tokenCounter.ts     # Token counting + context overhead
+│   │   ├── estimator.ts        # Pre-flight cost estimation
+│   │   ├── budgetManager.ts    # SQLite budget CRUD
+│   │   ├── cacheAnalyzer.ts    # Cache hit/miss analysis
+│   │   └── config.ts           # Constants & configuration
+│   ├── audit/                  # Audit modules
+│   │   ├── ghostTokens.ts      # Ghost token overhead calculator
+│   │   ├── claudeMdLinter.ts   # CLAUDE.md attention curve scorer
+│   │   ├── mcpAnalyzer.ts      # MCP server token cost analysis
+│   │   └── recommendations.ts  # Actionable optimization suggestions
+│   ├── hooks/                  # Claude Code hook system
+│   │   ├── templates/
+│   │   │   ├── notification.sh # Token usage logger
+│   │   │   └── stop.sh         # Budget enforcement
+│   │   └── installer.ts        # Hook installation logic
+│   ├── db/
+│   │   ├── schema.ts           # SQLite schema & init
+│   │   └── migrations.ts       # Database migrations
+│   └── types/
+│       ├── jsonl.ts            # JSONL log types
+│       ├── pricing.ts          # Model pricing types
+│       └── config.ts           # Config & audit types
+├── tests/
+│   ├── parser.test.ts
+│   ├── costCalculator.test.ts
+│   ├── estimator.test.ts
+│   ├── tokenCounter.test.ts
+│   └── fixtures/
+│       ├── sample-session.jsonl
+│       └── sample-claude-md.md
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+└── vitest.config.ts
+```
+
+## Technology Stack
+
+| Component | Technology | Why |
+|-----------|-----------|-----|
+| CLI framework | Commander.js | Subcommand routing, option parsing |
+| Terminal UI | Ink 5 (React 18) | Interactive dashboard with live updates |
+| Database | better-sqlite3 | Synchronous access, fast for CLI tools |
+| File watching | chokidar | Cross-platform file change detection |
+| Dates | Day.js | Lightweight, immutable date operations |
+| Colors | chalk | Terminal color output |
+| Bundler | tsup | Fast ESM bundling with shebang support |
+| Testing | vitest | Fast, ESM-native test runner |
+
+## Key Design Decisions
+
+### Token counting: heuristic over API
+
+kerf-cli uses `characters / 3.5` as a fast local heuristic instead of calling the Anthropic token counting API. This keeps the tool instant and dependency-free. For actual session costs, it reads the authoritative `total_cost_usd` field from JSONL logs when available.
+
+### Synchronous SQLite
+
+`better-sqlite3` is used instead of async alternatives because CLI tools benefit from synchronous access — no event loop overhead, faster startup, simpler code.
+
+### Multiply-then-divide cost calculation
+
+To avoid floating point drift in financial calculations:
+```typescript
+const cost = (tokens * pricePerMillion) / 1_000_000;
+```
+When `total_cost_usd` is present in the JSONL, it's used as the authoritative source.
+
+### JSONL message deduplication
+
+Claude Code streams responses, producing intermediate JSONL entries with partial data (e.g., `output_tokens: 1`). The parser deduplicates by message ID, keeping the **last** occurrence for each ID to get final token counts.
+
+### Context overhead constants
+
+```
+System prompt:      14,328 tokens (fixed)
+Built-in tools:     15,000 tokens (fixed, 24 tools)
+MCP tools:          ~600 tokens per tool (variable)
+CLAUDE.md:          variable (parsed from file)
+Autocompact buffer: 33,000 tokens (fixed)
+Context window:     200,000 tokens total
+```
+
+### CLAUDE.md attention curve
+
+Claude's attention follows a U-shaped curve across the context. kerf-cli maps each CLAUDE.md section to an attention zone:
+- **0-30%:** High attention (top of file)
+- **30-70%:** Low attention ("dead zone")
+- **70-100%:** High attention (bottom of file)
+
+Critical rules (NEVER, ALWAYS, MUST, CRITICAL) in the dead zone are flagged for reordering.
+
+## Data Flow
+
+### Watch command
+```
+~/.claude/projects/*.jsonl → parser.ts → costCalculator.ts → Dashboard.tsx
+         ↑ chokidar watches        ↓ React state updates every 2s
+```
+
+### Estimate command
+```
+task description → estimator.ts → complexity detection → turn estimation
+                         ↓
+                  tokenCounter.ts → context overhead
+                         ↓
+                  costCalculator.ts → pricing per model
+                         ↓
+                  EstimateCard.tsx (or JSON output)
+```
+
+### Audit command
+```
+CLAUDE.md → claudeMdLinter.ts → section analysis + attention scoring
+.mcp.json → mcpAnalyzer.ts   → tool count + token overhead
+                    ↓
+           ghostTokens.ts → total overhead + grade
+                    ↓
+           recommendations.ts → prioritized actions
+```
+
+## Model Pricing (as of May 2025)
+
+| Model | Input | Output | Cache Read | Cache Creation |
+|-------|-------|--------|------------|----------------|
+| Sonnet 4 | $3/M | $15/M | $0.30/M | $3.75/M |
+| Opus 4 | $15/M | $75/M | $1.50/M | $18.75/M |
+| Haiku 4 | $0.80/M | $4/M | $0.08/M | $1.00/M |
+
+## Key Paths
+
+| Path | Purpose |
+|------|---------|
+| `~/.claude/projects/<encoded-path>/<session>.jsonl` | Claude Code session logs |
+| `~/.claude/settings.json` | Global Claude Code settings & hooks |
+| `.claude/settings.json` | Project-level settings & hooks |
+| `.mcp.json` / `~/.claude.json` | MCP server configurations |
+| `~/.kerf/kerf.db` | SQLite database (budgets, usage) |
+| `~/.kerf/session-log.jsonl` | kerf-cli hook event log |

package/CHANGELOG.md

@@ -1,17 +1,72 @@
 # Changelog
 
-## v0.1.1 (2026-04-04)
+All notable changes to this project will be documented in this file.
 
-- Fix: ContextBar crash when token usage exceeds 100% of context window
-- Fix: Package published as `kerf-cli` (npm blocked unscoped `kerf`)
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.0 (2026-04-04)
+## [0.2.0] - 2026-04-04
 
-Initial release.
+### Added
+- `kerf` binary alias — both `kerf` and `kerf-cli` now work as command names
+- Repository metadata (homepage, bugs, repository fields in package.json)
+- CI badge in README
+- `test:coverage` script
+- Separate CHANGELOG.md following Keep a Changelog format
+- ARCHITECTURE.md with project structure, design decisions, and data flow
+- LAUNCH-POST.md for social media launch content
 
-- `npx kerf-cli watch` — Real-time cost dashboard
-- `npx kerf-cli estimate <task>` — Pre-flight cost estimation
-- `npx kerf-cli budget set/show/list/remove` — Per-project budget management
-- `npx kerf-cli audit` — Ghost token & CLAUDE.md audit
-- `npx kerf-cli report` — Historical cost reports
-- `npx kerf-cli init` — Setup hooks and database
+### Changed
+- README rewritten with `kerf` as primary command name for brevity
+- All command examples use short `kerf` form
+
+## [0.1.5] - 2026-04-04
+
+### Fixed
+- Version injection via tsup `define` instead of runtime `createRequire` — fixes `Cannot find module '../../package.json'` when running from npm
+
+## [0.1.4] - 2026-04-04
+
+### Fixed
+- `--version` now reads dynamically from package.json
+- `--compare` shows proper side-by-side table for all 3 models (was only rendering first)
+- `watch` gracefully exits in non-TTY environments with helpful message
+- `useInput` disabled in non-TTY to prevent raw mode crash
+
+## [0.1.3] - 2026-04-04
+
+### Fixed
+- CLAUDE.md detection now searches git root and `~/.claude/` (not just cwd)
+- `--claude-md-only` shows per-section breakdown with attention zones and suggested reorder
+- `--mcp-only` properly filters to MCP-only output and recommendations
+- Hourly report dates no longer show "Invalid Date"
+
+## [0.1.1] - 2026-04-04
+
+### Fixed
+- ContextBar crash when token usage exceeds 100% of context window (negative `String.repeat`)
+
+## [0.1.0] - 2026-04-04
+
+### Added
+- `kerf-cli watch` — Real-time cost dashboard with Ink (React for CLI)
+- `kerf-cli estimate <task>` — Pre-flight cost estimation with complexity detection
+- `kerf-cli budget set/show/list/remove` — Per-project budget management with SQLite
+- `kerf-cli audit` — Ghost token audit with CLAUDE.md attention curve analysis
+- `kerf-cli report` — Historical cost reports with hourly charts, CSV/JSON export
+- `kerf-cli init` — Setup hooks, database, and detect compatible tools
+- JSONL session log parser with message deduplication
+- Per-model pricing engine (Sonnet 4, Opus 4, Haiku 4)
+- Token counting heuristic (characters / 3.5)
+- Context overhead calculator (ghost tokens)
+- MCP server token cost analyzer
+- Claude Code hook templates (notification + budget enforcement)
+- 34 vitest tests with fixture data
+- CI/CD with GitHub Actions (test on Node 20/22, publish on release)
+
+[0.2.0]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.1...v0.1.3
+[0.1.1]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/dhanushkumarsivaji/kerf-cli/releases/tag/v0.1.0

package/LAUNCH-POST.md

@@ -0,0 +1,173 @@
+# kerf-cli — Launch Post Brief
+
+> Use this document to generate a launch post for Twitter/X, Reddit, LinkedIn, or any platform.
+
+---
+
+## What It Is
+
+**kerf-cli** — Cost intelligence for Claude Code. Real-time dashboards, pre-flight cost estimation, per-project budgets, and ghost token auditing.
+
+- **npm:** https://www.npmjs.com/package/kerf-cli
+- **GitHub:** https://github.com/dhanushkumarsivaji/kerf-cli
+- **Install:** `npx kerf-cli@latest`
+- **Author:** Dhanush Kumar Sivaji
+
+---
+
+## The Problem It Solves
+
+Claude Code users have no visibility into token spending during sessions. People exhaust their 20x Max plan in under 20 minutes without knowing why. Context windows get silently consumed by ghost tokens — system prompts (14K), built-in tools (15K), MCP servers, CLAUDE.md files, and autocompact buffers — before any conversation even starts.
+
+---
+
+## What It Does (6 Commands)
+
+### 1. `kerf-cli watch` — Real-Time Dashboard
+Live cost monitoring in a second terminal tab while Claude Code runs.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  kerf-cli watch | session: a3f8c2d1... | 47 messages         │
+├──────────────────────────────────────────────────────────────┤
+│  >> $4.82 / ~$15.00 window | $0.18/min | ~56m remaining     │
+│  [████████████░░░░░░░░░░░░░░░░░░] 38% | 76K / 200K tokens   │
+│    system(14K) + tools(15K) + mcp(8K) + conversation(39K)   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 2. `kerf-cli estimate` — Pre-Flight Cost Estimation
+Know what a task will cost before you start. Compares Sonnet vs Opus vs Haiku.
+
+```
+$ kerf-cli estimate --compare 'add feature'
+
+  Model      Turns      Low          Expected     High
+  ----------------------------------------------------------
+  sonnet     5-15       $0.67        $1.05        $1.45
+  opus       5-15       $3.35        $5.24        $7.26
+  haiku      5-15       $0.18        $0.28        $0.39
+```
+
+### 3. `kerf-cli budget` — Per-Project Budgets
+Set weekly/monthly spending limits. Automatic warnings at 80% and alerts at 100%.
+
+```
+$ kerf-cli budget show
+
+  Budget:  $50.00/weekly
+  Spent:   $42.30
+  [████████████████░░░░] 84.6%
+```
+
+### 4. `kerf-cli audit` — Ghost Token Audit
+Find invisible token waste eating your 200K context window.
+
+```
+$ kerf-cli audit
+
+  Context Window Health: B (62% usable)
+
+  Ghost Token Breakdown:
+    System prompt:     14,328 tokens (7.2%)
+    Built-in tools:    15,000 tokens (7.5%)
+    MCP tools (3 srv):  8,400 tokens (4.2%)
+    CLAUDE.md:          2,100 tokens (1.1%)
+    Autocompact buffer:33,000 tokens (16.5%)
+    Total overhead:    72,828 tokens (36.4%)
+
+  Recommendations:
+    1. [HIGH] Reorder CLAUDE.md — 3 critical rules in dead zone
+    2. [MED] Disable unused 'playwright' MCP server (-7,200 tokens)
+```
+
+### 5. `kerf-cli audit --claude-md-only` — CLAUDE.md Attention Curve Analysis
+Maps each section to Claude's U-shaped attention curve. Flags critical rules (NEVER, ALWAYS, MUST) stuck in the low-attention "dead zone" (30-70% of file).
+
+```
+  Sections:
+    Conventions                 110 tokens  L15-23 [dead zone] *critical rules*
+    Key Paths                    87 tokens  L24-30 [dead zone]
+    Testing                      26 tokens  L31-35 [high attention]
+```
+
+### 6. `kerf-cli report` — Historical Cost Reports
+Daily/weekly/monthly spending with hourly charts, per-model and per-session breakdowns. CSV and JSON export.
+
+```
+$ kerf-cli report --sessions --model
+
+  Total Cost:       $12.77
+  Cache Hit Rate:   100.0%
+
+  Model Breakdown:
+    sonnet: $6.20 (73.6%) — 3 sessions
+    opus:   $2.22 (26.4%) — 1 session
+
+  Hourly:
+    Apr 4, 2 PM    ████░░░░░░░░ $1.75
+    Apr 4, 6 PM    ████████████ $5.64
+```
+
+---
+
+## Tech Stack
+
+- TypeScript, Commander.js, Ink (React for CLI), better-sqlite3, chokidar, Day.js
+- Parses Claude Code's JSONL session logs from `~/.claude/projects/`
+- Stores budgets in SQLite at `~/.kerf/kerf.db`
+- 34 tests passing, zero TypeScript errors
+- Bundled with tsup, published as ESM
+
+---
+
+## How It Was Built
+
+Built entirely in a single Claude Code session using Opus. The entire project — scaffolding, 7 core modules, 5 Ink UI components, 6 CLI commands, 4 audit analyzers, hook system, SQLite schema, 34 tests, CI/CD, README, and npm publishing — was implemented from a detailed implementation guide in one conversation.
+
+---
+
+## Comparison
+
+| Feature | kerf-cli | RTK | ccusage | token-optimizer |
+|---------|----------|-----|---------|-----------------|
+| Real-time dashboard | Yes | No | No | No |
+| Pre-flight estimation | Yes | No | No | No |
+| Per-project budgets | Yes | No | No | No |
+| Ghost token audit | Yes | No | No | Partial |
+| CLAUDE.md optimization | Yes | No | No | Yes |
+| Historical reports | Yes | No | Yes | No |
+
+**RTK compresses. ccusage tracks. kerf predicts.**
+
+---
+
+## Quick Start (3 commands)
+
+```bash
+npx kerf-cli@latest init      # set up database & hooks
+npx kerf-cli@latest watch     # live dashboard in second terminal
+npx kerf-cli@latest audit     # find ghost token waste
+```
+
+---
+
+## Key Stats
+
+- **Package:** kerf-cli on npm
+- **Version:** 0.1.5
+- **Size:** 56KB bundled
+- **Tests:** 34 passing
+- **License:** MIT
+- **Node:** 20+
+- **Published:** April 4, 2026
+
+---
+
+## Taglines (pick one)
+
+- "Cost intelligence for Claude Code. Know before you spend."
+- "Stop burning tokens blind. kerf-cli gives you a dashboard for Claude Code."
+- "Your Claude Code plan just got a speedometer."
+- "Every token has a kerf. Now you can see it."
+- "I built a CLI that shows you exactly where your Claude Code tokens go."