kerf-cli 0.1.1 → 0.1.3
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 +11 -6
- package/README.md +37 -32
- package/USAGE.md +644 -0
- package/dist/index.js +87 -30
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.1.1 (2026-04-04)
|
|
4
|
+
|
|
5
|
+
- Fix: ContextBar crash when token usage exceeds 100% of context window
|
|
6
|
+
- Fix: Package published as `kerf-cli` (npm blocked unscoped `kerf`)
|
|
7
|
+
|
|
3
8
|
## v0.1.0 (2026-04-04)
|
|
4
9
|
|
|
5
10
|
Initial release.
|
|
6
11
|
|
|
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
|
|
12
|
+
- `npx kerf-cli watch` — Real-time cost dashboard
|
|
13
|
+
- `npx kerf-cli estimate <task>` — Pre-flight cost estimation
|
|
14
|
+
- `npx kerf-cli budget set/show/list/remove` — Per-project budget management
|
|
15
|
+
- `npx kerf-cli audit` — Ghost token & CLAUDE.md audit
|
|
16
|
+
- `npx kerf-cli report` — Historical cost reports
|
|
17
|
+
- `npx kerf-cli init` — Setup hooks and database
|
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# kerf
|
|
1
|
+
# kerf-cli
|
|
2
2
|
|
|
3
3
|
**Cost intelligence for Claude Code. Know before you spend.**
|
|
4
4
|
|
|
5
5
|
> *kerf (n.) — the width of material removed by a cutting tool. Every token operation has a kerf.*
|
|
6
6
|
|
|
7
|
-
[](https://www.npmjs.com/package/kerf)
|
|
7
|
+
[](https://www.npmjs.com/package/kerf-cli)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[]()
|
|
10
10
|
[]()
|
|
@@ -32,16 +32,16 @@
|
|
|
32
32
|
|
|
33
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
34
|
|
|
35
|
-
**kerf fixes that.**
|
|
35
|
+
**kerf-cli fixes that.**
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
39
39
|
## Quick Start
|
|
40
40
|
|
|
41
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
|
|
42
|
+
npx kerf-cli@latest init # Set up hooks & database
|
|
43
|
+
npx kerf-cli@latest watch # Real-time cost dashboard
|
|
44
|
+
npx kerf-cli@latest audit # Find ghost token waste
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
---
|
|
@@ -57,9 +57,9 @@ Live cost monitoring while Claude Code runs. See your burn rate, context usage,
|
|
|
57
57
|
Know the cost before you start.
|
|
58
58
|
|
|
59
59
|
```bash
|
|
60
|
-
$ kerf estimate 'refactor auth module'
|
|
60
|
+
$ npx kerf-cli estimate 'refactor auth module'
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
╭──────────────────────────────────────────────────────────╮
|
|
63
63
|
│ kerf estimate: 'refactor auth module' │
|
|
64
64
|
│ │
|
|
65
65
|
│ Model: Sonnet 4 │
|
|
@@ -80,9 +80,9 @@ $ kerf estimate 'refactor auth module'
|
|
|
80
80
|
Set spending limits and get warnings before you go over.
|
|
81
81
|
|
|
82
82
|
```bash
|
|
83
|
-
kerf budget set 50 --period weekly
|
|
84
|
-
kerf budget show
|
|
85
|
-
kerf budget list
|
|
83
|
+
npx kerf-cli budget set 50 --period weekly
|
|
84
|
+
npx kerf-cli budget show
|
|
85
|
+
npx kerf-cli budget list
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
### Ghost Token Audit — `kerf audit`
|
|
@@ -90,7 +90,7 @@ kerf budget list
|
|
|
90
90
|
Find and fix invisible token waste: system prompt overhead, MCP tool bloat, CLAUDE.md dead zones.
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
$ kerf audit
|
|
93
|
+
$ npx kerf-cli audit
|
|
94
94
|
|
|
95
95
|
Context Window Health: B (62% usable)
|
|
96
96
|
|
|
@@ -111,18 +111,18 @@ $ kerf audit
|
|
|
111
111
|
Track spending over time with per-model and per-session breakdowns.
|
|
112
112
|
|
|
113
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
|
|
114
|
+
npx kerf-cli report # Today's costs
|
|
115
|
+
npx kerf-cli report --period week # Weekly summary
|
|
116
|
+
npx kerf-cli report --csv # Export for spreadsheets
|
|
117
|
+
npx kerf-cli report --sessions # Per-session breakdown
|
|
118
118
|
```
|
|
119
119
|
|
|
120
120
|
---
|
|
121
121
|
|
|
122
|
-
## Why kerf?
|
|
122
|
+
## Why kerf-cli?
|
|
123
123
|
|
|
124
|
-
| Feature | kerf | RTK | ccusage | token-optimizer |
|
|
125
|
-
|
|
124
|
+
| Feature | kerf-cli | RTK | ccusage | token-optimizer |
|
|
125
|
+
|---------|----------|-----|---------|-----------------|
|
|
126
126
|
| Real-time dashboard | Yes | No | No | No |
|
|
127
127
|
| Pre-flight estimation | Yes | No | No | No |
|
|
128
128
|
| Per-project budgets | Yes | No | No | No |
|
|
@@ -137,8 +137,8 @@ kerf report --sessions # Per-session breakdown
|
|
|
137
137
|
|
|
138
138
|
## Works With
|
|
139
139
|
|
|
140
|
-
- **RTK** — complementary (kerf shows savings from RTK compression)
|
|
141
|
-
- **ccusage** — compatible (kerf can import historical data)
|
|
140
|
+
- **RTK** — complementary (kerf-cli shows savings from RTK compression)
|
|
141
|
+
- **ccusage** — compatible (kerf-cli can import historical data)
|
|
142
142
|
- **ECC** — compatible hooks
|
|
143
143
|
|
|
144
144
|
---
|
|
@@ -147,15 +147,20 @@ kerf report --sessions # Per-session breakdown
|
|
|
147
147
|
|
|
148
148
|
| Command | Description |
|
|
149
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) |
|
|
150
|
+
| `npx kerf-cli` / `npx kerf-cli watch` | Real-time cost dashboard (default) |
|
|
151
|
+
| `npx kerf-cli estimate <task>` | Pre-flight cost estimation |
|
|
152
|
+
| `npx kerf-cli budget set <amt>` | Set project budget |
|
|
153
|
+
| `npx kerf-cli budget show` | Show current budget status |
|
|
154
|
+
| `npx kerf-cli budget list` | List all project budgets |
|
|
155
|
+
| `npx kerf-cli audit` | Ghost token & CLAUDE.md audit |
|
|
156
|
+
| `npx kerf-cli audit --fix` | Auto-apply safe optimizations |
|
|
157
|
+
| `npx kerf-cli report` | Historical cost reports |
|
|
158
|
+
| `npx kerf-cli init` | Set up kerf (hooks, database) |
|
|
159
|
+
|
|
160
|
+
**Tip:** Add an alias for convenience:
|
|
161
|
+
```bash
|
|
162
|
+
echo 'alias kerf="npx kerf-cli"' >> ~/.zshrc
|
|
163
|
+
```
|
|
159
164
|
|
|
160
165
|
---
|
|
161
166
|
|
|
@@ -164,8 +169,8 @@ kerf report --sessions # Per-session breakdown
|
|
|
164
169
|
Contributions welcome! Please open an issue first to discuss what you'd like to change.
|
|
165
170
|
|
|
166
171
|
```bash
|
|
167
|
-
git clone https://github.com/dhanushkumarsivaji/kerf.git
|
|
168
|
-
cd kerf
|
|
172
|
+
git clone https://github.com/dhanushkumarsivaji/kerf-cli.git
|
|
173
|
+
cd kerf-cli
|
|
169
174
|
npm install
|
|
170
175
|
npm test
|
|
171
176
|
```
|