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
- How to allow Claude Code to run all commands: permission modes, allow rules and skip permissions
- Claude Code permissions: allow, ask and deny rules, rule syntax and allowed tools
- Claude Code telemetry and data retention: what is sent and how to turn it off
- CLAUDE.md: where it goes, how it loads, and how it works with AGENTS.md
- Claude Code hooks: all events, exit codes, PreToolUse and PermissionRequest JSON, examples
- Claude Code subagents: create one, limit its tools, and call it
- Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes)
- Claude Code custom slash commands and skills (SKILL.md)
- Claude Code settings.json: file locations, precedence, and key settings
- Claude Code plugins and marketplaces: install, create, and share
- Claude Code headless mode: claude -p, --output-format json, --bare and CI flags
- Claude Code /model: switch models, aliases (opus, sonnet, haiku, opusplan), ANTHROPIC_MODEL and effort
- Claude Code /cost and /usage: check token spend, usage limits and reduce costs
- Claude Code VS Code extension: install, shortcuts, settings and /ide (works in Cursor too)
- MCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 Upgrade
- Subagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot (2026)
- Allow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 more (2026)
- How to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and more (2026)
- Claude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict mode
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 →