skip to content

How does a Claude Code statusLine command receive session data, and how would you script a footer showing the git branch and context use?

level: middleimportance: should knowfreq 12%

answer

  1. a shell command in settings
  2. JSON in, text out
  3. stdin, not arguments
  4. null early, so add a fallback
  5. COLUMNS instead of tput

basics

~20 s

Claude Code runs the statusLine command from settings with session JSON on stdin and shows whatever it prints to stdout. A script reads workspace.current_dir and context_window.used_percentage, asks git for the branch, and echoes one line.

solid answer

~40 s

Add a `statusLine` object to `~/.claude/settings.json` or project settings with `type: "command"` and a `command` that is a script path or inline shell; `/statusline` can generate one for you from a plain-language description. Claude Code runs it with a JSON object on stdin, including `model.display_name`, `workspace.current_dir`, `context_window.used_percentage`, `cost.total_cost_usd` and `output_style.name`, and displays what the command prints to stdout. The JSON has no branch field outside worktree sessions, so the script runs `git branch --show-current` itself. Read optional or nullable fields with fallbacks such as jq's `// 0`. Each printed line becomes a row, ANSI colours and OSC 8 links work, and width comes from the `COLUMNS` variable because the output is captured rather than sent to the terminal. It runs locally and uses no API tokens.

code

bash · 10 lines
bash
#!/bin/bash
# ~/.claude/statusline.sh - Claude Code pipes session JSON to stdin
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# used_percentage can be null early in a session, so fall back to 0
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# The JSON has no branch outside worktree sessions, so ask git
BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
echo "[$MODEL] ${DIR##*/}${BRANCH:+ on $BRANCH} | ${PCT}% context"

go deeper

for a junior

Recall that statusLine in settings names a command, the command reads JSON from stdin and prints the footer, and /statusline can write the script for you.

for a middle

Explain the stdin-to-stdout contract, the useful fields, why nullable fields need fallbacks, and why the branch comes from git rather than the JSON.

for a senior

Show production habits: COLUMNS instead of tput, mock-JSON tests, null-safe reads, and treating a repository-supplied statusLine as code that needs review before trusting the folder.

for a principal

Judge whether a team-wide status line belongs in shared project settings at all, given every developer's terminal, tools such as jq, and trust prompts differ.

## The contract The **status line** is a customizable row at the bottom of Claude Code that runs a shell command you configure. The contract is small: 1. Claude Code runs your command. 2. It writes a **JSON object describing the session to the command's stdin**. 3. It displays whatever the command prints to **stdout**, one row per line. The status line runs locally and does not consume API tokens. It renders in its own row above the built-in footer badges and does not replace them, though with a custom status line Claude Code stops showing most footer keyboard hints, such as `esc to interrupt`. ## Configuring it Put a `statusLine` object in user settings (`~/.claude/settings.json`) or project settings: ```json { "statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 2 } } ``` - `type` is `"command"`, and `command` is a script path or an inline shell command, since it runs in a shell. - `padding` adds horizontal spacing in characters; default `0`. - `refreshInterval` re-runs the command every N seconds on top of event updates. - `hideVimModeIndicator` hides the built-in `-- INSERT --` text when your script renders `vim.mode` itself. The shortcut is `/statusline`: describe what you want, or run it without arguments to build one from your shell prompt, and Claude Code writes a script in `~/.claude/` and updates your settings. Settings reload automatically when saved. ## Fields worth knowing | Field | What it holds | |---|---| | `model.display_name` | The current model's display name | | `workspace.current_dir`, `workspace.project_dir` | Current directory, and where Claude Code was launched | | `context_window.used_percentage` | Pre-calculated share of the context window in use; may be `null` early | | `cost.total_cost_usd` | A client-side session cost estimate | | `output_style.name` | The active output style | | `pr.number`, `pr.url` | The open pull request for the branch, when one is found | | `worktree.branch` | Branch name, present only in a worktree session | | `session_id` | Stable per session, useful as a cache key | What the context and cost figures mean is a separate subject; the status line's job is to render them. Several fields are absent or `null` at times, so read every one with a fallback. ## Writing the script A footer with branch and context use needs `jq` for the JSON and `git` for the branch, because outside a worktree session the JSON carries no branch name: ```bash #!/bin/bash input=$(cat) DIR=$(echo "$input" | jq -r '.workspace.current_dir') PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1) BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null) echo "${DIR##*/}${BRANCH:+ on $BRANCH} | ${PCT}% context" ``` Make it executable with `chmod +x`, then test it outside Claude Code by piping mock JSON into it before wiring it into settings. ## Output rules - **Multiple lines:** each `echo` or `print` becomes its own row. - **Colours:** ANSI escape codes such as `\033[32m` work if the terminal supports them. - **Links:** OSC 8 sequences make clickable text in terminals that support hyperlinks; `printf '%b'` handles the escapes more reliably than `echo -e`. - **Width:** Claude Code captures the output instead of connecting it to the terminal, so `tput cols` cannot see the terminal size. Read the `COLUMNS` and `LINES` variables, which Claude Code sets before running the script. - **Brevity:** the row is narrow, and notifications can share it outside fullscreen rendering, so long output truncates. ## Common mistakes - **Printing to stderr.** Only stdout is displayed; stderr is visible through `claude --debug`. - **Forgetting the executable bit.** A script path needs `chmod +x`, or nothing appears. - **Assuming a field exists.** `pr` appears only while an open pull request is found, `rate_limits` only for some account types and after the first response, and `worktree` only in worktree sessions. - **Running slow commands every time.** The script runs often, so `git status` in a large repository adds lag; cache it per `session_id`. - **Backslashes on Windows.** With Git Bash installed, backslashes in the `command` path are consumed as escape characters; write the path with forward slashes. ## Adjacent customisation Colours of the interface itself are a separate setting: `/theme` picks a preset or a custom theme stored as JSON in `~/.claude/themes/`. Rows for running subagents can be rendered by a separate `subagentStatusLine` command.

  • Why does tput cols give the wrong width inside a status-line script, and what do you use instead?
    Claude Code captures the script's output rather than connecting it to the terminal, so `tput cols` and language-level width detection cannot read the terminal size. Claude Code sets `COLUMNS` and `LINES` to the current terminal dimensions before running the script, so size the output from those.
  • How do you test a status-line script without starting a Claude Code session?
    Pipe mock JSON into it, for example `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25}}' | ./statusline.sh`. Include a case with fields missing or null, since a real session sends `null` for `used_percentage` early and omits optional objects such as `pr`.
  • Can a repository ship a status line for everyone who clones it?
    Yes: `statusLine` is accepted in project settings. Because it executes a shell command, Claude Code applies the same workspace trust rule as hooks in settings files, so it stays blank until the folder is trusted. Treat it like a hook and review the script before trusting a repository that brings one.

  • The status line command receives session data as command-line arguments.
  • Every status line refresh spends API tokens.
  • The session JSON always includes the git branch.
  • tput cols inside the script reads the real terminal width.
  • context_window.used_percentage is always a number from the first render.
  • Anything the script writes to stderr appears in the status line.