Add a Claude Code status line

A Claude Code status line is a row at the bottom of that session. Claude Code runs a shell command you configure, passes JSON about the session on stdin, and prints whatever the command writes to stdout. The row sits above the built-in footer badges. It is how you keep the model, the directory, and the git branch visible in the terminal you are looking at. The setup below follows Claude Code's status line docs.

Set it with /statusline

In a Claude Code session, /statusline plus a description writes a script under ~/.claude/ and updates your settings. Approve the file edits if Claude asks.

/statusline show the model, the folder name, and the git branch

Run /statusline with no arguments and it auto-configures from your shell prompt, as the command list describes. To turn the row off, run /statusline delete, /statusline clear, or /statusline remove it. Deleting the statusLine field from the settings file does the same.

The statusLine setting

The setting is statusLine in ~/.claude/settings.json (every project) or in the project's .claude/settings.json. type is "command". command is a script path or an inline shell command. Add the field beside the settings you already have. This one-liner uses jq to print the model, the last segment of the directory, and the context percentage. used_percentage can be null early in a session, so // 0 keeps the line from printing the word null:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.workspace.current_dir | split(\"/\") | last) | \\(.context_window.used_percentage // 0)%\"'"
  }
}

Claude Code reloads settings on save and runs the command. The line stays blank until the command exits 0 and prints something. Install jq first (on a Mac with Homebrew, brew install jq); a missing jq makes this command fail, and a failing command leaves the row empty.

Three optional fields sit on the same object. padding is extra horizontal space in characters, default 0, on top of the interface's own spacing. refreshInterval is a number of seconds, minimum 1, and re-runs the command on that timer as well as on events. Leave it unset to run only on events. Set it for a clock, or when background subagents change git state while the main session is idle. hideVimModeIndicator set to true hides the built-in -- INSERT -- text when your script prints vim.mode itself. The same page documents all three.

JSON Claude Code passes on stdin

The command's standard input is one JSON object for this session. These are the fields the examples on this page use. Names and meaning are from the status line docs; that page has the full list, including rate limits, the prompt cache, and pull requests.

• model.id and model.display_name: the current model identifier and the name to print.
• cwd and workspace.current_dir: the current working directory. Both hold the same path. Prefer workspace.current_dir.
• workspace.project_dir: the directory where Claude Code was launched. It can differ from cwd if the working directory changes during the session.
• session_id: the session identifier. session_name is present after you set a name with the --name flag or /rename, or once an AI-generated title exists. The default short name, such as my-app-3f, does not fill session_name.
• context_window.used_percentage: a precomputed percentage of the context window in use. It, and context_window.remaining_percentage, can be null early in the session. context_window.current_usage is null before the first API call, and again after /compact until the next call. context_window.context_window_size is the maximum in tokens.
• cost.total_cost_usd: estimated session cost in USD, computed on your machine at list price unless a modelPricing table is in effect. It can differ from the bill. It resets to $0 when /clear starts a new session. cost.total_duration_ms is wall-clock time the session has been running.
• The git branch comes from git, in workspace.current_dir. worktree.branch is present only while the session is in a worktree session, and it is absent for hook-based worktrees. workspace.git_worktree is the linked worktree's name when the directory is a worktree from git worktree add, and it is absent in the main working tree.

A field the docs mark as absent is left out of the JSON. A field that is present and null is separate: jq -r prints the word null unless you give a fallback (// 0 or // empty). The script runs on your machine and does not spend API tokens.

Model, git branch, and directory

The one-liner can only print fields that are in the JSON. The branch comes from git, in the directory the JSON names. Save this as ~/.claude/statusline.sh. git -C runs in workspace.current_dir, which is the path the docs say is the session directory. git branch --show-current prints nothing when that directory is not a checkout, and nothing on a detached HEAD.

#!/bin/bash
# Claude Code writes session JSON to stdin.
# https://code.claude.com/docs/en/statusline
set -o pipefail
input=$(cat)

if ! command -v jq >/dev/null 2>&1; then
  echo "status line: install jq"
  exit 0
fi

model=$(printf "%s" "$input" | jq -r ".model.display_name // empty") || {
  echo "status line: jq could not parse stdin"
  exit 0
}
dir=$(printf "%s" "$input" | jq -r ".workspace.current_dir // .cwd // empty") || {
  echo "status line: jq could not parse stdin"
  exit 0
}
if [ -z "$model" ]; then
  model="?"
fi

folder=""
branch=""
if [ -n "$dir" ]; then
  folder=$(basename "$dir")
  # The branch is not a stdin field. Ask git in the session directory.
  branch=$(git -C "$dir" branch --show-current 2>/dev/null || true)
fi

if [ -n "$folder" ] && [ -n "$branch" ]; then
  printf "[%s] %s (%s)\n" "$model" "$folder" "$branch"
elif [ -n "$folder" ]; then
  printf "[%s] %s\n" "$model" "$folder"
else
  printf "[%s]\n" "$model"
fi

Mark it executable, then point command at it. A script that is not executable fails, and the row stays blank.

chmod +x ~/.claude/statusline.sh

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

Try it before trusting the setting. This feeds a small JSON document on stdin. The branch appears when $PWD is inside a git checkout:

echo "{\"model\":{\"display_name\":\"Opus\"},\"workspace\":{\"current_dir\":\"$PWD\"}}" | ~/.claude/statusline.sh

A checkout at ~/code/shop-web on branch feature-auth prints [Opus] shop-web (feature-auth). The docs' own walkthrough prints the model, the folder, and the context percentage, and their git example is the pattern this script follows. Bash covers macOS and Linux. On Windows, the docs' Windows section shows PowerShell and Git Bash, and paths in command use forward slashes.

When the line updates

The command runs once when the session starts, including when you resume one. After that it runs when a new assistant message arrives, when /compact finishes, when the permission mode changes, when vim mode toggles, when you change the command in settings, when a refreshInterval elapses, when a rate-limit window in the last JSON reaches its resets_at, and when a warm prompt cache in that JSON reaches its expires_at. Updates are debounced by 300ms, except a change to command itself, which runs immediately. If a new update arrives while the script is still running, Claude Code cancels the in-flight script. Editing the script shows up the next time a trigger runs it. The row hides while the help menu or a permission prompt is open.

With a custom status line configured, Claude Code stops showing most of the footer's keyboard hints, including esc to interrupt, ? for shortcuts, and hold space to speak. The footer badges stay. The status line does not replace them.

When the line stays blank

Claude Code shows the command's stdout only after it exits 0. Anything else leaves the row blank. claude --debug logs the script's stderr on every run, and the exit code on the first run of a session.

• The script is not executable. Run chmod +x ~/.claude/statusline.sh and check the path in command. ~ is your home directory.
• jq is missing, or the JSON did not parse. The one-liner then exits non-zero and the row is blank. The script on this page prints status line: install jq instead, and exits 0 so that message is visible. Install jq and run the echo test above.
• The script is slow. git status and git diff in a large repository block the row until they finish, and a newer update cancels a script that is still running, so the line looks stuck. git branch --show-current is the cheap question. The docs' caching example stores git output for a few seconds, keyed by session_id, when you do need the heavier commands. A short refreshInterval runs a slow script more often. Leave it unset unless the line shows a clock or git state that changes while the session is idle.
• The workspace is not trusted yet. Because statusLine runs a shell command, it waits on the same trust dialog as hooks. Until you accept it, claude --debug logs Status line command skipped: workspace trust not accepted. Start Claude Code again and accept the trust dialog.
• disableAllHooks set to true outside managed settings leaves only a statusLine from managed settings, so with no managed value the row stays off. allowManagedHooksOnly in managed settings does the same to a status line in your own settings file. The settings reference describes both gates.
• A value is null. jq -r prints null for .context_window.used_percentage before the first API response. Use // 0. Restarting Claude Code is the docs' next step if values stay empty after several messages.

Several sessions at once

Each claude process has its own status line, and the JSON is that process's session. The model, folder, and branch on the row tell you which checkout this terminal is. Set a name with /rename or start with --name when you want session_name in the JSON too. The default short name does not populate that field.

The row is inside the session on screen. A question in another window is not part of this stdin. Give each task its own checkout and its own tmux window or iTerm tab, and name the window for the branch. Run Claude Code in parallel with git worktrees is that layout: claude --worktree, one window per task, and what still collides. tmux's status line is the window list along the edge. Claude Code's status line is the row inside the pane.

AgentDock is the view across those sessions. It reads Claude Code sessions you already started, from ~/.claude and, where it can, from the terminal. Your statusLine script keeps running inside Claude Code. Each session is a dot on the screen edge: blue while the turn runs, amber when it is waiting on you, green when the turn finished, gray when idle. With the Claude Code hook on (Settings › Agents › Claude Code › Know when Claude Code needs you), amber means a permission prompt or a question, for a session in a window you are not looking at as well as the one in front. The hook applies to sessions started after you turn it on. The Inbox (⌃⌥I) collects the questions. The hover card shows the git branch, and a linked worktree is labeled with the repository name.

That works in tmux, iTerm, and cmux, which can also take a typed answer. Ghostty, Warp, Alacritty, and Terminal show the same dots; typing into those terminals goes through tmux. After the trial, the dots and the hover card keep working. The Inbox and ⌥⌥ need a license.