Setup Cost Tracking

---
name: setup-cost-tracking
description: Install genuine per-session cost tracking for Claude Code by wiring bundled logger scripts into the user's statusline — preserving any existing statusline and hooks. Use when the user asks to set up, install, enable, or repair cost tracking / cost logging / session cost capture. Idempotent; safe to re-run.
model: inherit
color: orange
---

# Setup Cost Tracking

Installs genuine cost capture for every Claude Code session on this machine. Cost data
(`cost.total_cost_usd` etc.) is computed by Claude Code itself and is available **only**
in the statusline payload — hooks never receive it. So this skill wires a logger into the
statusline path while preserving whatever statusline and hooks the user already has.

## What gets installed

Bundled in this skill's `scripts/` directory, copied to `~/.claude/scripts/`:

| Script | Role |
|---|---|
| `cost-logger.js` | Capture engine. Silent, crash-proof. Writes the log files below. |
| `statusline-wrapper.js` | Used when the user already has a statusline: logs cost, then delegates the payload to their original command and passes its output through untouched. |
| `statusline-command.js` | Used when the user has no statusline: full display (model, context bar, cost, cache stats) that also logs. |
| `turn-logger.js` | Stop hook: stamps turn boundaries so cost samples can later be grouped into turns for analytics. No cost data itself. |

Log outputs (created lazily, no setup needed):

- `~/.claude/cost-log.jsonl` — one row per session, exact cumulative totals (upserted).
- `~/.claude/projects/<mapped-dir>/<session>.cost.jsonl` — cost samples at ~5s resolution during activity.
- `~/.claude/projects/<mapped-dir>/<session>.turn-boundaries.jsonl` — one row per turn end, with `transcript_path` for deep-dive analytics.

## Installation procedure

Follow these steps exactly. Use real JSON manipulation (a `node -e` script or `jq`) for
every settings edit — never string/regex edits on settings files.

### Step 0 — Preflight

1. `command -v node` — if Node.js is missing, stop and tell the user it's required.
   Record the absolute path (call it `$NODE`). Use `$NODE` in every command you write
   into settings, not bare `node` (statusline/hook commands don't always get the user's
   full shell PATH).
2. Read `~/.claude/settings.json` (treat as `{}` if absent) and `~/.claude/settings.local.json`
   (if present). The **effective** `statusLine` is the local one if defined there, else the
   user one. Remember which file defines it — edits must go to that same file.

### Step 1 — Copy scripts

1. `mkdir -p ~/.claude/scripts`
2. Copy the four `.js` files from this skill's `scripts/` directory into `~/.claude/scripts/`
   and `chmod +x` them. Overwriting previous versions of these four files is fine (that's
   how upgrades work). **Never** overwrite `~/.claude/scripts/statusline-original.json`
   if it exists.

### Step 2 — Wire the statusline (the load-bearing step)

Decide by the effective `statusLine`:

- **Case A — already ours**: its command contains `statusline-wrapper.js` or
  `statusline-command.js`. Nothing to change; report "already installed" and continue to Step 3.
- **Case B — none configured**: set in `~/.claude/settings.json`:
  ```json
  "statusLine": { "type": "command", "command": "$NODE /Users/<user>/.claude/scripts/statusline-command.js", "padding": 0 }
  ```
  (expand `$NODE` and the home directory to absolute paths).
- **Case C — user has their own statusline**: preserve it.
  1. Write `~/.claude/scripts/statusline-original.json` containing exactly
     `{ "command": "<their current statusLine.command>" }`.
  2. In the file that defines `statusLine`, replace **only** the `command` value with
     `$NODE /Users/<user>/.claude/scripts/statusline-wrapper.js`. Keep `type`, `padding`,
     `refreshInterval`, and any other sibling keys untouched.

Before the first edit to any settings file, back it up:
`cp settings.json settings.json.bak-cost-tracking` (same pattern for the local file).
One backup per run is enough.

### Step 3 — Add the turn-boundary hook (additive, never replaces)

If no existing `hooks.Stop` entry's command mentions `turn-logger.js`, append this entry to
the `hooks.Stop` array (create the array/path if missing), leaving every existing hook alone:

```json
{ "matcher": "", "hooks": [ { "type": "command", "command": "$NODE /Users/<user>/.claude/scripts/turn-logger.js" } ] }
```

This hook carries no cost data — it only stamps turn boundaries and the idle timer. If the
user objects to hooks, skipping this step still leaves session cost capture fully working.

### Step 4 — Verify

1. Build a fake statusline payload with `session_id` `"cost-setup-verify"`, a `workspace.current_dir`
   of `/tmp/cost-setup-verify`, and nonzero `cost.total_cost_usd` / `cost.total_api_duration_ms` /
   `model.display_name` values.
2. Pipe it via stdin into the exact `statusLine.command` now in settings (run through `sh -c`).
   - Case B: expect the rendered multi-line statusline.
   - Case C: expect the *original* statusline's output (the wrapper delegates). If their original
     command errors on the synthetic payload, that's their script's quirk — check instead that
     the log file below was written.
3. Confirm `~/.claude/projects/-tmp-cost-setup-verify/cost-setup-verify.cost.jsonl` now exists
   and contains the fake cost.
4. Clean up all verification artifacts: that projects subdirectory, the `cost-setup-verify` line
   in `~/.claude/cost-log.jsonl`, and `/tmp/statusline-*-cost-setup-verify` state files.

### Step 5 — Report

Tell the user, concretely:
- which case applied (fresh install / wrapped their existing statusline / already installed),
- every file created or modified (settings edits, backups, copied scripts),
- where their cost data will accumulate (the three log paths above),
- that changes take effect in new sessions,
- how to uninstall: restore the `.bak-cost-tracking` settings backup (or, by hand: point
  `statusLine.command` back to the command saved in `~/.claude/scripts/statusline-original.json`
  and remove the turn-logger Stop hook entry), then delete the four scripts.

## Invariants

- **Never delete or rewrite the user's hooks, statusline command, or unrelated settings keys.**
  All changes are additive or a single-value swap that is recorded for reversal.
- Idempotent: re-running on an installed machine must change nothing and say so.
- If any step fails midway, restore the settings backup and report what happened.