meter-ai 0.3.0 → 0.3.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.
Files changed (2) hide show
  1. package/README.md +69 -32
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,16 +2,30 @@
2
2
 
3
3
  **Intelligent CLI wrapper for Claude Code** — pre-task cost estimation, live status bar, budget protection.
4
4
 
5
- meter sits transparently between you and Claude Code via PATH shimming. You keep typing `claude` exactly as before. meter adds:
5
+ ## Why I Built This
6
6
 
7
- - **Pre-task estimation** — know what a task will cost before it runs
7
+ I'm a student. My budget is tight, but my urge to build things is not. I think about projects in my sleep. I wake up and start coding. I use Claude Code every single day to build tools that empower myself and the community around me.
8
+
9
+ But here's the thing — I had no idea what any of it cost. I'd run a prompt, Claude would do its thing, and at the end of the month I'd stare at a bill wondering which Tuesday afternoon wiped out half my budget. Or worse, I'd hit my 5-hour rate limit wall right in the middle of something important and have to stop dead.
10
+
11
+ I built meter so I could see what my actions actually cost. Not after the fact — but as I work. Every prompt, every task, every session. Because when you're a student building on a budget, awareness is the difference between building sustainably and burning out your credits in a week.
12
+
13
+ If you're in the same boat — stretching every dollar, every token, every rate limit window — this is for you.
14
+
15
+ ---
16
+
17
+ ## What It Does
18
+
19
+ meter sits transparently between you and Claude Code. You keep typing `claude` exactly as before. meter adds:
20
+
21
+ - **Per-prompt estimation** — see the estimated cost of each prompt in Claude Code's statusline
8
22
  - **Live status bar** — ambient cost/usage ticker while the agent works
9
- - **Budget protection** — non-blocking notification when thresholds are hit, with one-keypress model switching
23
+ - **Budget protection** — notifications when thresholds are hit, with model switching
24
+ - **Session history** — track what you spent, on what, and learn your patterns
10
25
  - **Works for both API users and plan subscribers**
11
26
 
12
27
  ```
13
- $ claude "refactor the auth layer"
14
- ◆ meter claude-opus ~$0.38 heavy ████████████░░░░ 68% 5hr window | $0.12 elapsed
28
+ ◆ meter claude-opus ~$0.38 heavy │ 68% 5hr window reset in 2h 14m
15
29
  ```
16
30
 
17
31
  ## Install
@@ -22,19 +36,28 @@ meter init
22
36
  # restart your terminal
23
37
  ```
24
38
 
25
- That's it. `meter init` detects your shell, finds the real `claude` binary, sets up a transparent shim, and writes your config. From now on, every `claude` invocation runs through meter automatically.
39
+ That's it. `meter init` detects your shell, finds the real `claude` binary, sets up a transparent shim, installs estimation hooks into Claude Code, and writes your config. From that point on, every `claude` invocation runs through meter automatically.
26
40
 
27
41
  ## How It Works
28
42
 
29
- meter uses a PTY (pseudo-terminal) wrapper — the same mechanism used by VS Code's integrated terminal, tmux, and asciinema. Claude Code runs inside a PTY slave and believes it owns a real terminal. meter is the PTY master: it passes all I/O through unchanged while injecting a status bar at the bottom of your terminal.
43
+ meter integrates with Claude Code in two ways:
30
44
 
31
- ### For API users (paying per token)
45
+ ### 1. Claude Code Hooks (interactive sessions)
32
46
 
33
- ```
34
- ◆ meter claude-opus ~$0.38 heavy │ ████████████░░░░ $0.21 / $0.50
35
- ```
47
+ When you launch `claude` interactively, meter hooks into Claude Code's native event system:
48
+
49
+ - **`UserPromptSubmit` hook** — runs the estimation pipeline every time you submit a prompt
50
+ - **Statusline integration** — displays the estimate in Claude Code's own bottom bar
51
+
52
+ This means you see the cost estimation right inside Claude Code's UI, alongside your existing statusline info. No separate window, no terminal conflicts.
36
53
 
37
- meter tracks actual dollar cost in real time. When your per-task budget threshold is hit, you get a non-blocking notification:
54
+ ### 2. PTY Wrapper (non-interactive / one-shot commands)
55
+
56
+ When you run `claude "fix the bug"` with a prompt argument, meter wraps the process in a PTY and shows a live status bar with real-time cost tracking.
57
+
58
+ ### For API users (paying per token)
59
+
60
+ meter tracks actual dollar cost. When your per-task budget threshold is hit:
38
61
 
39
62
  ```
40
63
  ⚠ 80% budget hit ($0.40/$0.50) [s]witch to sonnet [d]ismiss [c]ancel
@@ -42,31 +65,36 @@ meter tracks actual dollar cost in real time. When your per-task budget threshol
42
65
 
43
66
  ### For plan users (Claude Max, Pro)
44
67
 
45
- ```
46
- ◆ meter claude-opus ~$0.38 heavy │ ████████████░░░░ 68% 5hr window reset in 2h 14m
47
- ```
48
-
49
- meter polls your 5-hour usage window percentage and warns before you hit the rate limit wall mid-task.
68
+ meter tracks your 5-hour usage window percentage and warns before you hit the rate limit wall mid-task.
50
69
 
51
- ## Pre-Task Estimation
70
+ ## Pre-Prompt Estimation
52
71
 
53
72
  meter estimates task cost/weight using a three-layer pipeline:
54
73
 
55
74
  1. **Heuristics** (~50ms, free) — keyword scoring + repo size analysis
56
- 2. **Historical baseline** (~10ms, free) — trigram similarity against your past tasks
57
- 3. **LLM pre-call** (~1-2s, ~$0.0001) — only fires on ambiguous tasks
75
+ 2. **Historical baseline** (~10ms, free) — trigram similarity against your past tasks in `~/.meter/history.db`
76
+ 3. **LLM pre-call** (~1-2s, ~$0.0001) — only fires on ambiguous tasks, asks Haiku for a one-word complexity classification
77
+
78
+ Simple tasks never hit layer 3. The pipeline gets smarter over time as your history builds up — Layer 2 learns from your real usage patterns and replaces guesswork with data.
79
+
80
+ ### Cost estimates by complexity
58
81
 
59
- Simple tasks never hit layer 3. The estimate shows instantly and the agent starts immediately — no confirmation gate, no pause.
82
+ | Complexity | Estimated cost |
83
+ |---|---|
84
+ | low | ~$0.02 |
85
+ | medium | ~$0.09 |
86
+ | heavy | ~$0.38 |
87
+ | critical | ~$0.80 |
60
88
 
61
89
  ## Commands
62
90
 
63
91
  ```bash
64
- meter init # Set up PATH shim and config
92
+ meter init # Set up shim, hooks, and config
65
93
  meter status # Show current mode, model, usage, and config
66
94
  meter report # Weekly digest of usage and costs
67
95
  meter history # Browse past task records
68
96
  meter config # View and set budgets, thresholds, model chain
69
- meter uninstall # Clean removal of all shims and data
97
+ meter uninstall # Clean removal of all shims, hooks, and data
70
98
  ```
71
99
 
72
100
  ### Configuration
@@ -93,18 +121,27 @@ All data stays local. No telemetry, no cloud, no accounts.
93
121
 
94
122
  ```
95
123
  ~/.meter/
96
- config.json # Mode, budgets, thresholds, resolved binary path
97
- history.db # SQLite: task history, costs, estimates
98
- pricing.json # Model pricing table (updated weekly)
99
- bin/claude # PATH shim
100
- cache/ # Usage data, session state
101
- reports/ # Weekly digest snapshots
124
+ config.json # Mode, budgets, thresholds, resolved binary path
125
+ history.db # SQLite: task history, costs, estimates
126
+ hooks/
127
+ on-prompt.js # Claude Code UserPromptSubmit hook
128
+ statusline.js # Claude Code statusline command
129
+ bin/claude # PATH shim
130
+ cache/
131
+ latest-estimate.json # Most recent estimation result
132
+ reports/ # Weekly digest snapshots
102
133
  ```
103
134
 
135
+ ## Known Limitations
136
+
137
+ **Estimation timing in interactive sessions.** Claude Code's hook system fires the `UserPromptSubmit` event *when* the prompt is submitted, not before. This means the estimation appears in the statusline as Claude is already processing your prompt — you see the cost *during* execution, not before you press Enter. This is a platform limitation of Claude Code's hook architecture, not a meter limitation. If Anthropic adds a pre-submit hook in the future, meter will support it immediately.
138
+
139
+ **What this means in practice:** You won't get a "this will cost $X, proceed?" gate before each prompt. Instead, meter gives you ambient awareness — you see the estimated cost of each prompt as it runs, learn your patterns over time, and build intuition for what's expensive. The `meter report` and `meter history` commands help you review and learn from your spending.
140
+
104
141
  ## Uninstall
105
142
 
106
143
  ```bash
107
- meter uninstall # Removes shim and PATH entry
144
+ meter uninstall # Removes shim, hooks, and PATH entry
108
145
  npm uninstall -g meter-ai
109
146
  ```
110
147
 
@@ -113,11 +150,11 @@ npm uninstall -g meter-ai
113
150
  - **v1.1** — Aider support
114
151
  - **v1.2** — Gemini CLI support
115
152
  - **v1.3** — Codex CLI support
116
- - **v2.0** — CSV/JSON export, `--dry-run` estimation, team usage sharing
153
+ - **v2.0** — Session cost summary on exit, `meter estimate "prompt"` pre-check command, CSV/JSON export
117
154
 
118
155
  ## Support
119
156
 
120
- If meter saved you from a surprise bill or a rate limit wall, consider [buying me a coffee](https://buymeacoffee.com/catancs).
157
+ I built this as a student, for students and solo devs who care about every dollar. If meter helped you understand your AI spending better, consider [buying me a coffee](https://buymeacoffee.com/catancs).
121
158
 
122
159
  ## License
123
160
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "meter-ai",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Intelligent CLI wrapper for Claude Code — pre-task cost estimation, live status bar, budget protection",
5
5
  "bin": {
6
6
  "meter": "dist/index.js"