What is custom-statusline?

The custom-statusline skill enhances the Claude Code CLI experience by providing a highly configurable, information-rich status bar. It integrates real-time Git status, Anthropic API usage tracking, and context window monitoring using Nerd Font icons and ANSI colors to improve developer productivity and resource awareness.

When should I use custom-statusline?

custom-statusline is useful in the following scenarios: • API Usage Monitoring: Track 5-hour and 7-day Anthropic API consumption percentages directly in your terminal to manage rate limits effectively. • Git Workflow Integration: View current branch names, file modification counts, and ahead/behind status instantly without running separate git commands. • Context Window Management: Monitor the percentage of context window usage in real-time to decide when to compact or reset the session for optimal performance. • CLI Environment Customization: Personalize the Claude Code interface with professional Nerd Font symbols and color-coded system information for a more intuitive workspace.

name	custom-statusline
description	Set up custom Claude Code status line with Nerd Font icons, colors, git status, usage tracking, system info, and project context. NO EMOJIS - only Nerd Font icons and symbols. Use when configuring statusline, setting up status bar, or customizing Claude UI. Triggers with statusline, status bar, custom theme.

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
Color-coded by usage level

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)"

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

custom-statusline

When & Why to Use This Skill

Use Cases