Custom status line

What it does

The statusLine setting in your settings.json runs a shell command every few seconds and displays its output in Claude Code's status bar—that persistent line at the top of the terminal. You control what appears: current branch, test status, pending changes, time, environment variables, anything your shell can print.

{
  "statusLine": "git branch --show-current | tr -d '\\n'; echo ' | ' ; npm run status:check 2>/dev/null || echo 'no tests'"
}

The command's stdout is captured and shown live. Each time Claude Code runs a tool that might change state (git operations, npm install, file edits), the statusLine re-executes, keeping your context fresh without manual checking.

When to use it

Use it when you want critical project state always visible without context-switching to a separate terminal tab:

• Branch tracking during multi-branch work — see which branch you're on at a glance
• Test health — pipe test output or a custom health check that shows pass/fail counts
• Pending changes — git status --porcelain | wc -l displays unstaged file count
• Deployment readiness — check if current branch is deployable (e.g., npm run check status)
• Time tracking — date "+%H:%M" for session time awareness
• Environment flags — show $NODE_ENV or feature flags active in this session

The status bar is always visible, so mission-critical checks belong here. Fluff (uptime, weather) should not—reserve the space for decisions that affect your work right now.

Try it yourself

Run /statusline-setup to configure your status line interactively, or manually edit your settings.json file and write a simple shell command that outputs useful info. Keep it under 60 characters so it fits the terminal width. Test it locally first by running the command directly in your shell, then copy the working command into the statusLine field. Restart Claude Code to see it in action.

Gotchas

Output format: The shell command's output is taken literally—no newlines, just trimmed whitespace. Multi-line output collapses to a single line, so pipe tr -d '\n' to strip line breaks if needed.

Performance: If your command is slow (e.g., a git operation on a large repo), the entire status bar blocks until it completes. Keep commands under 500ms. Avoid git fetch or expensive network calls—use local-only checks like git rev-parse --abbrev-ref HEAD.

Error handling: Stderr is discarded; only stdout is shown. If your command fails (non-zero exit), nothing appears in the status bar. Chain fallbacks with || so the bar always has content: command-that-might-fail || echo 'fallback'.

Escaping: Inside the JSON string, backslashes must be escaped (\\n not \n). Single quotes work fine; double-quote them if using echo.