Claude Code Usage in Raycast

A Script Command that reads Headroom's local JSON and shows your Claude Code session + weekly % on demand from Raycast.

The Script Command

Raycast Script Commands are shell scripts with special comment metadata. Save this as ~/raycast-scripts/claude-usage.sh:

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Claude Code Usage
# @raycast.mode compact
# @raycast.packageName Developer Tools

# Optional parameters:
# @raycast.icon 🧠
# @raycast.description Show Claude Code session and weekly usage from Headroom

FILE="$HOME/.claude/headroom-usage.json"

if [ ! -f "$FILE" ]; then
  echo "No data — is Headroom installed?"
  exit 0
fi

SESSION=$(jq '.sessionUsagePct | floor' "$FILE" 2>/dev/null)
WEEKLY=$(jq '.weeklyUsagePct | floor' "$FILE" 2>/dev/null)
CONTEXT=$(jq '.contextUsagePct | floor // empty' "$FILE" 2>/dev/null)
MODEL=$(jq -r '.modelName // "unknown"' "$FILE" 2>/dev/null)
COST=$(jq '.sessionCost // 0' "$FILE" 2>/dev/null)

if [ -z "$SESSION" ]; then
  echo "Waiting for Claude Code data…"
  exit 0
fi

if [ -n "$CONTEXT" ]; then
  echo "CC ${SESSION}%·${WEEKLY}%·${CONTEXT}% | $MODEL | $$${COST}"
else
  echo "CC ${SESSION}%·${WEEKLY}% | $MODEL | $$${COST}"
fi

Setup

1. Save the script to ~/raycast-scripts/claude-usage.sh
2. Make it executable: chmod +x ~/raycast-scripts/claude-usage.sh
3. In Raycast: open Settings → Extensions → Script Commands → Add Directory → pick ~/raycast-scripts/
4. Search for "Claude Code Usage" in Raycast — it will appear as a command

Detailed view (list mode)

For a full breakdown with reset countdowns, use @raycast.mode fullOutput:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Claude Code Usage (Detailed)
# @raycast.mode fullOutput
# @raycast.packageName Developer Tools
# @raycast.icon 🧠
# @raycast.description Full Claude Code usage breakdown with reset times

FILE="$HOME/.claude/headroom-usage.json"
[ ! -f "$FILE" ] && echo "Headroom not installed or Claude Code not running." && exit 0

jq -r '
  "Session:  " + (.sessionUsagePct | floor | tostring) + "%" +
    (if .sessionResetSec then " (resets in " + (.sessionResetSec / 3600 | floor | tostring) + "h " + ((.sessionResetSec % 3600) / 60 | floor | tostring) + "m)" else "" end),
  "Weekly:   " + (.weeklyUsagePct  | floor | tostring) + "%" +
    (if .weeklyResetSec then " (resets in " + (.weeklyResetSec / 86400 | floor | tostring) + "d " + ((.weeklyResetSec % 86400) / 3600 | floor | tostring) + "h)" else "" end),
  (if .contextUsagePct then "Context:  " + (.contextUsagePct | floor | tostring) + "%" else empty end),
  "Model:    " + (.modelName // "unknown"),
  "Cost:     $" + ((.sessionCost // 0) | tostring)
' "$FILE"

Set a keyboard shortcut

In Raycast Settings → Extensions → Script Commands → Claude Code Usage → set a hotkey like ⌘⌥U to pull up usage without leaving your current app.

The always-on alternative

The Raycast Script Command shows usage on demand. Headroom shows it always-on in the menu bar — you can see it at a glance without opening Raycast. Both read from the same file.

If you want the ambient view (without opening Raycast each time), Headroom is the right tool. If you prefer Raycast as your control center and want to query usage there, this script works well.

brew install --cask patwalls/tap/headroom

→ Shell prompt integration
→ Starship integration
→ tmux integration
→ How the data source works