headroom.walls.sh · log

Log Claude Code usage over time

Snapshot your session and weekly usage every 15 minutes with cron, build a running CSV log, and query trends with jq. No new dependencies — just the file Claude Code already writes.

The data source

Claude Code writes a snapshot of your current usage to ~/.claude/headroom-usage.json every time it refreshes its status line (requires the statusLineHook set up). The file contains:

{
  "sessionUsagePct": 34.2,
  "weeklyUsagePct": 61.8,
  "sessionCost": 0.42,
  "modelName": "claude-sonnet-4-6",
  "sessionResetSec": 9847,
  "weeklyResetSec": 198432
}

This is a point-in-time snapshot — it only shows right now. To build a history, you snapshot it on a schedule and append each reading to a log file.

Step 1 — Set up the hook

If ~/.claude/headroom-usage.json doesn't exist yet, add the statusLineHook to ~/.claude/settings.json first:

{
  "statusLineHook": "cat ~/.claude/headroom-usage.json 2>/dev/null | jq -r '"CC \(.sessionUsagePct|floor)%·\(.weeklyUsagePct|floor)%"' 2>/dev/null || echo 'CC --%'"
}

Start a Claude Code session and run any command — the file will appear. Then proceed.

→ Full hook setup docs

Step 2 — Create the log script

Create ~/.claude/log-usage.sh:

#!/bin/bash
# Append a timestamped usage snapshot to the CSV log.
LOG="$HOME/.claude/usage-log.csv"
SRC="$HOME/.claude/headroom-usage.json"

# Write header if new file
[ -f "$LOG" ] || echo "timestamp,session_pct,weekly_pct,session_cost,model,session_reset_sec,weekly_reset_sec" >> "$LOG"

# Only log if Claude Code has written data
[ -f "$SRC" ] || exit 0
jq -r "[
  (now | todate),
  .sessionUsagePct,
  .weeklyUsagePct,
  .sessionCost,
  .modelName,
  .sessionResetSec,
  .weeklyResetSec
] | @csv" "$SRC" >> "$LOG"

chmod +x ~/.claude/log-usage.sh

Step 3 — Schedule with cron

Open your crontab:

crontab -e

Add a line to snapshot every 15 minutes:

# Log Claude Code usage every 15 minutes
*/15 * * * * /bin/bash $HOME/.claude/log-usage.sh

Verify it was saved:

crontab -l | grep log-usage

The log format

After a few hours, your log looks like:

timestamp,session_pct,weekly_pct,session_cost,model,session_reset_sec,weekly_reset_sec
"2026-06-11T14:00:03Z",12.1,43.2,0.18,"claude-sonnet-4-6",16247,187203
"2026-06-11T14:15:04Z",18.7,43.9,0.27,"claude-sonnet-4-6",15347,186303
"2026-06-11T14:30:05Z",31.4,45.1,0.46,"claude-sonnet-4-6",14447,185403
"2026-06-11T14:45:03Z",31.4,45.1,0.46,"claude-sonnet-4-6",13547,184503
"2026-06-11T15:00:04Z",48.2,46.8,0.71,"claude-sonnet-4-6",12647,183603

Querying the log with jq

Today's peak session usage

tail -n 96 ~/.claude/usage-log.csv | grep -v "^timestamp" |   jq -Rs '[split("
")[] | select(length>0) | split(",") | {session: .[1]|tonumber, ts: .[0]}] | max_by(.session)'

Last 4 hours, session % only

tail -n 16 ~/.claude/usage-log.csv | grep -v "^timestamp" |   awk -F',' '{print $1, $2"%"}'

Daily cost summary

grep "^"2026-06-11" ~/.claude/usage-log.csv |   awk -F',' 'BEGIN{max=0} {v=$4+0; if(v>max) max=v} END{print "max cost so far today: $"max}'

Weekly usage trend (last 7 days of noon snapshots)

grep "T12:0" ~/.claude/usage-log.csv | tail -7 |   awk -F',' '{printf "%s  weekly: %s%%
", substr($1,2,10), $3}'

Alert when weekly crosses 80%

Add this to your ~/.zshrc or run it from cron:

WEEKLY=$(jq -r '.weeklyUsagePct' ~/.claude/headroom-usage.json 2>/dev/null)
if (( $(echo "$WEEKLY > 80" | bc -l) )); then
  osascript -e 'display notification "Claude Code weekly usage over 80%" with title "Headroom"'
fi

Log rotation

At 15-minute intervals the log grows ~100 rows/day. After a month that's ~3,000 rows — tiny. After a year, ~35,000 rows — still fast with grep/awk. If you prefer to rotate monthly:

# Add to crontab — archive on the 1st of each month at midnight
0 0 1 * * mv $HOME/.claude/usage-log.csv $HOME/.claude/usage-log-$(date +%Y-%m).csv

Visualize with gnuplot (optional)

If you have gnuplot installed (brew install gnuplot), a quick terminal sparkline of weekly % over time:

gnuplot -e "
  set terminal dumb 80 20;
  set datafile separator ',';
  set xdata time; set timefmt '%Y-%m-%dT%H:%M:%SZ';
  plot '~/.claude/usage-log.csv' using 1:3 with lines title 'weekly %'
"

If you want both the log for history and a live indicator without a terminal open, Headroom keeps session and weekly usage visible in the menu bar at all times — color-coded before a limit stops you. Free, MIT, ~267 KB.

brew install --cask patwalls/tap/headroom

→ statusLineHook setup
→ Threshold notifications
→ 5-hour session window explained
→ 7-day weekly window explained