Claude Code Usage in Starship

A Starship custom module that shows your Claude Code session and weekly usage — reads Headroom's local JSON, no daemon required.

What it looks like

~/projects/myapp on main CC 72%·41% ❯

The CC indicator shows session % · weekly %. Color-coded: gray when low, amber when either hits 70%, red when either hits 90%. Disappears when Claude Code isn't running (file is stale or missing).

Starship config (starship.toml)

Add a [custom.claude] module to your ~/.config/starship.toml:

[custom.claude]
description = "Claude Code session and weekly usage from Headroom"
command = """
jq -r '
  if .sessionUsagePct == null then ""
  else
    (.sessionUsagePct | floor | tostring) + "%·" +
    (.weeklyUsagePct  | floor | tostring) + "%"
  end
' ~/.claude/headroom-usage.json 2>/dev/null
"""
when = "test -f ~/.claude/headroom-usage.json"
format = "[$output]($style) "
style = "yellow"
shell = ["sh", "-c"]

This hides automatically when the file doesn't exist (Headroom not installed, or Claude Code hasn't run yet).

Color-coded variant

Match Headroom's amber/red thresholds — amber at 70%, red at 90%:

[custom.claude]
description = "Claude Code usage — color-coded like Headroom"
command = """
jq -r '
  if .sessionUsagePct == null then ""
  else
    (.sessionUsagePct | floor) as $s |
    (.weeklyUsagePct  | floor) as $w |
    (if $s >= 90 or $w >= 90 then "red"
     elif $s >= 70 or $w >= 70 then "yellow"
     else "white" end) + ":" +
    ($s | tostring) + "%·" + ($w | tostring) + "%"
  end
' ~/.claude/headroom-usage.json 2>/dev/null
"""
when = "test -f ~/.claude/headroom-usage.json"
format = "CC [[$output](fg:${{split(output, ':')[0]}})]($style) "
style = "dimmed white"
shell = ["sh", "-c"]

Because the color is dynamic, this uses Starship's nested format syntax — the outer format uses $style dimmed, but the output itself carries the color name prefix.

Simpler approach: the output carries the color prefix

If nested format feels complex, output the colored text directly using ANSI codes in the command:

[custom.claude]
description = "Claude Code usage with inline ANSI color"
command = """
jq -r '
  if .sessionUsagePct == null then ""
  else
    (.sessionUsagePct | floor) as $s |
    (.weeklyUsagePct  | floor) as $w |
    (if $s >= 90 or $w >= 90 then "\u001b[31m"
     elif $s >= 70 or $w >= 70 then "\u001b[33m"
     else "\u001b[37m" end) as $c |
    $c + "CC " + ($s|tostring) + "%·" + ($w|tostring) + "%\u001b[0m"
  end
' ~/.claude/headroom-usage.json 2>/dev/null
"""
when = "test -f ~/.claude/headroom-usage.json"
format = "[$output]($style) "
style = ""
shell = ["sh", "-c"]

Prompt position

Add custom.claude to your format or right_format:

# Left prompt — before the ❯
format = """...${custom.claude}$character"""

# Right prompt (cleaner — doesn't eat left-side space)
right_format = """${custom.claude}"""

Include context window %

Headroom also tracks context window usage (contextUsagePct). Add a third number:

command = """
jq -r '
  if .sessionUsagePct == null then ""
  else
    (.sessionUsagePct | floor | tostring) + "%·" +
    (.weeklyUsagePct  | floor | tostring) + "%·" +
    (if .contextUsagePct != null then (.contextUsagePct | floor | tostring) + "%" else "" end)
  end
' ~/.claude/headroom-usage.json 2>/dev/null
"""

This outputs 23%·41%·64% — matching what Headroom v0.3.5 shows in the menu bar.

Testing the module

# Verify the JSON exists and has the right shape
jq '{sessionUsagePct,weeklyUsagePct,contextUsagePct}' ~/.claude/headroom-usage.json

# Test the command output directly
jq -r '(.sessionUsagePct | floor | tostring) + "%·" + (.weeklyUsagePct | floor | tostring) + "%"' ~/.claude/headroom-usage.json

# Reload Starship (just open a new terminal or source your RC)

Why this works without a daemon

Starship runs the command each time it renders the prompt — when you press Enter, the module runs jq, reads the current values from disk, and renders the output. Since Headroom keeps that file fresh (updated each time Claude Code renders its status line), the prompt always shows current numbers.

No background process. No polling interval. The read happens at prompt-render time, which is exactly when you want fresh data: right before you type the next command.

Install Headroom

brew install --cask patwalls/tap/headroom

Or download directly. Free, MIT, ~267 KB, signed + notarized. Once installed, the JSON file is written automatically.

→ Full shell prompt guide (zsh · bash · fish · Starship)
→ tmux status-right integration
→ How the statusLineHook works