meter-ai 0.2.0 → 0.3.1

package/README.md

@@ -2,16 +2,30 @@
 
 **Intelligent CLI wrapper for Claude Code** — pre-task cost estimation, live status bar, budget protection.
 
-meter sits transparently between you and Claude Code via PATH shimming. You keep typing `claude` exactly as before. meter adds:
+## Why I Built This
 
-- **Pre-task estimation** — know what a task will cost before it runs
+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.
+
+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.
+
+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.
+
+If you're in the same boat — stretching every dollar, every token, every rate limit window — this is for you.
+
+---
+
+## What It Does
+
+meter sits transparently between you and Claude Code. You keep typing `claude` exactly as before. meter adds:
+
+- **Per-prompt estimation** — see the estimated cost of each prompt in Claude Code's statusline
 - **Live status bar** — ambient cost/usage ticker while the agent works
-- **Budget protection** — non-blocking notification when thresholds are hit, with one-keypress model switching
+- **Budget protection** — notifications when thresholds are hit, with model switching
+- **Session history** — track what you spent, on what, and learn your patterns
 - **Works for both API users and plan subscribers**
 
 ```
-$ claude "refactor the auth layer"
-◆ meter  claude-opus  ~$0.38  heavy  ████████████░░░░  68% 5hr window  |  $0.12 elapsed
+◆ meter  claude-opus  ~$0.38  heavy  │  68% 5hr window  reset in 2h 14m
 ```
 
 ## Install
@@ -22,19 +36,28 @@ meter init
 # restart your terminal
 ```
 
-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.
+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.
 
 ## How It Works
 
-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.
+meter integrates with Claude Code in two ways:
 
-### For API users (paying per token)
+### 1. Claude Code Hooks (interactive sessions)
 
-```
-◆ meter  claude-opus  ~$0.38  heavy  │  ████████████░░░░  $0.21 / $0.50
-```
+When you launch `claude` interactively, meter hooks into Claude Code's native event system:
+
+- **`UserPromptSubmit` hook** — runs the estimation pipeline every time you submit a prompt
+- **Statusline integration** — displays the estimate in Claude Code's own bottom bar
+
+This means you see the cost estimation right inside Claude Code's UI, alongside your existing statusline info. No separate window, no terminal conflicts.
 
-meter tracks actual dollar cost in real time. When your per-task budget threshold is hit, you get a non-blocking notification:
+### 2. PTY Wrapper (non-interactive / one-shot commands)
+
+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.
+
+### For API users (paying per token)
+
+meter tracks actual dollar cost. When your per-task budget threshold is hit:
 
 ```
 ⚠  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
 
 ### For plan users (Claude Max, Pro)
 
-```
-◆ meter  claude-opus  ~$0.38  heavy  │  ████████████░░░░  68% 5hr window  reset in 2h 14m
-```
-
-meter polls your 5-hour usage window percentage and warns before you hit the rate limit wall mid-task.
+meter tracks your 5-hour usage window percentage and warns before you hit the rate limit wall mid-task.
 
-## Pre-Task Estimation
+## Pre-Prompt Estimation
 
 meter estimates task cost/weight using a three-layer pipeline:
 
 1. **Heuristics** (~50ms, free) — keyword scoring + repo size analysis
-2. **Historical baseline** (~10ms, free) — trigram similarity against your past tasks
-3. **LLM pre-call** (~1-2s, ~$0.0001) — only fires on ambiguous tasks
+2. **Historical baseline** (~10ms, free) — trigram similarity against your past tasks in `~/.meter/history.db`
+3. **LLM pre-call** (~1-2s, ~$0.0001) — only fires on ambiguous tasks, asks Haiku for a one-word complexity classification
+
+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.
+
+### Cost estimates by complexity
 
-Simple tasks never hit layer 3. The estimate shows instantly and the agent starts immediately — no confirmation gate, no pause.
+| Complexity | Estimated cost |
+|---|---|
+| low | ~$0.02 |
+| medium | ~$0.09 |
+| heavy | ~$0.38 |
+| critical | ~$0.80 |
 
 ## Commands
 
 ```bash
-meter init        # Set up PATH shim and config
+meter init        # Set up shim, hooks, and config
 meter status      # Show current mode, model, usage, and config
 meter report      # Weekly digest of usage and costs
 meter history     # Browse past task records
 meter config      # View and set budgets, thresholds, model chain
-meter uninstall   # Clean removal of all shims and data
+meter uninstall   # Clean removal of all shims, hooks, and data
 ```
 
 ### Configuration
@@ -93,18 +121,27 @@ All data stays local. No telemetry, no cloud, no accounts.
 
 ```
 ~/.meter/
-  config.json       # Mode, budgets, thresholds, resolved binary path
-  history.db        # SQLite: task history, costs, estimates
-  pricing.json      # Model pricing table (updated weekly)
-  bin/claude        # PATH shim
-  cache/            # Usage data, session state
-  reports/          # Weekly digest snapshots
+  config.json           # Mode, budgets, thresholds, resolved binary path
+  history.db            # SQLite: task history, costs, estimates
+  hooks/
+    on-prompt.js        # Claude Code UserPromptSubmit hook
+    statusline.js       # Claude Code statusline command
+  bin/claude            # PATH shim
+  cache/
+    latest-estimate.json  # Most recent estimation result
+  reports/              # Weekly digest snapshots
 ```
 
+## Known Limitations
+
+**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.
+
+**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.
+
 ## Uninstall
 
 ```bash
-meter uninstall       # Removes shim and PATH entry
+meter uninstall       # Removes shim, hooks, and PATH entry
 npm uninstall -g meter-ai
 ```
 
@@ -113,11 +150,11 @@ npm uninstall -g meter-ai
 - **v1.1** — Aider support
 - **v1.2** — Gemini CLI support
 - **v1.3** — Codex CLI support
-- **v2.0** — CSV/JSON export, `--dry-run` estimation, team usage sharing
+- **v2.0** — Session cost summary on exit, `meter estimate "prompt"` pre-check command, CSV/JSON export
 
 ## Support
 
-If meter saved you from a surprise bill or a rate limit wall, consider [buying me a coffee](https://buymeacoffee.com/catancs).
+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).
 
 ## License
 

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAmD9D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwD9D"}

package/dist/commands/init.js

@@ -1,5 +1,6 @@
-import { mkdir } from 'fs/promises';
-import { join } from 'path';
+import { mkdir, readFile, writeFile, copyFile, chmod } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { detectShell, getShellConfigPath } from '../shell/detect.js';
 import { resolveTrueBinary } from '../shell/binary-resolver.js';
 import { writeShim } from '../shell/shim-writer.js';
@@ -8,7 +9,7 @@ import { writeConfig, ensureConfigDefaults } from '../storage/config-store.js';
 import { detectMode } from '../auth/detect.js';
 import { readCredentials } from '../auth/credentials.js';
 import { resolveOrgId } from '../tracking/plan-usage.js';
-import { CLAUDE_CREDENTIALS_PATH } from '../constants.js';
+import { CLAUDE_CREDENTIALS_PATH, CLAUDE_SETTINGS_PATH } from '../constants.js';
 export async function runInit(opts) {
     const meterDir = opts.meterDir;
     const binDir = join(meterDir, 'bin');
@@ -52,7 +53,77 @@ export async function runInit(opts) {
         ...(orgId ? { org_id: orgId } : {}),
     });
     await writeConfig(join(meterDir, 'config.json'), config);
+    // Install Claude Code hooks (skip in tests)
+    if (!opts.skipPathInjection) {
+        await installClaudeHooks(meterDir);
+    }
     console.log(`✓ meter initialised (${mode} mode)`);
     console.log(`  Restart your terminal or run: source ~/.zshrc`);
 }
+async function installClaudeHooks(meterDir) {
+    const hooksDir = join(meterDir, 'hooks');
+    await mkdir(hooksDir, { recursive: true });
+    // Copy hook scripts to ~/.meter/hooks/
+    const srcDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+    for (const file of ['on-prompt.js', 'statusline.js']) {
+        try {
+            await copyFile(join(srcDir, file), join(hooksDir, file));
+            await chmod(join(hooksDir, file), 0o755);
+        }
+        catch {
+            // If source doesn't exist (running from dist), try the dist/hooks path
+            const distDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'src', 'hooks');
+            try {
+                await copyFile(join(distDir, file), join(hooksDir, file));
+                await chmod(join(hooksDir, file), 0o755);
+            }
+            catch {
+                console.warn(`  ⚠ Could not copy ${file} — skipping hook installation`);
+            }
+        }
+    }
+    // Update Claude Code settings.json to add meter hooks
+    try {
+        let settings = {};
+        try {
+            settings = JSON.parse(await readFile(CLAUDE_SETTINGS_PATH, 'utf-8'));
+        }
+        catch {
+            // settings file doesn't exist yet — we'll create it
+        }
+        // Add UserPromptSubmit hook if not already present
+        const meterHookCommand = `node "${join(hooksDir, 'on-prompt.js')}"`;
+        if (!settings.hooks)
+            settings.hooks = {};
+        if (!settings.hooks.UserPromptSubmit)
+            settings.hooks.UserPromptSubmit = [];
+        const alreadyHasHook = settings.hooks.UserPromptSubmit.some((h) => h.hooks?.some((hh) => hh.command?.includes('meter')));
+        if (!alreadyHasHook) {
+            settings.hooks.UserPromptSubmit.push({
+                hooks: [{ type: 'command', command: meterHookCommand }]
+            });
+            console.log('✓ Added meter estimation hook to Claude Code');
+        }
+        // Add/update statusline command
+        const meterStatuslineCommand = `node "${join(hooksDir, 'statusline.js')}"`;
+        const existingStatusLine = settings.statusLine;
+        if (!existingStatusLine || existingStatusLine.command?.includes('meter')) {
+            // No existing statusline or it's ours — set it
+            settings.statusLine = { type: 'command', command: meterStatuslineCommand };
+            console.log('✓ Added meter statusline to Claude Code');
+        }
+        else {
+            // There's an existing statusline from another tool — chain them
+            // Create a wrapper that runs both
+            const chainCommand = `${existingStatusLine.command} && echo " │ " && ${meterStatuslineCommand}`;
+            settings.statusLine = { type: 'command', command: chainCommand };
+            console.log('✓ Chained meter statusline with existing statusline');
+        }
+        await mkdir(dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
+        await writeFile(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.warn(`  ⚠ Could not update Claude Code settings: ${err}`);
+    }
+}
 //# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meter-ai",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Intelligent CLI wrapper for Claude Code — pre-task cost estimation, live status bar, budget protection",
   "bin": {
     "meter": "dist/index.js"

package/src/auth/credentials.ts

@@ -0,0 +1,44 @@
+import { watch } from 'fs'
+import { readFile as readFileAsync } from 'fs/promises'
+
+export interface ClaudeCredentials {
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number
+  [key: string]: unknown
+}
+
+export async function readCredentials(path: string): Promise<ClaudeCredentials | null> {
+  async function tryRead(): Promise<ClaudeCredentials | null> {
+    try {
+      const raw = await readFileAsync(path, 'utf-8')
+      return JSON.parse(raw) as ClaudeCredentials
+    } catch {
+      return null
+    }
+  }
+
+  const first = await tryRead()
+  if (first) return first
+
+  // retry once after 200ms (handles partial writes on macOS kqueue)
+  await new Promise(r => setTimeout(r, 200))
+  return tryRead()
+}
+
+export function watchCredentials(
+  path: string,
+  onChange: (creds: ClaudeCredentials | null) => void
+): () => void {
+  let debounceTimer: NodeJS.Timeout | null = null
+
+  const watcher = watch(path, () => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(async () => {
+      const creds = await readCredentials(path)
+      onChange(creds)
+    }, 100) // 100ms debounce to avoid partial-write reads
+  })
+
+  return () => watcher.close()
+}

package/src/auth/detect.ts

@@ -0,0 +1,24 @@
+import { access } from 'fs/promises'
+import type { UserMode } from '../types.js'
+
+interface DetectOptions {
+  credentialsPath: string
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function detectMode(opts: DetectOptions): Promise<UserMode | null> {
+  const hasApiKey = Boolean(process.env.ANTHROPIC_API_KEY)
+  const hasCredentials = await fileExists(opts.credentialsPath)
+
+  if (hasCredentials) return 'plan'
+  if (hasApiKey) return 'api'
+  return null
+}

package/src/commands/config.ts

@@ -0,0 +1,19 @@
+import { readConfig, writeConfig } from '../storage/config-store.js'
+import { CONFIG_PATH } from '../constants.js'
+
+export async function runConfig(args: string[]): Promise<void> {
+  const config = await readConfig(CONFIG_PATH)
+  if (!config) { console.log('Run meter init first.'); return }
+  if (args.length === 0) { console.log(JSON.stringify(config, null, 2)); return }
+  if (args[0] === 'set' && args[1] && args[2]) {
+    const field = args[1]
+    const val = args[2]
+    if (field === 'budget') config.budget.per_task_usd = parseFloat(val)
+    else if (field === 'threshold') {
+      config.budget.threshold_pct = parseInt(val, 10)
+      config.plan.window_threshold_pct = parseInt(val, 10)
+    }
+    await writeConfig(CONFIG_PATH, config)
+    console.log(`✓ ${field} set to ${val}`)
+  }
+}

package/src/commands/history.ts

@@ -0,0 +1,16 @@
+import { openDb, getRecentTasks } from '../storage/db.js'
+import { HISTORY_DB_PATH } from '../constants.js'
+
+export async function runHistory(args: string[]): Promise<void> {
+  const limit = parseInt(args[0] ?? '30', 10)
+  const db = await openDb(HISTORY_DB_PATH)
+  const tasks = getRecentTasks(db, limit)
+  db.close()
+  if (tasks.length === 0) { console.log('No tasks recorded yet.'); return }
+  console.log(`\n◆ meter  history  (last ${limit})\n`)
+  for (const t of tasks) {
+    const date = new Date(t.created_at).toLocaleString()
+    const cost = t.actual_cost != null ? `$${t.actual_cost.toFixed(3)}` : t.window_pct_end != null ? `${t.window_pct_end.toFixed(0)}% window` : '—'
+    console.log(`  ${date}  ${t.complexity.padEnd(8)}  ${cost.padStart(10)}  ${t.prompt_text.slice(0, 50)}`)
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,149 @@
+import { mkdir, readFile, writeFile, copyFile, chmod } from 'fs/promises'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { detectShell, getShellConfigPath } from '../shell/detect.js'
+import { resolveTrueBinary } from '../shell/binary-resolver.js'
+import { writeShim } from '../shell/shim-writer.js'
+import { injectPath, isPathAlreadyInjected } from '../shell/path-inject.js'
+import { writeConfig, ensureConfigDefaults } from '../storage/config-store.js'
+import { detectMode } from '../auth/detect.js'
+import { readCredentials } from '../auth/credentials.js'
+import { resolveOrgId } from '../tracking/plan-usage.js'
+import { METER_BIN_DIR, CLAUDE_CREDENTIALS_PATH, CLAUDE_SETTINGS_PATH } from '../constants.js'
+import type { UserMode } from '../types.js'
+
+export interface InitOptions {
+  meterDir: string
+  trueBinary?: string
+  mode?: UserMode
+  skipPathInjection?: boolean
+  orgId?: string | null
+}
+
+export async function runInit(opts: InitOptions): Promise<void> {
+  const meterDir = opts.meterDir
+  const binDir = join(meterDir, 'bin')
+  await mkdir(binDir, { recursive: true })
+  await mkdir(join(meterDir, 'cache'), { recursive: true })
+  await mkdir(join(meterDir, 'reports'), { recursive: true })
+
+  // Resolve true claude binary
+  const trueBinary = opts.trueBinary ?? await resolveTrueBinary('claude', binDir)
+  if (!trueBinary) {
+    throw new Error('claude not found in PATH. Install Claude Code first.')
+  }
+
+  // Detect mode
+  const mode = opts.mode ?? await detectMode({ credentialsPath: CLAUDE_CREDENTIALS_PATH })
+  if (!mode) {
+    throw new Error('No Claude credentials found. Run `claude` first to authenticate.')
+  }
+
+  // Resolve org_id for Plan Mode
+  let orgId = opts.orgId ?? null
+  if (mode === 'plan' && orgId === null) {
+    const creds = await readCredentials(CLAUDE_CREDENTIALS_PATH)
+    if (creds) orgId = await resolveOrgId(creds)
+  }
+
+  // Write shim
+  const shimPath = join(binDir, 'claude')
+  await writeShim(shimPath, trueBinary)
+
+  // Inject PATH (skip in tests)
+  if (!opts.skipPathInjection) {
+    const shell = detectShell()
+    const configPath = getShellConfigPath(shell)
+    const already = await isPathAlreadyInjected(configPath)
+    await injectPath(shell, configPath)
+    if (!already) {
+      console.log(`✓ Added ~/.meter/bin to PATH in ${configPath}`)
+    }
+  }
+
+  // Write config
+  const config = ensureConfigDefaults({
+    mode,
+    resolved_binaries: { claude: trueBinary },
+    ...(orgId ? { org_id: orgId } : {}),
+  })
+  await writeConfig(join(meterDir, 'config.json'), config)
+
+  // Install Claude Code hooks (skip in tests)
+  if (!opts.skipPathInjection) {
+    await installClaudeHooks(meterDir)
+  }
+
+  console.log(`✓ meter initialised (${mode} mode)`)
+  console.log(`  Restart your terminal or run: source ~/.zshrc`)
+}
+
+async function installClaudeHooks(meterDir: string): Promise<void> {
+  const hooksDir = join(meterDir, 'hooks')
+  await mkdir(hooksDir, { recursive: true })
+
+  // Copy hook scripts to ~/.meter/hooks/
+  const srcDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'hooks')
+  for (const file of ['on-prompt.js', 'statusline.js']) {
+    try {
+      await copyFile(join(srcDir, file), join(hooksDir, file))
+      await chmod(join(hooksDir, file), 0o755)
+    } catch {
+      // If source doesn't exist (running from dist), try the dist/hooks path
+      const distDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'src', 'hooks')
+      try {
+        await copyFile(join(distDir, file), join(hooksDir, file))
+        await chmod(join(hooksDir, file), 0o755)
+      } catch {
+        console.warn(`  ⚠ Could not copy ${file} — skipping hook installation`)
+      }
+    }
+  }
+
+  // Update Claude Code settings.json to add meter hooks
+  try {
+    let settings: Record<string, any> = {}
+    try {
+      settings = JSON.parse(await readFile(CLAUDE_SETTINGS_PATH, 'utf-8'))
+    } catch {
+      // settings file doesn't exist yet — we'll create it
+    }
+
+    // Add UserPromptSubmit hook if not already present
+    const meterHookCommand = `node "${join(hooksDir, 'on-prompt.js')}"`
+    if (!settings.hooks) settings.hooks = {}
+    if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = []
+
+    const alreadyHasHook = settings.hooks.UserPromptSubmit.some((h: any) =>
+      h.hooks?.some((hh: any) => hh.command?.includes('meter'))
+    )
+
+    if (!alreadyHasHook) {
+      settings.hooks.UserPromptSubmit.push({
+        hooks: [{ type: 'command', command: meterHookCommand }]
+      })
+      console.log('✓ Added meter estimation hook to Claude Code')
+    }
+
+    // Add/update statusline command
+    const meterStatuslineCommand = `node "${join(hooksDir, 'statusline.js')}"`
+    const existingStatusLine = settings.statusLine
+
+    if (!existingStatusLine || existingStatusLine.command?.includes('meter')) {
+      // No existing statusline or it's ours — set it
+      settings.statusLine = { type: 'command', command: meterStatuslineCommand }
+      console.log('✓ Added meter statusline to Claude Code')
+    } else {
+      // There's an existing statusline from another tool — chain them
+      // Create a wrapper that runs both
+      const chainCommand = `${existingStatusLine.command} && echo " │ " && ${meterStatuslineCommand}`
+      settings.statusLine = { type: 'command', command: chainCommand }
+      console.log('✓ Chained meter statusline with existing statusline')
+    }
+
+    await mkdir(dirname(CLAUDE_SETTINGS_PATH), { recursive: true })
+    await writeFile(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf-8')
+  } catch (err) {
+    console.warn(`  ⚠ Could not update Claude Code settings: ${err}`)
+  }
+}

package/src/commands/report.ts

@@ -0,0 +1,27 @@
+import { readConfig } from '../storage/config-store.js'
+import { openDb, getRecentTasks } from '../storage/db.js'
+import { CONFIG_PATH, HISTORY_DB_PATH } from '../constants.js'
+
+export async function runReport(): Promise<void> {
+  const config = await readConfig(CONFIG_PATH)
+  if (!config) { console.log('Run meter init first.'); return }
+  const db = await openDb(HISTORY_DB_PATH)
+  const weekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000
+  const allTasks = getRecentTasks(db, 500).filter(t => t.created_at >= weekAgo)
+  db.close()
+  if (allTasks.length === 0) { console.log('No tasks recorded this week.'); return }
+  const totalCost = allTasks.reduce((s, t) => s + (t.actual_cost ?? 0), 0)
+  const heaviest = allTasks.sort((a, b) => (b.actual_cost ?? 0) - (a.actual_cost ?? 0))[0]
+  const byComplexity: Record<string, number> = { low: 0, medium: 0, heavy: 0, critical: 0 }
+  for (const t of allTasks) byComplexity[t.complexity] = (byComplexity[t.complexity] ?? 0) + 1
+  console.log(`\n◆ meter  weekly report\n`)
+  console.log(`  Mode            ${config.mode}`)
+  console.log(`  Tasks run       ${allTasks.length}`)
+  if (config.mode === 'api') {
+    console.log(`  Total spend     $${totalCost.toFixed(3)}`)
+    console.log(`  Avg task cost   $${(totalCost / allTasks.length).toFixed(3)}`)
+  }
+  if (heaviest) console.log(`  Heaviest task   "${heaviest.prompt_text.slice(0, 40)}"`)
+  console.log(`\n  By complexity:`)
+  for (const [k, v] of Object.entries(byComplexity)) if (v > 0) console.log(`    ${k.padEnd(10)} ${v} tasks`)
+}

package/src/commands/status.ts

@@ -0,0 +1,16 @@
+import { readConfig } from '../storage/config-store.js'
+import { CONFIG_PATH } from '../constants.js'
+
+export async function runStatus(): Promise<void> {
+  const config = await readConfig(CONFIG_PATH)
+  if (!config) { console.log('meter not initialised. Run: meter init'); return }
+  console.log(`◆ meter status\n`)
+  console.log(`  Mode:    ${config.mode}`)
+  console.log(`  Model:   ${config.models.claude_chain[0]}`)
+  console.log(`  Claude:  ${config.resolved_binaries.claude}`)
+  if (config.mode === 'api') {
+    console.log(`  Budget:  $${config.budget.per_task_usd} per task  (notify at ${config.budget.threshold_pct}%)`)
+  } else {
+    console.log(`  Window:  notify at ${config.plan.window_threshold_pct}%`)
+  }
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,20 @@
+import { rm } from 'fs/promises'
+import { removePath } from '../shell/path-inject.js'
+import { detectShell, getShellConfigPath } from '../shell/detect.js'
+import { METER_DIR } from '../constants.js'
+import * as readline from 'readline/promises'
+
+export async function runUninstall(): Promise<void> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await rl.question('Remove all meter data (~/.meter/)? [y/N] ')
+  rl.close()
+  const shell = detectShell()
+  const configPath = getShellConfigPath(shell)
+  await removePath(configPath)
+  console.log(`✓ Removed PATH entry from ${configPath}`)
+  if (answer.toLowerCase() === 'y') {
+    await rm(METER_DIR, { recursive: true, force: true })
+    console.log('✓ Removed ~/.meter/')
+  }
+  console.log('✓ Uninstall complete. Run: npm uninstall -g meter-ai')
+}