How to Customize Your Claude Code Status Line

Ever glanced at Claude Code and wondered which model you’re actually using? Or how much of the context window you’ve burned through? By default, this information is hidden away—but you can surface it right in your terminal.

A custom status line shows you what matters at a glance:

[Opus] Context: 12%

This tells you the active model and context usage without interrupting your flow. Let me show you how to set it up.

How the status line works#

Claude Code pipes JSON data to your status line script via stdin. Your script processes that data and outputs whatever text you want displayed.

The JSON contains everything you’d want to know: model info, token counts, costs, and workspace details.

Step 1: Create the status line script#

Create a new file at ~/.claude/statusline.sh:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

echo "[$MODEL] Context: ${PERCENT_USED}%"

The script reads JSON from stdin, extracts the fields we care about using jq, calculates the percentage, and outputs the formatted string.

Step 2: Make it executable#

chmod +x ~/.claude/statusline.sh

Step 3: Configure Claude Code#

Add the status line configuration to ~/.claude/settings.json:

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

If you already have settings in this file, add the statusLine block alongside your existing configuration.

Step 4: Restart Claude Code#

Close and reopen Claude Code. Your new status line should appear.

Available variables#

The script receives JSON with these fields:

Adding cost tracking#

Want to see how much your session is costing? Extend the script:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

printf "[%s] Context: %d%% | $%.2f" "$MODEL" "$PERCENT_USED" "$COST"

Now you’ll see something like: [Opus] Context: 12% | $0.45

Troubleshooting#

Status line not showing?

1. Check that jq is installed: brew install jq (macOS) or apt install jq (Linux)
2. Verify the script is executable: ls -la ~/.claude/statusline.sh
3. Restart Claude Code after making changes

Test your script manually:

echo '{"model":{"display_name":"Opus"},"context_window":{"total_input_tokens":1000,"total_output_tokens":500,"context_window_size":200000}}' | ~/.claude/statusline.sh

Should output: [Opus] Context: 0%

Taking it further#

The status line is one piece of the Claude Code customization puzzle. Once you’re comfortable with scripts like this, explore:

• Notification hooks Get Notified When Claude Code Finishes With Hooks Set up desktop notifications in Claude Code to know when Claude needs your input or permission. Learn how to use hooks for instant alerts instead of constantly checking. claude-code Nov 23, 2025 to get desktop alerts when Claude needs input
• Slash commands How to Speed Up Your Claude Code Experience with Slash Commands Learn how to transform Claude Code from a chatbot into a deterministic engine using Slash Commands. This guide covers the technical setup and a complete 'Full Circle' workflow that automates your entire feature lifecycle. aiclaude-code Nov 22, 2025 to automate repetitive tasks
• The full Claude Code feature stack Understanding Claude Code's Full Stack: MCP, Skills, Subagents, and Hooks Explained A practical guide to Claude Code's features — explained in the order they were introduced: MCP (2024), Claude Code core (Feb 2025), Plugins (2025), and Agent Skills (Oct 2025). What each does, how they fit together, and when to use what. claude-codeaimcp +2 Nov 9, 2025 for MCP, skills, and subagents

The status line script pattern—reading JSON from stdin and outputting formatted text—is the same foundation that powers many of Claude Code’s extensibility features.