Claude Code Usage in Alfred

An Alfred Script Filter workflow that reads Headroom's local JSON and displays your Claude Code session and weekly usage on demand.

Quick bash script (no workflow needed)

The simplest approach: add a keyword to Alfred that runs a bash script and shows output:

In Alfred Preferences → Workflows → + → Templates → Essentials → "Keyword to Script":

• Keyword: cc (or claude)
• Script type: /bin/bash
• Script content:

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

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

if [ -n "$CONTEXT" ]; then
  printf "Session: %d%%  Weekly: %d%%  Context: %d%%
Model: %s  Cost: $%s"     "$SESSION" "$WEEKLY" "$CONTEXT" "$MODEL" "$COST"
else
  printf "Session: %d%%  Weekly: %d%%
Model: %s  Cost: $%s"     "$SESSION" "$WEEKLY" "$MODEL" "$COST"
fi

Script Filter workflow (Alfred JSON output)

For a richer result that shows each metric as a separate Alfred result item:

#!/bin/bash
FILE="$HOME/.claude/headroom-usage.json"

if [ ! -f "$FILE" ]; then
  echo '{"items":[{"title":"Headroom not installed","subtitle":"Install from headroom.walls.sh","valid":false}]}'
  exit 0
fi

SESSION=$(jq '.sessionUsagePct | floor' "$FILE")
WEEKLY=$(jq '.weeklyUsagePct | floor' "$FILE")
CONTEXT=$(jq '.contextUsagePct | floor // "–"' "$FILE")
MODEL=$(jq -r '.modelName // "unknown"' "$FILE")
COST=$(jq '.sessionCost // 0' "$FILE")
SESSION_RESET=$(jq '.sessionResetSec // 0 | . / 3600 | floor' "$FILE")
WEEKLY_RESET=$(jq '.weeklyResetSec // 0 | . / 86400 | floor' "$FILE")

cat <

Setup for Script Filter


  
Alfred Preferences → Workflows → + → Blank Workflow
  
Add trigger: Inputs → Script Filter; set Keyword to cc
  
Language: /bin/bash, Script: paste the JSON script above
  
Check "Alfred filters results" if you want to type-filter the items


Pressing Enter on a result copies the value to the clipboard.

The always-on alternative

Alfred shows usage on demand when you invoke it. Headroom shows it always-on in the menu bar without any keypress. Both read the same file.

If you live in Alfred, this script works well. If you want the usage visible without actively checking, Headroom's menu bar item is the simpler choice.

brew install --cask patwalls/tap/headroom

→ Raycast Script Command

→ Shell prompt integration

→ How the data source works