kerf-cli 0.1.0

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.
Files changed (10) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/LICENSE +21 -0
  3. package/README.md +177 -0
  4. package/dist/index.js +1704 -0
  5. package/dist/index.js.map +1 -0
  6. package/kerf@0.1.0 +0 -0
  7. package/npm +0 -0
  8. package/package.json +49 -0
  9. package/tsup +0 -0
  10. package/vitest +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,12 @@
1
+ # Changelog
2
+
3
+ ## v0.1.0 (2026-04-04)
4
+
5
+ Initial release.
6
+
7
+ - `kerf watch` — Real-time cost dashboard
8
+ - `kerf estimate <task>` — Pre-flight cost estimation
9
+ - `kerf budget set/show/list/remove` — Per-project budget management
10
+ - `kerf audit` — Ghost token & CLAUDE.md audit
11
+ - `kerf report` — Historical cost reports
12
+ - `kerf init` — Setup hooks and database
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dhanush Kumar Sivaji
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,177 @@
1
+ # kerf
2
+
3
+ **Cost intelligence for Claude Code. Know before you spend.**
4
+
5
+ > *kerf (n.) — the width of material removed by a cutting tool. Every token operation has a kerf.*
6
+
7
+ [![npm version](https://img.shields.io/npm/v/kerf)](https://www.npmjs.com/package/kerf)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9
+ [![Node 20+](https://img.shields.io/badge/node-20%2B-green.svg)]()
10
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)]()
11
+
12
+ ```
13
+ ┌──────────────────────────────────────────────────────────────┐
14
+ │ kerf watch | session: a3f8c2d1... | 47 messages (q=quit) │
15
+ ├──────────────────────────────────────────────────────────────┤
16
+ │ >> $4.82 / ~$15.00 window | $0.18/min | ~56m remaining │
17
+ │ [████████████░░░░░░░░░░░░░░░░░░] 38% | 76K / 200K tokens │
18
+ │ system(14K) + tools(15K) + mcp(8K) + conversation(39K) │
19
+ │ │
20
+ │ Recent Messages: │
21
+ │ 10:45:02 3.2K tok $0.12 │
22
+ │ 10:47:18 5.1K tok $0.24 │
23
+ │ 10:49:55 2.8K tok $0.09 │
24
+ └──────────────────────────────────────────────────────────────┘
25
+ ```
26
+
27
+ ---
28
+
29
+ ## The Problem
30
+
31
+ > "20x Max plan exhausted in 19 minutes"
32
+
33
+ You don't know what you're spending until it's gone. Claude Code sessions burn through tokens fast — context overhead, MCP tools, bloated CLAUDE.md files — and there's no way to see it happening in real time.
34
+
35
+ **kerf fixes that.**
36
+
37
+ ---
38
+
39
+ ## Quick Start
40
+
41
+ ```bash
42
+ npx kerf@latest init # Set up hooks & database
43
+ npx kerf@latest watch # Real-time cost dashboard
44
+ npx kerf@latest audit # Find ghost token waste
45
+ ```
46
+
47
+ ---
48
+
49
+ ## Features
50
+
51
+ ### Real-Time Dashboard — `kerf watch`
52
+
53
+ Live cost monitoring while Claude Code runs. See your burn rate, context usage, and projected costs.
54
+
55
+ ### Pre-Flight Estimation — `kerf estimate <task>`
56
+
57
+ Know the cost before you start.
58
+
59
+ ```bash
60
+ $ kerf estimate 'refactor auth module'
61
+
62
+ ╭───────────────────────────────────────────────────────���──╮
63
+ │ kerf estimate: 'refactor auth module' │
64
+ │ │
65
+ │ Model: Sonnet 4 │
66
+ │ Estimated turns: 15-40 (expected: 25) │
67
+ │ Context overhead: 62.7K tokens (ghost tokens) │
68
+ │ │
69
+ │ Estimated Cost: │
70
+ │ Low: $2.10 │
71
+ │ Expected: $5.80 │
72
+ │ High: $12.40 │
73
+ │ │
74
+ │ -> Using Opus would cost ~$29.00 (5x more) │
75
+ ╰──────────────────────────────────────────────────────────╯
76
+ ```
77
+
78
+ ### Per-Project Budgets — `kerf budget`
79
+
80
+ Set spending limits and get warnings before you go over.
81
+
82
+ ```bash
83
+ kerf budget set 50 --period weekly
84
+ kerf budget show
85
+ kerf budget list
86
+ ```
87
+
88
+ ### Ghost Token Audit — `kerf audit`
89
+
90
+ Find and fix invisible token waste: system prompt overhead, MCP tool bloat, CLAUDE.md dead zones.
91
+
92
+ ```bash
93
+ $ kerf audit
94
+
95
+ Context Window Health: B (62% usable)
96
+
97
+ Ghost Token Breakdown:
98
+ System prompt: 14,328 tokens (7.2%)
99
+ Built-in tools: 15,000 tokens (7.5%)
100
+ MCP tools (3 srv): 8,400 tokens (4.2%)
101
+ CLAUDE.md: 2,100 tokens (1.1%)
102
+ Autocompact buffer:33,000 tokens (16.5%)
103
+
104
+ Recommendations:
105
+ 1. [HIGH] Reorder CLAUDE.md critical rules
106
+ 2. [MED] Disable unused 'playwright' MCP server
107
+ ```
108
+
109
+ ### Historical Reports — `kerf report`
110
+
111
+ Track spending over time with per-model and per-session breakdowns.
112
+
113
+ ```bash
114
+ kerf report # Today's costs
115
+ kerf report --period week # Weekly summary
116
+ kerf report --csv # Export for spreadsheets
117
+ kerf report --sessions # Per-session breakdown
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Why kerf?
123
+
124
+ | Feature | kerf | RTK | ccusage | token-optimizer |
125
+ |---------|------|-----|---------|-----------------|
126
+ | Real-time dashboard | Yes | No | No | No |
127
+ | Pre-flight estimation | Yes | No | No | No |
128
+ | Per-project budgets | Yes | No | No | No |
129
+ | Ghost token audit | Yes | No | No | Partial |
130
+ | CLAUDE.md optimization | Yes | No | No | Yes |
131
+ | Historical reports | Yes | No | Yes | No |
132
+ | Hook-based tracking | Yes | No | No | No |
133
+
134
+ **RTK compresses. ccusage tracks. kerf predicts.**
135
+
136
+ ---
137
+
138
+ ## Works With
139
+
140
+ - **RTK** — complementary (kerf shows savings from RTK compression)
141
+ - **ccusage** — compatible (kerf can import historical data)
142
+ - **ECC** — compatible hooks
143
+
144
+ ---
145
+
146
+ ## All Commands
147
+
148
+ | Command | Description |
149
+ |---------|-------------|
150
+ | `kerf` / `kerf watch` | Real-time cost dashboard (default) |
151
+ | `kerf estimate <task>` | Pre-flight cost estimation |
152
+ | `kerf budget set <amt>` | Set project budget |
153
+ | `kerf budget show` | Show current budget status |
154
+ | `kerf budget list` | List all project budgets |
155
+ | `kerf audit` | Ghost token & CLAUDE.md audit |
156
+ | `kerf audit --fix` | Auto-apply safe optimizations |
157
+ | `kerf report` | Historical cost reports |
158
+ | `kerf init` | Set up kerf (hooks, database) |
159
+
160
+ ---
161
+
162
+ ## Contributing
163
+
164
+ Contributions welcome! Please open an issue first to discuss what you'd like to change.
165
+
166
+ ```bash
167
+ git clone https://github.com/dhanushkumarsivaji/kerf.git
168
+ cd kerf
169
+ npm install
170
+ npm test
171
+ ```
172
+
173
+ ---
174
+
175
+ ## License
176
+
177
+ [MIT](LICENSE) - Dhanush Kumar Sivaji