Claude Code Status Line Maker

1 · Choose your elements

2 · Put them in order

Nothing selected yet — tick an element above and it lands here.

3 · Preview

4 · Take it home

What the Claude Code status line is

The status line is the single line Claude Code pins to the bottom of your terminal — the same idea as a shell prompt or a tmux status bar, but scoped to your session with Claude. Out of the box it's minimal. With one setting, it becomes yours: which model is on duty, what branch you're about to let an AI loose on, what this session has cost so far — whatever you can print, it can show.

The mechanism is refreshingly blunt: you point Claude Code at any executable. It runs your command, feeds it a JSON blob of session state on stdin, and displays whatever your command prints. That's the whole contract. Everything on this page is detail.

Three ways to set one up

1. Ask Claude Code to do it (easiest)

Claude Code has a built-in /statusline command that takes plain-English instructions and writes the script for you. That's what the generator above produces: a precise instruction, so you get exactly the line you designed instead of whatever the model improvises. Paste, press enter, done.

2. Use a ready-made script

Flip the output above to Script + settings.json for a finished shell script and the setting that wires it in. You see every line before it runs — the reasonable instinct for anything that executes on every update.

3. Write your own

Any executable works — bash, Python, Node, a compiled binary. Read JSON from stdin, print one line to stdout. The stdin reference below is everything your script will be handed.

statusLine in settings.json

The setting lives in ~/.claude/settings.json (all sessions) or a project's .claude/settings.json (that project only — handy for a per-repo status line):

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

What your command receives on stdin

On every update, Claude Code pipes a JSON object like this to your command:

{
  "session_id": "abc123-...",
  "transcript_path": "/Users/you/.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/you/projects/my-app",
  "version": "2.1.205",
  "model": {
    "id": "claude-opus-4-8",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/Users/you/projects/my-app",
    "project_dir": "/Users/you/projects/my-app"
  },
  "output_style": { "name": "default" },
  "cost": {
    "total_cost_usd": 0.42,
    "total_duration_ms": 754321,
    "total_api_duration_ms": 98765,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15500,
    "total_output_tokens": 1200,
    "context_window_size": 200000,
    "used_percentage": 8,
    "remaining_percentage": 92
  },
  "exceeds_200k_tokens": false
}

How rendering actually works

• Every line you print is a row. A single line is the common case (and all this generator makes), but each additional echo renders as its own row above the built-in footer — handy for a second line with a context bar. Keep it tight; the status area has limited width.
• Updates are event-driven, debounced at ~300 ms. The line refreshes after each new assistant message, after /compact, and on permission- or vim-mode changes — not on a clock. So a "live" seconds counter won't tick between messages unless you set refreshInterval (see the settings table) to also re-run on a timer.
• ANSI escape codes render. \033[36m gets you cyan, not garbage. Dim (\033[2m) is the workhorse — status lines read best quiet.
• It runs in your session's directory, so git branch --show-current and friends work with no extra plumbing.
• Silence is allowed. Empty output or a failing command just means no status line — Claude Code carries on.

Worked examples

The minimalist

Model and folder. Enough to never again wonder which terminal tab is burning Opus tokens.

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
printf '%s │ %s' "$model" "$dir"

The git-aware

Adds the branch, with a * when the tree is dirty — the single most useful character an AI-assisted coder can keep in view.

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
cwd=$(echo "$input" | jq -r '.workspace.current_dir')
branch=$(git -C "$cwd" branch --show-current 2>/dev/null)
dirty=$(git -C "$cwd" status --porcelain 2>/dev/null | head -1)
[ -n "$dirty" ] && branch="${branch}*"
out="$model"
[ -n "$branch" ] && out="$out │ $branch"
printf '%s' "$out"

The spend-watcher

Cost, session length, and the diff Claude has racked up. For anyone on a budget — which is everyone.

#!/usr/bin/env bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0' | awk '{printf "$%.2f", $1}')
mins=$(( $(echo "$input" | jq -r '.cost.total_duration_ms // 0') / 60000 ))
added=$(echo "$input" | jq -r '.cost.total_lines_added // 0')
removed=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
printf '%s │ %sm │ +%s -%s' "$cost" "$mins" "$added" "$removed"

Troubleshooting

FAQ

pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
printf '%s%%' "$pct"