Building a Custom Claude Code Statusline

Claude Code has a built-in statusline feature that lets you display custom information at the bottom of your terminal while you work. By default it’s blank, but you can point it at any script that reads JSON from stdin and outputs text.

Here’s what ours looks like:

Six lines of real-time session data: git status, model info, context window usage, session timer, cost tracking, and rotating tips. All rendered with ANSI colors from a single bash script.

The Setup

The statusline is a standalone bash script forked from cc-statusline by @chongdashu. No npm install required — just drop the script at ~/.claude/statusline.sh and make it executable. The only optional dependency is jq for faster JSON parsing (it falls back to grep/sed if jq isn’t available).

To enable it, add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

Claude Code pipes JSON session data to your script via stdin. The script parses it, grabs some extra info from git and ~/.claude/settings.json, and prints colored text back. That’s the whole interface.

What It Displays

Line 1 — Directory & Git: Current working directory, branch name, uncommitted changes (+added ~modified -deleted), commits ahead/behind remote, time since last commit, and stash count.

Line 2 — Environment: Which model you’re using (Opus, Sonnet, Haiku), Claude Code version, output style, MCP server count, and hooks count.

Line 3 — Context Usage: A 60-character progress bar showing how much of the context window you’ve consumed. Colors shift from mint green (≤50%) to peach (51-70%) to coral red (≥71%) so you know when it’s time to /compact.

Line 4 — Session Timer: Time until your 5-hour rolling session resets, with a mini progress bar.

Line 5 — Cost & Tokens: Total session cost in USD, burn rate per hour, input/output token split, and tokens per minute.

Line 6 — Tips: A rotating tip that changes every minute — keyboard shortcuts, slash commands, and workflow suggestions.

How It Works

The script is straightforward bash. It reads JSON from stdin, extracts fields, and prints formatted output. The interesting design choice is dual JSON parsing — it checks for jq on startup and uses it if available, but falls back to pure bash grep/sed parsing if not:

HAS_JQ=0
if command -v jq >/dev/null 2>&1; then
  HAS_JQ=1
fi

This means the statusline works on any system regardless of what’s installed. Same pattern for git — if you’re not in a repo, the git line just doesn’t appear.

The context bar uses dynamic ANSI 256-color codes that shift based on percentage:

if [ "$context_used_pct" -le 50 ]; then
  context_color() { printf '\033[38;5;158m'; }   # mint green
elif [ "$context_used_pct" -le 70 ]; then
  context_color() { printf '\033[38;5;216m'; }   # peach
else
  context_color() { printf '\033[38;5;210m'; }   # coral red
fi

The tip rotation is minimal — index into an array using the current Unix timestamp divided by 60:

tip_index=$(( $(date +%s) / 60 % ${#tips[@]} ))
printf '\n💡 %s%s%s' "$(tip_color)" "${tips[$tip_index]}" "$(rst)"

Customizing It

The script is meant to be forked and edited. A few things you might want to change:

Colors — Each element has a named color function near the top of the script. Change the ANSI 256-color codes to match your terminal theme:

dir_color()     { printf '\033[38;5;117m'; }  # sky blue
model_color()   { printf '\033[38;5;147m'; }  # light purple
cost_color()    { printf '\033[38;5;222m'; }  # light gold

Progress bar width — The context bar defaults to 60 characters. Change the second argument:

context_bar=$(progress_bar "$context_used_pct" 60)

Tips — The tips array is just a bash array. Add your own, remove ones you’ve memorized, or change the rotation speed by adjusting the 60 divisor.

Key Takeaways

• Claude Code’s statusLine setting accepts any script that reads JSON from stdin and outputs text
• Our fork of cc-statusline is a standalone bash script with git integration, context tracking, and cost monitoring — no npm required
• The script uses graceful degradation throughout — jq or bash fallback, git or no git, missing fields get sensible defaults
• Everything is customizable by editing the script directly

Links

• Our fork: github.com/mmasters/cc-statusline
• Original project: github.com/chongdashu/cc-statusline