b-open-io/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