statusline-setup

Status Line Setup

Create and customize Claude Code status lines to display contextual information like model name, git branch, token usage, project colors, and more.

Overview

Claude Code supports custom status lines displayed at the bottom of the interface. Status lines update when conversation messages change, running at most every 300ms.

Interactive Setup Flow

When setting up a status line, first check for existing configuration and use AskUserQuestion to gather preferences.

Pre-Check: Existing Status Line

# Check for existing configuration
if [[ -f ~/.claude/settings.json ]]; then
    EXISTING=$(jq -r '.statusLine // empty' ~/.claude/settings.json)
    if [[ -n "$EXISTING" ]]; then
        # User has existing status line - ask about backup
    fi
fi

Setup Questions

1. Approach: Custom script (full control), ccstatusline (widget-based TUI), or Simple inline
2. Features: Git branch, project colors, token usage, session cost
3. Style: Powerline, Minimal, or Match terminal
4. Editor: Cursor, VS Code, Sublime, or None (for clickable links)

Two Approaches

1. Manual Script (Full Control)

Create a shell script that receives JSON data via stdin and outputs a single line with ANSI colors.

Quick setup:

cat > ~/.claude/statusline.sh << 'EOF'
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
echo "[$MODEL] $DIR"
EOF
chmod +x ~/.claude/statusline.sh

Configure in settings:

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

2. ccstatusline (Widget-Based)

Use the third-party ccstatusline for a widget-based approach with TUI configuration.

Quick setup:

bunx ccstatusline@latest

Configure in settings:

{
  "statusLine": "bunx ccstatusline@latest"
}

JSON Input Structure

The status line command receives structured JSON via stdin:

Field	Description
model.id	Model identifier (e.g., "provider/model-id")
model.display_name	Human-readable name (e.g., "Opus")
workspace.current_dir	Current working directory
workspace.project_dir	Original project directory
cost.total_cost_usd	Session cost in USD
cost.total_duration_ms	Total session duration
context_window.context_window_size	Max context size
context_window.current_usage	Current token usage object
transcript_path	Path to session transcript JSON
session_id	Unique session identifier

Common Patterns

Git Branch Display

if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    DIRTY=""
    git diff --quiet HEAD 2>/dev/null || DIRTY="*"
    echo "[$MODEL] $BRANCH$DIRTY"
fi

Context Usage Percentage

USAGE=$(echo "$input" | jq '.context_window.current_usage')
if [ "$USAGE" != "null" ]; then
    TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')
    SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
    PERCENT=$((TOKENS * 100 / SIZE))
    echo "Context: ${PERCENT}%"
fi

Peacock Project Colors

SETTINGS=".vscode/settings.json"
if [[ -f "$SETTINGS" ]]; then
    COLOR=$(jq -r '.["peacock.color"] // empty' "$SETTINGS")
fi

Clickable File Links (OSC 8)

FILE_URL="vscode://file${LAST_FILE}"
echo -e "\033]8;;${FILE_URL}\a${FILENAME}\033]8;;\a"

Reference Files

For detailed implementation guidance, consult:

• references/json-input-schema.md — Complete JSON input documentation with all fields, extraction examples in Bash/Python/Node.js, and null-value handling
• references/scripting-patterns.md — ANSI color codes (256-color and true color), Powerline separators, Git integration patterns, project detection, clickable links (OSC 8), terminal integration, and formatting helpers
• references/ccstatusline-guide.md — Complete widget documentation, installation, configuration options, available widgets, multi-line setup, and troubleshooting