Status Line Setup Skill

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

Approach: Custom script (full control), ccstatusline (widget-based TUI), or Simple inline
Features: Git branch, project colors, token usage, session cost
Style: Powerline, Minimal, or Match terminal
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., "claude-opus-4-1") | | 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"

Best Practices

Keep it concise - Status line should fit on one line
Use colors sparingly - Make information scannable, not overwhelming
Cache expensive operations - Git status can be slow on large repos
Test manually first - Pipe mock JSON to script before configuring
Use jq for parsing - Reliable JSON extraction in bash
Handle missing data - Fields may be null or missing
Output to stdout only - Status line reads first line of stdout

Testing

Test scripts with mock JSON:

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/test"}}' | ./statusline.sh

Installation Script

Use scripts/install-statusline.sh to:

Copy status line script to ~/.claude/
Update settings.json
Create backup of existing configuration

Restore Previous Configuration

Backups are created with timestamps in ~/.claude/:

# List available backups
ls -la ~/.claude/*.backup.*

# Restore using restore script
~/.claude/plugins/cache/.../scripts/restore-statusline.sh

# Or manually
LATEST=$(ls -t ~/.claude/settings.json.backup.* 2>/dev/null | head -1)
if [[ -n "$LATEST" ]]; then
    cp "$LATEST" ~/.claude/settings.json
fi

Additional Resources

For detailed implementation guidance, see the references directory:

references/json-input-schema.md - Complete JSON input documentation with all fields, extraction examples in Bash/Python/Node.js, and handling null values
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

Agent Skills: Status Line Setup

Install this agent skill to your local

Skill Files