Building a Custom Status Line for Claude Code

I spend most of my day in Claude Code. It's my pair programmer, code reviewer, and rubber duck all rolled into one. After a few days of using it, I realized I had no idea how many tokens I'd burned, how much the session was costing, or how close I was to filling the context window.

Every once in a while I'd run /cost, think "that's higher than I expected," and go back to work.

That lasted about a day.

I like dashboards. If I'm consuming resources or spending money, I want to see it happening in real time. I don't want another command I have to remember to run. I want to glance at the bottom of my terminal and immediately know what's going on.

So I built a custom status line.

Why

There were three things I wanted to see.

Cost

Claude Opus isn't free, and long sessions can get surprisingly expensive. Having a running total visible all the time changes how I work. It's the difference between checking your bank account once a month and having your balance on your phone's home screen.

When I see:

session:$1.47

I immediately know whether I'm still in "keep going" territory or whether it's time to wrap up the current task and start fresh.

Context

Claude Code automatically compacts conversations when you get close to the context limit, but I'd rather make that decision myself.

Watching:

ctx:81% left

slowly become

ctx:32% left

during a long refactor tells me it's probably time to commit what I have and open a new session before I lose momentum.

Note: The context percentage reported by the status line is the raw value Claude Code provides. In my experience, Claude will start warning that the context window is getting low when the status line still shows roughly 28% remaining. The warning itself says about 14% is left. My guess is Claude is intentionally conservative and reserves part of the context window for compaction and generating responses, so it alerts you well before you actually hit the limit. I haven't found official documentation confirming this behavior, but it's been consistent enough that I plan around the status line value rather than waiting for the warning.

Orientation

I'm constantly jumping between repositories and branches.

At a glance I want to know:

• What project am I in?
• What branch am I on?
• Which model am I using?
• How long has this session been running?

It's the same reason every shell prompt shows the current git branch. Reducing context switching is free productivity.

How It Works

The status line API is almost disappointingly simple.

You point Claude Code at a shell script. Every few seconds it pipes a JSON document to the script's stdin, and whatever the script prints becomes the status line.

That's it.

No SDK.

No framework.

No API.

Just stdin and stdout.

Even better, it costs nothing. Everything runs locally. Claude Code sends your script session information over local IPC, your script formats it, and the result gets rendered in the terminal. Refresh it every second for an entire workday if you want—it won't consume a single token.

Here's the JSON I'm interested in (trimmed down a bit):

{
  "cwd": "/Users/nsdrone/gitrepos/my-project",
  "model": {
    "id": "claude-opus-4-6",
    "display_name": "Opus"
  },
  "cost": {
    "total_cost_usd": 1.47,
    "total_duration_ms": 342000
  },
  "context_window": {
    "remaining_percentage": 81.8,
    "current_usage": {
      "input_tokens": 89400,
      "output_tokens": 12300,
      "cache_read_input_tokens": 64200
    }
  }
}

My script parses the JSON with a single jq call, formats everything, and prints:

~/gitrepos/my-project (main) »    Opus | 5m | in:89.4k out:12.3k cache:64.2k | ctx:81% left | session:$1.47

That's everything I care about and nothing I don't.

Step 1: Create the Script

Create ~/.claude/statusline.sh:

#!/bin/bash
# Claude Code status line — renders session info at the bottom of the terminal.
# Claude Code pipes session JSON to stdin every refreshInterval seconds;
# whatever this script prints to stdout becomes the status bar.

INPUT=$(cat)

# Single jq call extracts all fields at once. @sh produces shell-safe quoted
# strings so eval can assign them without word-splitting issues.
eval "$(echo "$INPUT" | jq -r '
  @sh "CWD=\(.cwd // empty)",
  @sh "GIT_BRANCH=\(.git.branch // empty)",
  @sh "MODEL=\(.model.display_name // .model // empty)",
  @sh "INPUT_TOKENS=\(.context_window.current_usage.input_tokens // 0)",
  @sh "OUTPUT_TOKENS=\(.context_window.current_usage.output_tokens // 0)",
  @sh "CACHE_READ=\(.context_window.current_usage.cache_read_input_tokens // 0)",
  @sh "COST_USD=\(.cost.total_cost_usd // 0)",
  @sh "CTX_REMAINING=\(.context_window.remaining_percentage // 100)",
  @sh "DURATION_MS=\(.cost.total_duration_ms // 0)"
')"

# Collapse /Users/whoever to ~ for a shorter path
CWD="${CWD/#$HOME/~}"

# 1234 → "1.2k", 1234567 → "1.2M", 500 → "500"
format_tokens() {
  local n=$1
  if [ "$n" -ge 1000000 ]; then
    printf "%s.%sM" "$((n / 1000000))" "$((n % 1000000 / 100000))"
  elif [ "$n" -ge 1000 ]; then
    printf "%s.%sk" "$((n / 1000))" "$((n % 1000 / 100))"
  else
    echo "$n"
  fi
}

# Under an hour: "12m". Over an hour: "1h23m".
format_duration() {
  local ms=$1
  local total_sec=$((ms / 1000))
  local min=$((total_sec / 60))
  local hrs=$((min / 60))
  local remaining_min=$((min % 60))
  if [ "$hrs" -ge 1 ]; then
    printf "%dh%dm" "$hrs" "$remaining_min"
  else
    printf "%dm" "$min"
  fi
}

IN=$(format_tokens "$INPUT_TOKENS")
OUT=$(format_tokens "$OUTPUT_TOKENS")
CACHE=$(format_tokens "$CACHE_READ")
COST=$(printf "\$%.2f" "$COST_USD")
DUR=$(format_duration "$DURATION_MS")

# Left side: working directory and branch
LEFT="$CWD"
if [ -n "$GIT_BRANCH" ]; then
  LEFT="$LEFT ($GIT_BRANCH)"
fi
LEFT="$LEFT »"

# Right side: model, duration, tokens, context remaining, cost
RIGHT="$MODEL | $DUR | in:$IN out:$OUT cache:$CACHE | ctx:${CTX_REMAINING}% left | session:$COST"

printf '%s    %s' "$LEFT" "$RIGHT"

Step 2: Make It Executable

chmod +x ~/.claude/statusline.sh

Step 3: Wire It Up

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

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "refreshInterval": 1
  }
}

The refresh interval is measured in seconds. I use 1 because I like seeing everything update in real time. If that's overkill, bump it to 5.

Step 4: Test It

You don't have to launch Claude Code to verify the script.

echo '{"cwd":"/Users/you/project","git":{"branch":"main"},"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000,"output_tokens":8000,"cache_read_input_tokens":32000},"remaining_percentage":78},"cost":{"total_cost_usd":0.83,"total_duration_ms":420000}}' | ~/.claude/statusline.sh

Expected output:

~/project (main) »    Opus | 7m | in:45.0k out:8.0k cache:32.0k | ctx:78% left | session:$0.83

Step 5: Restart Claude Code

Start a new session and your status line will be waiting at the bottom of the terminal.

Make It Yours

The best part is that it's just a shell script.

A few ideas:

• Add ANSI colors when context gets low.
• Show +256/-43 lines changed.
• Build a multi-line status bar.
• Add git dirty state.
• Add a progress bar.
• Whatever else you can do in bash.

If you don't want to write any of this yourself, Claude Code already has a shortcut:

/statusline show me model, branch, token counts, context percentage, and cost

It will generate and wire up a status line for you.

Final Thoughts

This was the first thing I customized in Claude Code, and it completely changed how I use it.

Once you realize that status lines, hooks, and other extension points are just shell scripts receiving structured JSON, the whole system starts to click. You stop thinking about "features" and start thinking about automation.

And that's where the fun begins.