Claude Code usage in tmux status bar

If you work primarily in the terminal and tmux, you can show your Claude Code session and weekly usage in the tmux status bar — always visible at the bottom of the screen, no menu bar required. This snippet reads ~/.claude/headroom-usage.json on every tmux status refresh.

The JSON file is written by Claude Code's statusLine hook — the same source Headroom reads on macOS. You don't need Headroom installed; just the hook. Install the hook manually if you haven't already.

Basic status-right snippet

Add to ~/.tmux.conf:

# Claude Code usage in tmux status-right
# Reads session (5h) and weekly (7d) from ~/.claude/headroom-usage.json
# Example output: CC 23%·67%

set -g status-right '#(jq -r ""CC " + ((.sessionUsagePct // 0) | round | tostring) + "%·" + ((.weeklyUsagePct // 0) | round | tostring) + "%"" ~/.claude/headroom-usage.json 2>/dev/null || echo "CC --")  #H  %H:%M'
set -g status-interval 15
0:claude 1:term 2:vim CC 23%·67% hostname 14:32

status-interval 15 refreshes the status bar every 15 seconds — matches Headroom's refresh rate. Lower this to 5 for near-real-time updates (small overhead cost).

Color-coded version

Use tmux's color syntax to turn the text amber or red as limits approach:

# Color-coded Claude Code usage — amber at 70%+, red at 90%+
# Requires a script because tmux can't branch on shell output inline.

# 1. Create ~/bin/cc-usage-tmux (chmod +x)
#!/bin/bash
F="$HOME/.claude/headroom-usage.json"
[ -f "$F" ] || { echo "CC --"; exit; }
S=$(jq -r '.sessionUsagePct // 0 | . + 0.5 | floor' "$F" 2>/dev/null)
W=$(jq -r '.weeklyUsagePct // 0 | . + 0.5 | floor' "$F" 2>/dev/null)
MAX=$(( S > W ? S : W ))
if   [ "$MAX" -ge 90 ]; then COLOR="#[fg=red]"
elif [ "$MAX" -ge 70 ]; then COLOR="#[fg=yellow]"
else                         COLOR="#[fg=green]"
fi
echo "${COLOR}CC ${S}%·${W}%#[default]"
# 2. In ~/.tmux.conf
set -g status-right '#(~/bin/cc-usage-tmux)  #H  %H:%M'
set -g status-interval 15

With context window %

Show all three metrics — session, weekly, and context fill:

set -g status-right '#(jq -r ""CC " + ((.sessionUsagePct // 0) | round | tostring) + "%·" + ((.weeklyUsagePct // 0) | round | tostring) + "%·" + ((.contextUsagePct // 0) | round | tostring) + "%"" ~/.claude/headroom-usage.json 2>/dev/null || echo "CC --")  %H:%M'

Output: CC 23%·67%·41% (session · weekly · context).

In the status-left

Prefer the left side? Replace status-right with status-left and adjust your existing left content:

set -g status-left '#(jq -r ""CC " + ((.sessionUsagePct // 0) | round | tostring) + "%·" + ((.weeklyUsagePct // 0) | round | tostring) + "%"" ~/.claude/headroom-usage.json 2>/dev/null || echo "CC --") | [#S] '

Reloading the config

After editing ~/.tmux.conf, reload without restarting:

tmux source-file ~/.tmux.conf

Or from inside tmux: prefix + : then type source-file ~/.tmux.conf.

Why jq directly (not a separate daemon)

tmux runs the shell command on every status refresh. Reading a small local JSON file with jq is effectively free — ~1 ms, no persistent process, no network, no background daemon. Claude Code updates the file as you work; tmux reads it on each tick.

On macOS? Headroom shows the same meters in the native menu bar — always visible even when tmux isn't open. Free, zero config.

Download Headroom — free

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

Related