custom-statusline

Custom Status Line Setup

Sets up a comprehensive Claude Code status line with Nerd Font icons only (no emojis), ANSI colors, real-time usage tracking, git integration, and system monitoring.

Quick Start: Interactive Configuration

Run the /custom-statusline command to interactively configure your status line. It will ask which elements you want:

• Current directory - Working directory path
• Nerd Font icons - All icons (os, git, clock, usage) - all or nothing
• Git branch & status - Branch, dirty/clean, ahead/behind, stash
• Model name - Current Claude model
• Session duration - Time elapsed in session
• API usage (5h/7d) - Claude API usage percentages
• Context % till compact - Context window usage

The command will save your preferences to ~/.claude/statusline-config.json and configure settings to use the plugin's script.

Features

Git Integration

• Clean/dirty status indicator
• Modified file count
• Ahead/behind tracking
• Stash count display
• Branch name with color coding

Usage Tracking

• 5-hour and 7-day usage percentages from Anthropic API
• Color-coded thresholds (green <50%, yellow 50-80%, red >80%)
• Cached for 60 seconds to avoid API spam

Context Display

• Session context window percentage with visual progress bar
• Uses Claude Code's pre-calculated used_percentage for accuracy
• Color-coded thresholds matching community best practices:
  • Green (<50%): Safe zone
  • Yellow (50-80%): Approaching limit
  • Red (>80%): Near auto-compact trigger
• Example: ctx:45% ▓▓▓▓░░░░░░

Cost & Duration

• Total duration in minutes

How It Works

• Script: Stays in the plugin folder at ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.sh
• Config: Saved to ~/.claude/statusline-config.json (persists across plugin updates)
• Settings: Points to the plugin's script via dynamic lookup

Manual Setup

If you prefer manual setup instead of the command:

Step 1: Create Config File

Create ~/.claude/statusline-config.json:

{
  "show_cwd": true,
  "show_icons": true,
  "show_git": true,
  "show_model": true,
  "show_duration": true,
  "show_usage": true,
  "show_context": true
}

Step 2: Update Claude Settings

Update ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash -c \"$(find ~/.claude/plugins/cache/zeul-claude-plugins/custom-statusline -name statusline.sh 2>/dev/null | head -1)\""
  }
}

Step 3: Test Status Line

echo '{}' | bash -c "$(find ~/.claude/plugins/cache/zeul-claude-plugins/custom-statusline -name statusline.sh | head -1)"

Best Practices

This plugin follows community-recommended best practices for Claude Code statuslines:

Why Context Tracking Matters

Claude Code has a 200K token context window and automatically runs /compact at ~80% usage. Without visibility, you won't know you're approaching the limit until context is lost.

Design Principles

• Keep it scannable - Glance and get info in under a second
• Use pre-calculated values - used_percentage from Claude Code is more accurate than manual token math
• Color-code thresholds - 50%/80% boundaries match when to pay attention vs take action
• Cache API calls - 60-second cache prevents rate limiting and improves performance

References

• Creating The Perfect Claude Code Status Line
• Custom Claude Code Statusline: Track Context
• How to Customize Your Claude Code Status Line

Requirements

Essential

• Nerd Font installed - For icons (JetBrains Mono, Hack, FiraCode, etc.)
• jq installed - For JSON parsing (brew install jq)
• Git installed - For git features
• curl - For API usage fetching

Platform-Specific (macOS)

• security - Keychain access for API token

Troubleshooting

Icons not showing: Install a Nerd Font and configure your terminal to use it

No git branch: Script shows nothing when not in a git repository

Usage shows 0%: API call failed. Check:

• Keychain has "Claude Code-credentials"
• Internet connection active
• API endpoint accessible

Slow status line: Increase cache_max_age in the script to reduce API calls

Reconfigure: Run /custom-statusline again to change your preferences