Skip to content
AgentAtlas

Claude Code statusline: custom status bar in settings.json with context %, cost and git branch

How do I set up a custom status line in Claude Code?

Run /statusline with a plain English description and Claude Code writes the script and updates your settings for you. To do it by hand, add a statusLine object with type "command" and a command path to ~/.claude/settings.json. Claude Code pipes session JSON to the script on stdin and shows whatever it prints.

Fastest way: the /statusline command

/statusline accepts natural language. It generates a script in ~/.claude/ and updates your settings automatically. Run it with no arguments to auto-configure from your shell prompt.

Inside Claude Code

/statusline show model name and context percentage with a progress bar

To remove it, run /statusline delete (or clear, or remove), or delete the statusLine field from settings.json.

Manual setup in settings.json

Add statusLine to user settings (~/.claude/settings.json) or project settings. Set type to "command" and point command to a script or an inline shell command.

~/.claude/settings.json

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}
  • padding: optional extra horizontal spacing in characters, default 0
  • refreshInterval: optional, re-runs the command every N seconds on top of event updates, minimum 1. Use it for clocks or data that changes while the session is idle

Inline one-liner with jq

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

Example script: model, folder and context usage

~/.claude/statusline.sh

#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

Make it executable

chmod +x ~/.claude/statusline.sh

The script needs jq installed. Claude Code reloads settings automatically and runs the script as soon as you save.

Useful JSON fields

  • model.id, model.display_name: current model
  • workspace.current_dir, workspace.project_dir: working and launch directory
  • cost.total_cost_usd: estimated session cost at list price, resets on /clear
  • cost.total_duration_ms, cost.total_lines_added, cost.total_lines_removed
  • context_window.used_percentage, context_window.remaining_percentage, context_window.context_window_size
  • rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage: only for claude.ai Pro and Max subscribers (or behind a Claude apps gateway with a spend limit), may be absent
  • workspace.git_worktree: present only inside a linked git worktree

Some fields can be null or absent early in a session. Use jq fallbacks such as jq -r '.rate_limits.five_hour.used_percentage // empty'.

When it updates

The script runs at session start, then again when a new assistant message arrives, /compact finishes, the permission mode changes, vim mode toggles, the command setting changes, or a refreshInterval timer fires. Updates are debounced at 300ms, and an in-flight run is cancelled if a new update triggers. The status line runs locally and uses no API tokens.

Sources

More Claude Code guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →