Claude Code usage in your shell prompt

If you use Claude Code heavily, you may want your terminal prompt to show the current session and weekly usage — so you see the numbers before running /usage, without switching to the menu bar. These snippets read ~/.claude/headroom-usage.json and embed the values directly in your prompt.

These snippets work whether or not you have Headroom installed — they read the same local file. The file is written by Claude Code's statusLine hook, which Headroom installs automatically. If you don't have Headroom, install the hook manually.

Prerequisites: install the hook

The file ~/.claude/headroom-usage.json is written by a statusLine hook in ~/.claude/settings.json. Installing Headroom wires this automatically. Or wire it manually:

# Add to ~/.claude/settings.json under "statusLine"
{
  "statusLine": "jq -rc '. + {statusLineOutput: "CC \(.sessionUsagePct | round)%·\(.weeklyUsagePct | round)%"}' | tee ~/.claude/headroom-usage.json | jq -rc '.statusLineOutput'"
}

After adding this, open Claude Code once and the file appears at ~/.claude/headroom-usage.json.

Zsh — RPROMPT (right-side prompt)

Add Claude Code usage to the right side of your prompt. Right-prompts are unobtrusive: they don't affect copy-paste, and zsh hides them when a command is long enough to reach them.

# ~/.zshrc — add Claude Code usage to RPROMPT
function _cc_usage() {
  local f="$HOME/.claude/headroom-usage.json"
  [[ -f "$f" ]] || return
  local session weekly
  session=$(jq -r '.sessionUsagePct // empty | round | tostring + "%"' "$f" 2>/dev/null)
  weekly=$(jq -r '.weeklyUsagePct // empty | round | tostring + "%"' "$f" 2>/dev/null)
  [[ -n "$session" && -n "$weekly" ]] && echo "CC $session·$weekly"
}
RPROMPT='$(_cc_usage)'
~/projects/myapp on main
❯ git statusCC 23%·67%

Zsh — left prompt (PS1)

# ~/.zshrc — inline at the end of your PS1
function _cc_inline() {
  local f="$HOME/.claude/headroom-usage.json"
  [[ -f "$f" ]] || return
  local s w
  s=$(jq -r '.sessionUsagePct // empty | round' "$f" 2>/dev/null)
  w=$(jq -r '.weeklyUsagePct // empty | round' "$f" 2>/dev/null)
  [[ -n "$s" && -n "$w" ]] && echo " [CC $s%·$w%]"
}
PS1='%n@%m %~$(_cc_inline) %# '

Bash — PS1

# ~/.bashrc — add to PS1
_cc_usage_bash() {
  local f="$HOME/.claude/headroom-usage.json"
  [ -f "$f" ] || return
  local s w
  s=$(jq -r '.sessionUsagePct // empty | . + 0.5 | floor | tostring' "$f" 2>/dev/null)
  w=$(jq -r '.weeklyUsagePct // empty | . + 0.5 | floor | tostring' "$f" 2>/dev/null)
  [ -n "$s" ] && [ -n "$w" ] && echo " CC:$s%·$w%"
}
PS1='\u@\h \w$(\$(_cc_usage_bash)) \$ '

Fish shell

# ~/.config/fish/functions/fish_right_prompt.fish
function fish_right_prompt
  set f "$HOME/.claude/headroom-usage.json"
  test -f $f; or return
  set s (jq -r '.sessionUsagePct // empty | round | tostring + "%"' $f 2>/dev/null)
  set w (jq -r '.weeklyUsagePct // empty | round | tostring + "%"' $f 2>/dev/null)
  if test -n "$s" -a -n "$w"
    echo -n "CC $s·$w"
  end
end

Color-coded version (zsh RPROMPT)

Add color to match Headroom's amber/red thresholds:

# ~/.zshrc — color-coded RPROMPT
function _cc_color() {
  local f="$HOME/.claude/headroom-usage.json"
  [[ -f "$f" ]] || return
  local s w pct color
  s=$(jq -r '.sessionUsagePct // 0 | round' "$f" 2>/dev/null)
  w=$(jq -r '.weeklyUsagePct // 0 | round' "$f" 2>/dev/null)
  [[ -z "$s" || -z "$w" ]] && return
  # Use the higher of the two for coloring
  pct=$(( s > w ? s : w ))
  if   (( pct >= 90 )); then color="%F{red}"
  elif (( pct >= 70 )); then color="%F{yellow}"
  else                       color="%F{green}"
  fi
  echo "${color}CC ${s}%·${w}%%f"
}
RPROMPT='$(_cc_color)'

One-liner for scripts

Pull both values in a single jq call:

# Compact: "23%·67%"
jq -r '[.sessionUsagePct, .weeklyUsagePct] | map(. + 0.5 | floor | tostring + "%") | join("·")' ~/.claude/headroom-usage.json

# Key-value for alerting scripts
jq -r '"session=\(.sessionUsagePct | round)% week=\(.weeklyUsagePct | round)%"' ~/.claude/headroom-usage.json

Starship prompt

If you use Starship, add a custom module to ~/.config/starship.toml:

[custom.cc_usage]
command = """jq -r '["CC", (.sessionUsagePct|round|tostring)+"%", "·", (.weeklyUsagePct|round|tostring)+"%"] | join(" ")' ~/.claude/headroom-usage.json 2>/dev/null"""
when = 'test -f ~/.claude/headroom-usage.json'
format = "[$output]($style) "
style = "yellow"

Headroom shows the same numbers as a native macOS menu bar app — always visible, color-coded, with reset countdowns. No terminal, no jq required.

Download Headroom — free

or: brew install --cask patwalls/tap/headroom

Related