Build a Custom Claude Code Statusline (with Rate Limits and a Bell on Done)

The default Claude Code statusline is honest but thin: model name, working directory, that's about it. After a few long sessions I wanted more from it. How much of the context window have I burned? Am I close to the 5-hour rate limit? Has the agent finished and I missed it because I was in another tab?

Claude Code lets you replace the statusline with any shell command. It pipes a JSON blob to stdin on every render and prints whatever your script writes to stdout. So the upgrade is just bash and jq.

Read full blog post on my website

This is the seven-field bar I ended up with, the script behind it, and the wiring in ~/.claude/settings.json. Setup is about three minutes if you have jq installed.

Key Takeaways

The statusline is a shell command Claude Code re-runs on every UI render. It receives a JSON payload on stdin.

The payload exposes the model, context-window percentage, cwd, transcript path, and the 5h + 7d rate-limit windows.

jq parses every field in one line. ANSI escapes color the output. No dependencies beyond bash, jq, and git.

For an "answer is ready" bell, use a Stop hook in settings.json, not the statusline. Claude Code renders the statusline inside its TUI so a \a from there gets eaten before it reaches the terminal. The Stop hook runs in a real shell and fires once per turn.

Wiring is two lines in ~/.claude/settings.json under the statusLine key.

What Claude Code gives you

When the statusline command runs, Claude Code hands it a JSON object on stdin. The shape (as of May 2026) looks like this:

{
  "model": { "display_name": "Claude Opus 4.7 (1M context)" },
  "context_window": { "used_percentage": 22.4 },
  "cwd": "/Users/me/Workspace/foo",
  "workspace": { "current_dir": "/Users/me/Workspace/foo" },
  "transcript_path": "/Users/me/.claude/projects/.../session.jsonl",
  "rate_limits": {
    "five_hour": { "used_percentage": 34, "resets_at": 1746540000 },
    "seven_day": { "used_percentage": 12, "resets_at": 1746799200 }
  }
}

The rate-limit fields are the interesting bit. They don't exist for every render. Right after a fresh /clear you won't see them until the first API response of the new session. The script has to tolerate their absence. Same for context: an empty field in the early frames.

You can inspect the payload yourself by setting the statusline to cat | jq . for one render, then switching back. Or just trust the script below.

The script

I keep mine at ~/.claude/statusline-command.sh. It does seven things, in order:

Model display name.
A 20-block context-usage bar with a percentage.
Git branch of the current workspace.
Session length, derived from the transcript file's birth time.
Folder name (basename of cwd).
5-hour rate-limit usage with a "resets in 2h15m" countdown.
7-day rate-limit usage with the same countdown.

#!/usr/bin/env bash
# Claude Code status line script

input=$(cat)

# 1. Model
model=$(echo "$input" | jq -r '.model.display_name // "Unknown model"')

# 2. Context bar
used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
if [ -n "$used_pct" ]; then
  filled=$(echo "$used_pct" | awk '{printf "%d", ($1 / 100) * 20}')
  empty=$((20 - filled))
  bar_filled=""
  bar_empty=""
  for i in $(seq 1 $filled); do bar_filled="${bar_filled}█"; done
  for i in $(seq 1 $empty);  do bar_empty="${bar_empty}░";  done
  ctx_display="${bar_filled}${bar_empty} $(printf '%.0f' "$used_pct")%"
else
  ctx_display="░░░░░░░░░░░░░░░░░░░░ --%"
fi

# 3. Git branch (read from cwd, no-optional-locks so we don't fight an
# ongoing git operation in the same repo)
cwd=$(echo "$input" | jq -r '.cwd // .workspace.current_dir // ""')
git_branch=""
[ -n "$cwd" ] && git_branch=$(git -C "$cwd" --no-optional-locks symbolic-ref --short HEAD 2>/dev/null)
[ -z "$git_branch" ] && git_branch="no-git"

# 4 & 5. Rate limits
five_pct=$(echo  "$input" | jq -r '.rate_limits.five_hour.used_percentage  // empty')
five_reset=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at       // empty')
week_pct=$(echo  "$input" | jq -r '.rate_limits.seven_day.used_percentage  // empty')
week_reset=$(echo "$input" | jq -r '.rate_limits.seven_day.resets_at       // empty')

format_ttl() {
  local reset_epoch="$1"
  [ -z "$reset_epoch" ] && { echo ""; return; }
  local now diff
  now=$(date +%s)
  diff=$(( reset_epoch - now ))
  if [ "$diff" -le 0 ]; then
    echo "now"
  else
    printf '%dh%02dm' "$(( diff / 3600 ))" "$(( (diff % 3600) / 60 ))"
  fi
}

five_display=""
if [ -n "$five_pct" ]; then
  ttl=$(format_ttl "$five_reset")
  five_display="5h: $(printf '%.0f' "$five_pct")%"
  [ -n "$ttl" ] && five_display="${five_display} (resets ${ttl})"
fi

week_display=""
if [ -n "$week_pct" ]; then
  ttl=$(format_ttl "$week_reset")
  week_display="7d: $(printf '%.0f' "$week_pct")%"
  [ -n "$ttl" ] && week_display="${week_display} (resets ${ttl})"
fi

# 6. Session age (transcript file birth time)
transcript=$(echo "$input" | jq -r '.transcript_path // empty')
session_age="--"
if [ -n "$transcript" ] && [ -f "$transcript" ]; then
  file_epoch=$(stat -f %B "$transcript" 2>/dev/null || stat -c %W "$transcript" 2>/dev/null)
  if [ -n "$file_epoch" ] && [ "$file_epoch" -gt 0 ]; then
    diff=$(( $(date +%s) - file_epoch ))
    session_age="$(( diff / 3600 ))h$(( (diff % 3600) / 60 ))m"
  fi
fi

# 7. Folder name
folder=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""' | xargs basename 2>/dev/null)
[ -z "$folder" ] && folder="."

# Colors
CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'
MAGENTA='\033[35m'; BLUE='\033[34m'; DIM='\033[2m'; BOLD='\033[1m'; RESET='\033[0m'

parts=()
parts+=("$(printf "${CYAN}${BOLD}%s${RESET}" "$model")")
parts+=("$(printf "${DIM}ctx${RESET} %s" "$ctx_display")")
parts+=("$(printf "${GREEN} %s${RESET}" "$git_branch")")
parts+=("$(printf "${DIM}session${RESET} ${YELLOW}%s${RESET}" "$session_age")")
parts+=("$(printf "${MAGENTA}%s${RESET}" "$folder")")
[ -n "$five_display" ] && parts+=("$(printf "${BLUE}%s${RESET}" "$five_display")")
[ -n "$week_display" ] && parts+=("$(printf "${BLUE}%s${RESET}" "$week_display")")

sep="$(printf "${DIM} │ ${RESET}")"
result=""
for part in "${parts[@]}"; do
  [ -z "$result" ] && result="$part" || result="${result}${sep}${part}"
done

printf "%b" "$result"

Three notes on the script.

The context bar uses awk for floating-point math because bash's arithmetic is integer only. The seq loop after it is the simplest way to repeat a Unicode box-drawing character N times without resorting to printf format quirks.

The session-age block uses stat -f %B on macOS (BSD stat) and falls back to stat -c %W on Linux (GNU stat). Both ask for the file's birth time, which on the transcript file lines up with when the Claude Code session started. If your filesystem doesn't track birth time the field shows -- and that's fine.

git --no-optional-locks is there so the statusline doesn't fight an in-progress git rebase or git commit in the same repo. Without it you can occasionally get spurious lock contention when the agent is mid-commit.

Wiring it in

Make the script executable and add the statusLine block to ~/.claude/settings.json:

chmod +x ~/.claude/statusline-command.sh

{
  "statusLine": {
    "type": "command",
    "command": "bash /Users/me/.claude/statusline-command.sh"
  }
}

Use the absolute path. Claude Code spawns the command without your shell's $HOME expansion, so ~/.claude/... will fail silently and you'll just see the default bar.

After saving, the next render picks it up. You don't need to restart anything.

The bell on done (the part I got wrong)

My first attempt put printf '\a' at the end of the statusline script, banking on the terminal to ring the ASCII bell character. I never heard a sound. The reason: Claude Code captures the script's stdout and renders it inside its own TUI, so the bell character is part of the displayed string rather than a control code reaching the terminal. It gets stripped or rendered as nothing. The statusline is the wrong surface for a bell.

The right surface is a Stop hook. Claude Code fires hooks at well-defined lifecycle events, and Stop runs once when the agent finishes a turn. The hook command runs in a real shell, so anything that makes noise will work.

Add this to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff &"
          }
        ]
      }
    ]
  }
}

afplay ships with macOS and the & puts the sound in the background so the hook returns immediately. On Linux, swap in paplay /usr/share/sounds/freedesktop/stereo/complete.oga & or printf '\a' > /dev/tty if your terminal honors the bell character.

The hook fires once per completed turn, which is what I actually wanted. No constant pinging during streaming, just a soft Glass chime when the answer is ready.

What I'd change next

Two things on the list. Cost-per-session would be useful, but Claude Code doesn't expose that in the payload yet, so it would mean reading the transcript and tallying. And a colored threshold on the context bar (yellow at 70%, red at 90%) is one awk branch away.

If you build a variant, send it. The script is small enough that everyone's version will look slightly different, and that's the point.

推荐订阅源