kerf-cli 0.1.5 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +72 -0
- package/LAUNCH-POST.md +173 -0
- package/README.md +81 -91
- package/dist/index.js +252 -102
- package/dist/index.js.map +1 -1
- package/package.json +13 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.2.0] - 2026-04-04
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- `kerf` binary alias — both `kerf` and `kerf-cli` now work as command names
|
|
12
|
+
- Repository metadata (homepage, bugs, repository fields in package.json)
|
|
13
|
+
- CI badge in README
|
|
14
|
+
- `test:coverage` script
|
|
15
|
+
- Separate CHANGELOG.md following Keep a Changelog format
|
|
16
|
+
- ARCHITECTURE.md with project structure, design decisions, and data flow
|
|
17
|
+
- LAUNCH-POST.md for social media launch content
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
- README rewritten with `kerf` as primary command name for brevity
|
|
21
|
+
- All command examples use short `kerf` form
|
|
22
|
+
|
|
23
|
+
## [0.1.5] - 2026-04-04
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
- Version injection via tsup `define` instead of runtime `createRequire` — fixes `Cannot find module '../../package.json'` when running from npm
|
|
27
|
+
|
|
28
|
+
## [0.1.4] - 2026-04-04
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
- `--version` now reads dynamically from package.json
|
|
32
|
+
- `--compare` shows proper side-by-side table for all 3 models (was only rendering first)
|
|
33
|
+
- `watch` gracefully exits in non-TTY environments with helpful message
|
|
34
|
+
- `useInput` disabled in non-TTY to prevent raw mode crash
|
|
35
|
+
|
|
36
|
+
## [0.1.3] - 2026-04-04
|
|
37
|
+
|
|
38
|
+
### Fixed
|
|
39
|
+
- CLAUDE.md detection now searches git root and `~/.claude/` (not just cwd)
|
|
40
|
+
- `--claude-md-only` shows per-section breakdown with attention zones and suggested reorder
|
|
41
|
+
- `--mcp-only` properly filters to MCP-only output and recommendations
|
|
42
|
+
- Hourly report dates no longer show "Invalid Date"
|
|
43
|
+
|
|
44
|
+
## [0.1.1] - 2026-04-04
|
|
45
|
+
|
|
46
|
+
### Fixed
|
|
47
|
+
- ContextBar crash when token usage exceeds 100% of context window (negative `String.repeat`)
|
|
48
|
+
|
|
49
|
+
## [0.1.0] - 2026-04-04
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
- `kerf-cli watch` — Real-time cost dashboard with Ink (React for CLI)
|
|
53
|
+
- `kerf-cli estimate <task>` — Pre-flight cost estimation with complexity detection
|
|
54
|
+
- `kerf-cli budget set/show/list/remove` — Per-project budget management with SQLite
|
|
55
|
+
- `kerf-cli audit` — Ghost token audit with CLAUDE.md attention curve analysis
|
|
56
|
+
- `kerf-cli report` — Historical cost reports with hourly charts, CSV/JSON export
|
|
57
|
+
- `kerf-cli init` — Setup hooks, database, and detect compatible tools
|
|
58
|
+
- JSONL session log parser with message deduplication
|
|
59
|
+
- Per-model pricing engine (Sonnet 4, Opus 4, Haiku 4)
|
|
60
|
+
- Token counting heuristic (characters / 3.5)
|
|
61
|
+
- Context overhead calculator (ghost tokens)
|
|
62
|
+
- MCP server token cost analyzer
|
|
63
|
+
- Claude Code hook templates (notification + budget enforcement)
|
|
64
|
+
- 34 vitest tests with fixture data
|
|
65
|
+
- CI/CD with GitHub Actions (test on Node 20/22, publish on release)
|
|
66
|
+
|
|
67
|
+
[0.2.0]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.5...v0.2.0
|
|
68
|
+
[0.1.5]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.4...v0.1.5
|
|
69
|
+
[0.1.4]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.3...v0.1.4
|
|
70
|
+
[0.1.3]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.1...v0.1.3
|
|
71
|
+
[0.1.1]: https://github.com/dhanushkumarsivaji/kerf-cli/compare/v0.1.0...v0.1.1
|
|
72
|
+
[0.1.0]: https://github.com/dhanushkumarsivaji/kerf-cli/releases/tag/v0.1.0
|
package/LAUNCH-POST.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# kerf-cli — Launch Post Brief
|
|
2
|
+
|
|
3
|
+
> Use this document to generate a launch post for Twitter/X, Reddit, LinkedIn, or any platform.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## What It Is
|
|
8
|
+
|
|
9
|
+
**kerf-cli** — Cost intelligence for Claude Code. Real-time dashboards, pre-flight cost estimation, per-project budgets, and ghost token auditing.
|
|
10
|
+
|
|
11
|
+
- **npm:** https://www.npmjs.com/package/kerf-cli
|
|
12
|
+
- **GitHub:** https://github.com/dhanushkumarsivaji/kerf-cli
|
|
13
|
+
- **Install:** `npx kerf-cli@latest`
|
|
14
|
+
- **Author:** Dhanush Kumar Sivaji
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## The Problem It Solves
|
|
19
|
+
|
|
20
|
+
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.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## What It Does (6 Commands)
|
|
25
|
+
|
|
26
|
+
### 1. `kerf-cli watch` — Real-Time Dashboard
|
|
27
|
+
Live cost monitoring in a second terminal tab while Claude Code runs.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
31
|
+
│ kerf-cli watch | session: a3f8c2d1... | 47 messages │
|
|
32
|
+
├──────────────────────────────────────────────────────────────┤
|
|
33
|
+
│ >> $4.82 / ~$15.00 window | $0.18/min | ~56m remaining │
|
|
34
|
+
│ [████████████░░░░░░░░░░░░░░░░░░] 38% | 76K / 200K tokens │
|
|
35
|
+
│ system(14K) + tools(15K) + mcp(8K) + conversation(39K) │
|
|
36
|
+
└──────────────────────────────────────────────────────────────┘
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### 2. `kerf-cli estimate` — Pre-Flight Cost Estimation
|
|
40
|
+
Know what a task will cost before you start. Compares Sonnet vs Opus vs Haiku.
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
$ kerf-cli estimate --compare 'add feature'
|
|
44
|
+
|
|
45
|
+
Model Turns Low Expected High
|
|
46
|
+
----------------------------------------------------------
|
|
47
|
+
sonnet 5-15 $0.67 $1.05 $1.45
|
|
48
|
+
opus 5-15 $3.35 $5.24 $7.26
|
|
49
|
+
haiku 5-15 $0.18 $0.28 $0.39
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 3. `kerf-cli budget` — Per-Project Budgets
|
|
53
|
+
Set weekly/monthly spending limits. Automatic warnings at 80% and alerts at 100%.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
$ kerf-cli budget show
|
|
57
|
+
|
|
58
|
+
Budget: $50.00/weekly
|
|
59
|
+
Spent: $42.30
|
|
60
|
+
[████████████████░░░░] 84.6%
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 4. `kerf-cli audit` — Ghost Token Audit
|
|
64
|
+
Find invisible token waste eating your 200K context window.
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
$ kerf-cli audit
|
|
68
|
+
|
|
69
|
+
Context Window Health: B (62% usable)
|
|
70
|
+
|
|
71
|
+
Ghost Token Breakdown:
|
|
72
|
+
System prompt: 14,328 tokens (7.2%)
|
|
73
|
+
Built-in tools: 15,000 tokens (7.5%)
|
|
74
|
+
MCP tools (3 srv): 8,400 tokens (4.2%)
|
|
75
|
+
CLAUDE.md: 2,100 tokens (1.1%)
|
|
76
|
+
Autocompact buffer:33,000 tokens (16.5%)
|
|
77
|
+
Total overhead: 72,828 tokens (36.4%)
|
|
78
|
+
|
|
79
|
+
Recommendations:
|
|
80
|
+
1. [HIGH] Reorder CLAUDE.md — 3 critical rules in dead zone
|
|
81
|
+
2. [MED] Disable unused 'playwright' MCP server (-7,200 tokens)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 5. `kerf-cli audit --claude-md-only` — CLAUDE.md Attention Curve Analysis
|
|
85
|
+
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).
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
Sections:
|
|
89
|
+
Conventions 110 tokens L15-23 [dead zone] *critical rules*
|
|
90
|
+
Key Paths 87 tokens L24-30 [dead zone]
|
|
91
|
+
Testing 26 tokens L31-35 [high attention]
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 6. `kerf-cli report` — Historical Cost Reports
|
|
95
|
+
Daily/weekly/monthly spending with hourly charts, per-model and per-session breakdowns. CSV and JSON export.
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
$ kerf-cli report --sessions --model
|
|
99
|
+
|
|
100
|
+
Total Cost: $12.77
|
|
101
|
+
Cache Hit Rate: 100.0%
|
|
102
|
+
|
|
103
|
+
Model Breakdown:
|
|
104
|
+
sonnet: $6.20 (73.6%) — 3 sessions
|
|
105
|
+
opus: $2.22 (26.4%) — 1 session
|
|
106
|
+
|
|
107
|
+
Hourly:
|
|
108
|
+
Apr 4, 2 PM ████░░░░░░░░ $1.75
|
|
109
|
+
Apr 4, 6 PM ████████████ $5.64
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Tech Stack
|
|
115
|
+
|
|
116
|
+
- TypeScript, Commander.js, Ink (React for CLI), better-sqlite3, chokidar, Day.js
|
|
117
|
+
- Parses Claude Code's JSONL session logs from `~/.claude/projects/`
|
|
118
|
+
- Stores budgets in SQLite at `~/.kerf/kerf.db`
|
|
119
|
+
- 34 tests passing, zero TypeScript errors
|
|
120
|
+
- Bundled with tsup, published as ESM
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## How It Was Built
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Comparison
|
|
131
|
+
|
|
132
|
+
| Feature | kerf-cli | RTK | ccusage | token-optimizer |
|
|
133
|
+
|---------|----------|-----|---------|-----------------|
|
|
134
|
+
| Real-time dashboard | Yes | No | No | No |
|
|
135
|
+
| Pre-flight estimation | Yes | No | No | No |
|
|
136
|
+
| Per-project budgets | Yes | No | No | No |
|
|
137
|
+
| Ghost token audit | Yes | No | No | Partial |
|
|
138
|
+
| CLAUDE.md optimization | Yes | No | No | Yes |
|
|
139
|
+
| Historical reports | Yes | No | Yes | No |
|
|
140
|
+
|
|
141
|
+
**RTK compresses. ccusage tracks. kerf predicts.**
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Quick Start (3 commands)
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npx kerf-cli@latest init # set up database & hooks
|
|
149
|
+
npx kerf-cli@latest watch # live dashboard in second terminal
|
|
150
|
+
npx kerf-cli@latest audit # find ghost token waste
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Key Stats
|
|
156
|
+
|
|
157
|
+
- **Package:** kerf-cli on npm
|
|
158
|
+
- **Version:** 0.1.5
|
|
159
|
+
- **Size:** 56KB bundled
|
|
160
|
+
- **Tests:** 34 passing
|
|
161
|
+
- **License:** MIT
|
|
162
|
+
- **Node:** 20+
|
|
163
|
+
- **Published:** April 4, 2026
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Taglines (pick one)
|
|
168
|
+
|
|
169
|
+
- "Cost intelligence for Claude Code. Know before you spend."
|
|
170
|
+
- "Stop burning tokens blind. kerf-cli gives you a dashboard for Claude Code."
|
|
171
|
+
- "Your Claude Code plan just got a speedometer."
|
|
172
|
+
- "Every token has a kerf. Now you can see it."
|
|
173
|
+
- "I built a CLI that shows you exactly where your Claude Code tokens go."
|
package/README.md
CHANGED
|
@@ -5,13 +5,14 @@
|
|
|
5
5
|
> *kerf (n.) — the width of material removed by a cutting tool. Every token operation has a kerf.*
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/kerf-cli)
|
|
8
|
+
[](https://github.com/dhanushkumarsivaji/kerf-cli/actions/workflows/ci.yml)
|
|
8
9
|
[](LICENSE)
|
|
9
10
|
[]()
|
|
10
11
|
[]()
|
|
11
12
|
|
|
12
13
|
```
|
|
13
14
|
┌──────────────────────────────────────────────────────────────┐
|
|
14
|
-
│ kerf
|
|
15
|
+
│ kerf watch | session: a3f8c2d1... | 47 messages │
|
|
15
16
|
├──────────────────────────────────────────────────────────────┤
|
|
16
17
|
│ >> $4.82 / ~$15.00 window | $0.18/min | ~56m remaining │
|
|
17
18
|
│ [████████████░░░░░░░░░░░░░░░░░░] 38% | 76K / 200K tokens │
|
|
@@ -34,35 +35,41 @@ npx kerf-cli@latest watch # Real-time cost dashboard
|
|
|
34
35
|
npx kerf-cli@latest audit # Find ghost token waste
|
|
35
36
|
```
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
After global install (`npm i -g kerf-cli`), use the shorter `kerf` command:
|
|
39
|
+
|
|
38
40
|
```bash
|
|
39
|
-
|
|
41
|
+
kerf watch
|
|
42
|
+
kerf estimate 'refactor auth'
|
|
43
|
+
kerf audit
|
|
40
44
|
```
|
|
41
45
|
|
|
46
|
+
> Both `kerf` and `kerf-cli` work as command names.
|
|
47
|
+
|
|
42
48
|
---
|
|
43
49
|
|
|
44
50
|
## The Problem
|
|
45
51
|
|
|
46
52
|
> "20x Max plan exhausted in 19 minutes"
|
|
47
53
|
|
|
48
|
-
Claude Code sessions burn through tokens fast — context overhead, MCP tools, bloated CLAUDE.md files — and there's no way to see it in real time. kerf
|
|
54
|
+
Claude Code sessions burn through tokens fast — context overhead, MCP tools, bloated CLAUDE.md files — and there's no way to see it in real time. kerf fixes that with live dashboards, pre-flight estimates, budgets, and ghost token auditing.
|
|
49
55
|
|
|
50
56
|
---
|
|
51
57
|
|
|
52
58
|
## Installation
|
|
53
59
|
|
|
54
60
|
```bash
|
|
55
|
-
# No install needed — run directly
|
|
61
|
+
# No install needed — run directly via npx
|
|
56
62
|
npx kerf-cli@latest --help
|
|
57
63
|
|
|
58
|
-
# Or install globally
|
|
64
|
+
# Or install globally for the shorter 'kerf' command
|
|
59
65
|
npm install -g kerf-cli
|
|
66
|
+
kerf --help
|
|
60
67
|
```
|
|
61
68
|
|
|
62
69
|
### First-time setup
|
|
63
70
|
|
|
64
71
|
```bash
|
|
65
|
-
|
|
72
|
+
kerf init
|
|
66
73
|
```
|
|
67
74
|
|
|
68
75
|
Creates `~/.kerf/` directory, initializes the SQLite database, and optionally installs Claude Code hooks for automatic tracking.
|
|
@@ -73,12 +80,12 @@ Creates `~/.kerf/` directory, initializes the SQLite database, and optionally in
|
|
|
73
80
|
|
|
74
81
|
### Live monitoring (most common workflow)
|
|
75
82
|
|
|
76
|
-
Run Claude Code in one tab, kerf
|
|
83
|
+
Run Claude Code in one tab, kerf in another:
|
|
77
84
|
|
|
78
85
|
```
|
|
79
|
-
Terminal Tab 1 (Claude Code): Terminal Tab 2 (kerf
|
|
86
|
+
Terminal Tab 1 (Claude Code): Terminal Tab 2 (kerf):
|
|
80
87
|
┌──────────────────────────┐ ┌──────────────────────────┐
|
|
81
|
-
│ $ claude │ │ $
|
|
88
|
+
│ $ claude │ │ $ kerf watch │
|
|
82
89
|
│ │ │ │
|
|
83
90
|
│ > Fix the auth bug in │ │ >> $1.20 / ~$8.00 window │
|
|
84
91
|
│ src/auth/login.ts │ │ [████░░░░░░] 18% │
|
|
@@ -88,42 +95,42 @@ Terminal Tab 1 (Claude Code): Terminal Tab 2 (kerf-cli):
|
|
|
88
95
|
└──────────────────────────┘ └──────────────────────────┘
|
|
89
96
|
```
|
|
90
97
|
|
|
91
|
-
|
|
98
|
+
Auto-detects the active session. Press `q` to quit, `b` to toggle budget view.
|
|
92
99
|
|
|
93
100
|
### Before starting work
|
|
94
101
|
|
|
95
102
|
```bash
|
|
96
|
-
|
|
97
|
-
|
|
103
|
+
kerf estimate 'refactor the auth module'
|
|
104
|
+
kerf budget show
|
|
98
105
|
```
|
|
99
106
|
|
|
100
107
|
### End-of-day review
|
|
101
108
|
|
|
102
109
|
```bash
|
|
103
|
-
|
|
104
|
-
|
|
110
|
+
kerf report
|
|
111
|
+
kerf report --sessions
|
|
105
112
|
```
|
|
106
113
|
|
|
107
114
|
---
|
|
108
115
|
|
|
109
116
|
## Features
|
|
110
117
|
|
|
111
|
-
### Real-Time Dashboard — `kerf
|
|
118
|
+
### Real-Time Dashboard — `kerf watch`
|
|
112
119
|
|
|
113
120
|
Live cost monitoring with burn rate, context usage, and projected costs. Refreshes every 2 seconds.
|
|
114
121
|
|
|
115
122
|
```bash
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
123
|
+
kerf watch # auto-find active session
|
|
124
|
+
kerf watch --session abc123 # specific session
|
|
125
|
+
kerf watch --interval 5000 # slower refresh
|
|
119
126
|
```
|
|
120
127
|
|
|
121
|
-
### Pre-Flight Estimation — `kerf
|
|
128
|
+
### Pre-Flight Estimation — `kerf estimate`
|
|
122
129
|
|
|
123
130
|
Know what a task will cost before you start.
|
|
124
131
|
|
|
125
132
|
```bash
|
|
126
|
-
$
|
|
133
|
+
$ kerf estimate 'refactor auth module'
|
|
127
134
|
|
|
128
135
|
╭──────────────────────────────────────────────────────────╮
|
|
129
136
|
│ kerf-cli estimate: 'refactor auth module' │
|
|
@@ -142,7 +149,7 @@ $ npx kerf-cli estimate 'refactor auth module'
|
|
|
142
149
|
Compare all models side by side:
|
|
143
150
|
|
|
144
151
|
```bash
|
|
145
|
-
$
|
|
152
|
+
$ kerf estimate --compare 'add feature'
|
|
146
153
|
|
|
147
154
|
Model Turns Low Expected High
|
|
148
155
|
----------------------------------------------------------
|
|
@@ -154,7 +161,7 @@ $ npx kerf-cli estimate --compare 'add feature'
|
|
|
154
161
|
Priciest: opus at $5.24
|
|
155
162
|
```
|
|
156
163
|
|
|
157
|
-
Task complexity is detected from keywords:
|
|
164
|
+
Task complexity is auto-detected from keywords:
|
|
158
165
|
|
|
159
166
|
| Complexity | Keywords | Estimated Turns |
|
|
160
167
|
|-----------|----------|-----------------|
|
|
@@ -163,20 +170,20 @@ Task complexity is detected from keywords:
|
|
|
163
170
|
| Complex | refactor, rewrite, build, implement, migrate | 15-40 |
|
|
164
171
|
|
|
165
172
|
```bash
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
173
|
+
kerf estimate 'fix bug' --model opus # specific model
|
|
174
|
+
kerf estimate 'add auth' --files 'src/auth/*' # with file context
|
|
175
|
+
kerf estimate 'fix bug' --json # JSON output
|
|
169
176
|
```
|
|
170
177
|
|
|
171
|
-
### Per-Project Budgets — `kerf
|
|
178
|
+
### Per-Project Budgets — `kerf budget`
|
|
172
179
|
|
|
173
180
|
Set spending limits with automatic warnings.
|
|
174
181
|
|
|
175
182
|
```bash
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
183
|
+
kerf budget set 50 --period weekly # set budget
|
|
184
|
+
kerf budget show # check status
|
|
185
|
+
kerf budget list # all projects
|
|
186
|
+
kerf budget remove # remove budget
|
|
180
187
|
```
|
|
181
188
|
|
|
182
189
|
```
|
|
@@ -190,12 +197,12 @@ npx kerf-cli budget remove # remove budget
|
|
|
190
197
|
|
|
191
198
|
With hooks installed, you get warnings at 80% and alerts at 100%.
|
|
192
199
|
|
|
193
|
-
### Ghost Token Audit — `kerf
|
|
200
|
+
### Ghost Token Audit — `kerf audit`
|
|
194
201
|
|
|
195
202
|
Find invisible token waste eating your context window.
|
|
196
203
|
|
|
197
204
|
```bash
|
|
198
|
-
$
|
|
205
|
+
$ kerf audit
|
|
199
206
|
|
|
200
207
|
Context Window Health: B (62% usable)
|
|
201
208
|
|
|
@@ -215,20 +222,20 @@ $ npx kerf-cli audit
|
|
|
215
222
|
|
|
216
223
|
**Ghost tokens** are context consumed before your conversation starts: system prompt, built-in tools, MCP tools (~600 tokens each), CLAUDE.md, and autocompact buffer.
|
|
217
224
|
|
|
218
|
-
**CLAUDE.md attention curve:** Claude's attention is U-shaped. Rules at 0-30% and 70-100% get high attention. The 30-70% middle is a "dead zone." kerf
|
|
225
|
+
**CLAUDE.md attention curve:** Claude's attention is U-shaped. Rules at 0-30% and 70-100% get high attention. The 30-70% middle is a "dead zone." kerf flags critical rules (NEVER, ALWAYS, MUST) stuck there.
|
|
219
226
|
|
|
220
227
|
```bash
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
228
|
+
kerf audit --claude-md-only # per-section breakdown with attention zones
|
|
229
|
+
kerf audit --mcp-only # MCP server analysis
|
|
230
|
+
kerf audit --json # machine-readable output
|
|
224
231
|
```
|
|
225
232
|
|
|
226
|
-
### Historical Reports — `kerf
|
|
233
|
+
### Historical Reports — `kerf report`
|
|
227
234
|
|
|
228
235
|
Track spending over time with hourly charts and model breakdowns.
|
|
229
236
|
|
|
230
237
|
```bash
|
|
231
|
-
$
|
|
238
|
+
$ kerf report
|
|
232
239
|
|
|
233
240
|
kerf-cli report -- Sat, Apr 4, 2026
|
|
234
241
|
|
|
@@ -245,11 +252,11 @@ $ npx kerf-cli report
|
|
|
245
252
|
```
|
|
246
253
|
|
|
247
254
|
```bash
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
255
|
+
kerf report --period week # weekly
|
|
256
|
+
kerf report --period month # monthly
|
|
257
|
+
kerf report --sessions --model # per-session + per-model breakdown
|
|
258
|
+
kerf report --csv > costs.csv # export CSV
|
|
259
|
+
kerf report --json # export JSON
|
|
253
260
|
```
|
|
254
261
|
|
|
255
262
|
### Hooks — Automatic Tracking
|
|
@@ -260,9 +267,9 @@ Claude Code hooks run automatically during sessions:
|
|
|
260
267
|
- **Stop hook:** Checks budget and warns at 80%, alerts at 100%
|
|
261
268
|
|
|
262
269
|
```bash
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
270
|
+
kerf init # install hooks for current project
|
|
271
|
+
kerf init --global # install globally
|
|
272
|
+
kerf init --no-hooks # database only, skip hooks
|
|
266
273
|
```
|
|
267
274
|
|
|
268
275
|
---
|
|
@@ -271,27 +278,29 @@ npx kerf-cli init --no-hooks # database only, skip hooks
|
|
|
271
278
|
|
|
272
279
|
| Command | Description |
|
|
273
280
|
|---------|-------------|
|
|
274
|
-
| `
|
|
275
|
-
| `
|
|
276
|
-
| `
|
|
277
|
-
| `
|
|
278
|
-
| `
|
|
279
|
-
| `
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
281
|
+
| `kerf watch` | Real-time cost dashboard (default) |
|
|
282
|
+
| `kerf estimate <task>` | Pre-flight cost estimation |
|
|
283
|
+
| `kerf estimate --compare <task>` | Compare Sonnet vs Opus vs Haiku |
|
|
284
|
+
| `kerf budget set <amt> --period weekly` | Set project budget |
|
|
285
|
+
| `kerf budget show` | Check budget status |
|
|
286
|
+
| `kerf budget list` | List all project budgets |
|
|
287
|
+
| `kerf budget remove` | Remove budget |
|
|
288
|
+
| `kerf audit` | Ghost token & CLAUDE.md audit |
|
|
289
|
+
| `kerf audit --claude-md-only` | CLAUDE.md section analysis |
|
|
290
|
+
| `kerf audit --mcp-only` | MCP server analysis |
|
|
291
|
+
| `kerf report` | Today's cost report |
|
|
292
|
+
| `kerf report --period week` | Weekly report |
|
|
293
|
+
| `kerf report --csv` | Export as CSV |
|
|
294
|
+
| `kerf init` | First-time setup |
|
|
295
|
+
|
|
296
|
+
> All commands work with both `kerf` and `kerf-cli`.
|
|
288
297
|
|
|
289
298
|
---
|
|
290
299
|
|
|
291
|
-
## Why kerf
|
|
300
|
+
## Why kerf?
|
|
292
301
|
|
|
293
|
-
| Feature | kerf
|
|
294
|
-
|
|
302
|
+
| Feature | kerf | RTK | ccusage | token-optimizer |
|
|
303
|
+
|---------|------|-----|---------|-----------------|
|
|
295
304
|
| Real-time dashboard | Yes | No | No | No |
|
|
296
305
|
| Pre-flight estimation | Yes | No | No | No |
|
|
297
306
|
| Per-project budgets | Yes | No | No | No |
|
|
@@ -308,8 +317,8 @@ Works alongside RTK, ccusage, and ECC.
|
|
|
308
317
|
|
|
309
318
|
## Tips
|
|
310
319
|
|
|
311
|
-
- **Use Sonnet for implementation, Opus for planning** — check with `estimate --compare`
|
|
312
|
-
- **Keep CLAUDE.md under 200 lines** — audit with `audit --claude-md-only`
|
|
320
|
+
- **Use Sonnet for implementation, Opus for planning** — check with `kerf estimate --compare`
|
|
321
|
+
- **Keep CLAUDE.md under 200 lines** — audit with `kerf audit --claude-md-only`
|
|
313
322
|
- **Disable unused MCP servers** — each tool costs ~600 tokens
|
|
314
323
|
- **Monitor cache hit rate** — high rates (>80%) mean efficient context reuse
|
|
315
324
|
- **Set weekly budgets** — enough flexibility without runaway costs
|
|
@@ -322,40 +331,21 @@ Works alongside RTK, ccusage, and ECC.
|
|
|
322
331
|
|---------|----------|
|
|
323
332
|
| "No active session found" | Ensure Claude Code is running and has sent a message |
|
|
324
333
|
| Dashboard shows no data | Send a message in Claude Code, wait for response |
|
|
325
|
-
| Costs seem wrong | kerf
|
|
334
|
+
| Costs seem wrong | kerf uses `total_cost_usd` from logs when available; estimates use heuristic |
|
|
326
335
|
| Command not found | Use `npx kerf-cli@latest` or `npm install -g kerf-cli` |
|
|
327
|
-
| Database errors | `rm ~/.kerf/kerf.db &&
|
|
336
|
+
| Database errors | `rm ~/.kerf/kerf.db && kerf init` |
|
|
328
337
|
| Watch crashes | Must run in an interactive terminal, not piped |
|
|
329
338
|
|
|
330
339
|
---
|
|
331
340
|
|
|
332
|
-
## Changelog
|
|
333
|
-
|
|
334
|
-
### v0.1.4 (2026-04-04)
|
|
335
|
-
- Fix: `--version` now reads dynamically from package.json
|
|
336
|
-
- Fix: `--compare` shows proper side-by-side table for all 3 models
|
|
337
|
-
- Fix: `watch` gracefully exits in non-TTY environments
|
|
338
|
-
- Fix: CLAUDE.md detection searches git root and `~/.claude/`
|
|
339
|
-
- Fix: `--claude-md-only` shows per-section breakdown with attention zones
|
|
340
|
-
- Fix: Hourly report dates no longer show "Invalid Date"
|
|
341
|
-
|
|
342
|
-
### v0.1.3 (2026-04-04)
|
|
343
|
-
- Fix: CLAUDE.md found via git root, not just cwd
|
|
344
|
-
- Fix: Audit filtering for `--claude-md-only` and `--mcp-only`
|
|
345
|
-
- Fix: Hourly report date parsing
|
|
346
|
-
|
|
347
|
-
### v0.1.1 (2026-04-04)
|
|
348
|
-
- Fix: ContextBar crash when token usage exceeds 100%
|
|
349
|
-
|
|
350
|
-
### v0.1.0 (2026-04-04)
|
|
351
|
-
- Initial release: watch, estimate, budget, audit, report, init
|
|
352
|
-
|
|
353
|
-
---
|
|
354
|
-
|
|
355
341
|
## Architecture
|
|
356
342
|
|
|
357
343
|
See [ARCHITECTURE.md](ARCHITECTURE.md) for project structure, design decisions, data flow, and technology choices.
|
|
358
344
|
|
|
345
|
+
## Changelog
|
|
346
|
+
|
|
347
|
+
See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
348
|
+
|
|
359
349
|
---
|
|
360
350
|
|
|
361
351
|
## Contributing
|