Comprehensive Claude Code status line with Nerd Font icons, git status, API usage tracking, and interactive configuration

version
1.2.0

Install

/plugin install custom-statusline@zeul-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add zeulewan/zeul-claude-plugins.

Contents

Discovered from source

Skills 1

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

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

Commands 1

Custom Statusline Configuration

Configure the user's Claude Code status line by asking what elements they want displayed.

Step 1: Ask User Preferences

Use AskUserQuestion with these exact options (split into 2 questions due to 4-option limit):

Question 1 - Core elements:

Question: "Which core elements do you want in your status line?"
Header: "Core"
multiSelect: true
Options:
1. Label: "Current directory", Description: "Show working directory path"
2. Label: "Nerd Font icons", Description: "Show all icons (requires Nerd Font installed)"
3. Label: "Git branch & status", Description: "Show branch, dirty/clean, ahead/behind"
4. Label: "Model name", Description: "Show current Claude model"

Question 2 - Tracking elements:

Question: "Which tracking elements do you want?"
Header: "Tracking"
multiSelect: true
Options:
1. Label: "Session duration", Description: "Show time elapsed in session"
2. Label: "API usage (5h/7d)", Description: "Show Claude API usage percentages"
3. Label: "Context % till compact", Description: "Show context window usage"

Step 2: Write Config File

Based on user selections, write ~/.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
}

Set each value to true or false based on whether the user selected that option.

Step 3: Update Settings to Use Plugin Script

The statusline.sh script is included in the plugin. Update ~/.claude/settings.json to point to it using a shell wrapper that finds the plugin's script:

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

This wrapper dynamically locates the script in the plugin cache, so it survives plugin version updates.

Step 4: Notify User

Tell the user:

  • Configuration saved to ~/.claude/statusline-config.json
  • Script is provided by the plugin (no copy needed)
  • Settings updated to use the plugin's script
  • Restart Claude Code to see changes
  • Run /custom-statusline again to reconfigure

Sponsors

Details

Marketplace
zeulewan/zeul-claude-plugins
Source
plugins/custom-statusline
Category
Customization
Keywords
statusline, status, bar, theme, ui, nerd-font, configure

More from zeulewan/zeul-claude-plugins

All 6