statusline-generator

Original source / Raw SKILL.md

---
name: statusline-generator
description: Configures and customizes Claude Code statuslines with multi-line layouts, cost tracking via ccusage, git status indicators, and customizable colors. Activates for statusline setup, installation, configuration, customization, color changes, cost display, git status integration, or troubleshooting statusline issues.
---

# Statusline Generator

## Overview

This skill provides tools and guidance for creating and customizing Claude Code statuslines. It generates multi-line statuslines optimized for portrait screens, integrates with `ccusage` for session/daily cost tracking, displays git branch status, and supports color customization.

## When to Use This Skill

This skill activates for:
- Statusline configuration requests for Claude Code
- Cost information display (session/daily costs)
- Multi-line layouts for portrait or narrow screens
- Statusline color or format customization
- Statusline display or cost tracking issues
- Git status or path shortening features

## Quick Start

### Basic Installation

Install the default multi-line statusline:

1. Run the installation script:
   ```bash
   bash scripts/install_statusline.sh
   ```

2. Restart Claude Code to see the statusline

The default statusline displays:
- **Line 1**: `username (model) [session_cost/daily_cost]`
- **Line 2**: `current_path`
- **Line 3**: `[git:branch*+]`

### Manual Installation

Alternatively, manually install by:

1. Copy `scripts/generate_statusline.sh` to `~/.claude/statusline.sh`
2. Make it executable: `chmod +x ~/.claude/statusline.sh`
3. Update `~/.claude/settings.json`:
   ```json
   {
     "statusLine": {
       "type": "command",
       "command": "bash /home/username/.claude/statusline.sh",
       "padding": 0
     }
   }
   ```

## Statusline Features

### Multi-Line Layout

The statusline uses a 3-line layout optimized for portrait screens:

```
username (Sonnet 4.5 [1M]) [$0.26/$25.93]
~/workspace/java/ready-together-svc
[git:feature/branch-name*+]
```

**Benefits:**
- Shorter lines fit narrow screens
- Clear visual separation of information types
- No horizontal scrolling needed

### Cost Tracking Integration

Cost tracking via `ccusage`:
- **Session Cost**: Current conversation cost
- **Daily Cost**: Total cost for today
- **Format**: `[$session/$daily]` in magenta
- **Caching**: 2-minute cache to avoid performance impact
- **Background Fetch**: First run loads costs asynchronously

**Requirements:** `ccusage` must be installed and in PATH. See `references/ccusage_integration.md` for installation and troubleshooting.

### Model Name Shortening

Model names are automatically shortened:
- `"Sonnet 4.5 (with 1M token context)"` → `"Sonnet 4.5 [1M]"`
- `"Opus 4.1 (with 500K token context)"` → `"Opus 4.1 [500K]"`

This saves horizontal space while preserving key information.

### Git Status Indicators

Git branch status shows:
- **Yellow**: Clean branch (no changes)
- **Red**: Dirty branch (uncommitted changes)
- **Indicators**:
  - `*` - Modified or staged files
  - `+` - Untracked files
  - Example: `[git:main*+]` - Modified files and untracked files

### Path Shortening

Paths are shortened:
- Home directory replaced with `~`
- Example: `/home/username/workspace/project` → `~/workspace/project`

### Color Scheme

Default colors optimized for visibility:
- **Username**: Bright Green (`\033[01;32m`)
- **Model**: Bright Cyan (`\033[01;36m`)
- **Costs**: Bright Magenta (`\033[01;35m`)
- **Path**: Bright White (`\033[01;37m`)
- **Git (clean)**: Bright Yellow (`\033[01;33m`)
- **Git (dirty)**: Bright Red (`\033[01;31m`)

## Customization

### Changing Colors

Customize colors by editing `~/.claude/statusline.sh` and modifying the ANSI color codes in the final `printf` statement. See `references/color_codes.md` for available colors.

**Example: Change username to blue**
```bash
# Find this line:
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m%s\n\033[01;37m%s\033[00m\n%s' \

# Change \033[01;32m (green) to \033[01;34m (blue):
printf '\033[01;34m%s\033[00m \033[01;36m(%s)\033[00m%s\n\033[01;37m%s\033[00m\n%s' \
```

### Single-Line Layout

Convert to single-line layout by modifying the final `printf`:

```bash
# Replace:
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m%s\n\033[01;37m%s\033[00m\n%s' \
    "$username" "$model" "$cost_info" "$short_path" "$git_info"

# With:
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m:\033[01;37m%s\033[00m%s%s' \
    "$username" "$model" "$short_path" "$git_info" "$cost_info"
```

### Disabling Cost Tracking

If `ccusage` is unavailable or not desired:

1. Comment out the cost section in the script (lines ~47-73)
2. Remove `%s` for `$cost_info` from the final `printf`

See `references/ccusage_integration.md` for details.

### Adding Custom Elements

Add custom information (e.g., hostname, time):

```bash
# Add variable before final printf:
hostname=$(hostname -s)
current_time=$(date +%H:%M)

# Update printf to include new elements:
printf '\033[01;32m%s@%s\033[00m \033[01;36m(%s)\033[00m%s [%s]\n...' \
    "$username" "$hostname" "$model" "$cost_info" "$current_time" ...
```

## Troubleshooting

### Costs Not Showing

**Check:**
1. Is `ccusage` installed? Run `which ccusage`
2. Test `ccusage` manually: `ccusage session --json --offline -o desc`
3. Wait 5-10 seconds after first display (background fetch)
4. Check cache: `ls -lh /tmp/claude_cost_cache_*.txt`

**Solution:** See `references/ccusage_integration.md` for detailed troubleshooting.

### Colors Hard to Read

**Solution:** Adjust colors for your terminal background using `references/color_codes.md`. Bright colors (`01;3X`) are generally more visible than regular (`00;3X`).

### Statusline Not Updating

**Check:**
1. Verify settings.json points to correct script path
2. Ensure script is executable: `chmod +x ~/.claude/statusline.sh`
3. Restart Claude Code

### Git Status Not Showing

**Check:**
1. Are you in a git repository?
2. Test git commands: `git branch --show-current`
3. Check git permissions in the directory

## Resources

### scripts/generate_statusline.sh
Main statusline script with all features (multi-line, ccusage, git, colors). Copy this to `~/.claude/statusline.sh` for use.

### scripts/install_statusline.sh
Automated installation script that copies the statusline script and updates settings.json.

### references/color_codes.md
Complete ANSI color code reference for customizing statusline colors. Load when users request color customization.

### references/ccusage_integration.md
Detailed explanation of ccusage integration, caching strategy, JSON structure, and troubleshooting. Load when users experience cost tracking issues or want to understand how it works.

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/install_statusline.sh

```bash
#!/usr/bin/env bash

# Install statusline script to Claude Code configuration directory
# Usage: ./install_statusline.sh [target_path]

set -e

# Determine target path
if [ -n "$1" ]; then
    TARGET_PATH="$1"
else
    TARGET_PATH="$HOME/.claude/statusline.sh"
fi

# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SOURCE_SCRIPT="$SCRIPT_DIR/generate_statusline.sh"

# Check if source script exists
if [ ! -f "$SOURCE_SCRIPT" ]; then
    echo "❌ Error: generate_statusline.sh not found at $SOURCE_SCRIPT"
    exit 1
fi

# Create .claude directory if it doesn't exist
CLAUDE_DIR=$(dirname "$TARGET_PATH")
if [ ! -d "$CLAUDE_DIR" ]; then
    echo "📁 Creating directory: $CLAUDE_DIR"
    mkdir -p "$CLAUDE_DIR"
fi

# Copy the script
echo "📋 Copying statusline script to: $TARGET_PATH"
cp "$SOURCE_SCRIPT" "$TARGET_PATH"
chmod +x "$TARGET_PATH"

# Update settings.json
SETTINGS_FILE="$HOME/.claude/settings.json"

if [ ! -f "$SETTINGS_FILE" ]; then
    echo "⚠️  Warning: settings.json not found at $SETTINGS_FILE"
    echo "   Please create it manually or restart Claude Code"
    exit 0
fi

# Check if statusLine already configured
if grep -q '"statusLine"' "$SETTINGS_FILE"; then
    echo "✅ statusLine already configured in settings.json"
    echo "   Current configuration will use the updated script"
else
    echo "📝 Adding statusLine configuration to settings.json"

    # Backup settings.json
    cp "$SETTINGS_FILE" "$SETTINGS_FILE.backup"

    # Add statusLine configuration using jq
    jq '. + {"statusLine": {"type": "command", "command": "bash '"$TARGET_PATH"'", "padding": 0}}' "$SETTINGS_FILE.backup" > "$SETTINGS_FILE"

    echo "✅ statusLine configuration added"
    echo "   Backup saved to: $SETTINGS_FILE.backup"
fi

echo ""
echo "🎉 Installation complete!"
echo ""
echo "Next steps:"
echo "  1. Restart Claude Code to see your new statusline"
echo "  2. The statusline will show:"
echo "     Line 1: username (model) [session_cost/daily_cost]"
echo "     Line 2: current_path"
echo "     Line 3: [git:branch]"
echo ""
echo "Note: Cost information requires ccusage to be installed and accessible"
```

### scripts/generate_statusline.sh

```bash
#!/usr/bin/env bash

# Read JSON input from stdin
input=$(cat)

# Extract values from JSON
model_full=$(echo "$input" | jq -r '.model.display_name' 2>/dev/null || echo "Claude")
cwd=$(echo "$input" | jq -r '.workspace.current_dir' 2>/dev/null || pwd)
transcript=$(echo "$input" | jq -r '.transcript_path' 2>/dev/null)

# Shorten model name: "Sonnet 4.5 (with 1M token context)" -> "Sonnet 4.5 [1M]"
model=$(echo "$model_full" | sed -E 's/(.*)\(with ([0-9]+[KM]) token context\)/\1[\2]/' | sed 's/ *$//')

# Get username
username=$(whoami)

# Shorten path (replace home with ~)
short_path="${cwd/#$HOME/~}"

# Git branch status
git_info=""
if [ -d "$cwd/.git" ] || git -C "$cwd" rev-parse --git-dir >/dev/null 2>&1; then
    branch=$(git -C "$cwd" --no-optional-locks branch --show-current 2>/dev/null || echo "detached")

    # Check for changes
    status=""
    if ! git -C "$cwd" --no-optional-locks diff --quiet 2>/dev/null || \
       ! git -C "$cwd" --no-optional-locks diff --cached --quiet 2>/dev/null; then
        status="*"
    fi

    # Check for untracked files
    if [ -n "$(git -C "$cwd" --no-optional-locks ls-files --others --exclude-standard 2>/dev/null)" ]; then
        status="${status}+"
    fi

    # Format git info with color
    if [ -n "$status" ]; then
        # Red for dirty
        git_info=$(printf ' \033[01;31m[git:%s%s]\033[00m' "$branch" "$status")
    else
        # Yellow for clean
        git_info=$(printf ' \033[01;33m[git:%s]\033[00m' "$branch")
    fi
fi

# Cost information using ccusage with caching
cost_info=""
cache_file="/tmp/claude_cost_cache_$(date +%Y%m%d_%H%M).txt"

# Clean old cache files (older than 2 minutes)
find /tmp -name "claude_cost_cache_*.txt" -mmin +2 -delete 2>/dev/null

if [ -f "$cache_file" ]; then
    # Use cached costs
    cost_info=$(cat "$cache_file")
else
    # Get costs from ccusage (in background to not block statusline on first run)
    {
        session=$(ccusage session --json --offline -o desc 2>/dev/null | jq -r '.sessions[0].totalCost' 2>/dev/null | xargs printf "%.2f")
        daily=$(ccusage daily --json --offline -o desc 2>/dev/null | jq -r '.daily[0].totalCost' 2>/dev/null | xargs printf "%.2f")

        if [ -n "$session" ] && [ -n "$daily" ] && [ "$session" != "" ] && [ "$daily" != "" ]; then
            printf ' \033[01;35m[$%s/$%s]\033[00m' "$session" "$daily" > "$cache_file"
        fi
    } &

    # Try to use previous cache while new one is being generated
    prev_cache=$(find /tmp -name "claude_cost_cache_*.txt" -mmin -10 2>/dev/null | head -1)
    if [ -f "$prev_cache" ]; then
        cost_info=$(cat "$prev_cache")
    fi
fi

# Print the final status line (multi-line format for portrait screens)
# Line 1: username (model) [costs]
# Line 2: path (bright white for better visibility)
# Line 3: [git:branch]
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m%s\n\033[01;37m%s\033[00m\n%s' \
    "$username" "$model" "$cost_info" "$short_path" "$git_info"
```

### references/ccusage_integration.md

```markdown
# ccusage Integration Reference

This reference explains how the statusline integrates with `ccusage` for cost tracking and troubleshooting.

## What is ccusage?

`ccusage` is a command-line tool that tracks Claude Code usage and costs by reading conversation transcripts. It provides session-based and daily cost reporting.

## How Statusline Uses ccusage

The statusline script calls `ccusage` to display session and daily costs:

```bash
session=$(ccusage session --json --offline -o desc 2>/dev/null | jq -r '.sessions[0].totalCost' 2>/dev/null | xargs printf "%.2f")
daily=$(ccusage daily --json --offline -o desc 2>/dev/null | jq -r '.daily[0].totalCost' 2>/dev/null | xargs printf "%.2f")
```

### Key Features

1. **JSON Output**: Uses `--json` flag for machine-readable output
2. **Offline Mode**: Uses `--offline` to avoid fetching pricing data (faster)
3. **Descending Order**: Uses `-o desc` to get most recent data first
4. **Error Suppression**: Redirects errors to `/dev/null` to prevent statusline clutter

## Caching Strategy

To avoid slowing down the statusline, costs are cached:

- **Cache File**: `/tmp/claude_cost_cache_YYYYMMDD_HHMM.txt`
- **Cache Duration**: 2 minutes (refreshes based on minute timestamp)
- **Background Refresh**: First run fetches costs in background
- **Fallback**: Uses previous cache (up to 10 minutes old) while refreshing

### Cache Behavior

1. **First Display**: Statusline shows without costs
2. **2-5 Seconds Later**: Costs appear after background fetch completes
3. **Next 2 Minutes**: Cached costs shown instantly
4. **After 2 Minutes**: New cache generated in background

## ccusage JSON Structure

### Session Data
```json
{
  "sessions": [
    {
      "sessionId": "conversation-id",
      "totalCost": 0.26206769999999996,
      "inputTokens": 2065,
      "outputTokens": 1313,
      "lastActivity": "2025-10-20"
    }
  ]
}
```

### Daily Data
```json
{
  "daily": [
    {
      "date": "2025-10-20",
      "totalCost": 25.751092800000013,
      "inputTokens": 16796,
      "outputTokens": 142657
    }
  ]
}
```

## Troubleshooting

### Costs Not Showing

**Symptoms**: Statusline appears but no `[$X.XX/$X.XX]` shown

**Possible Causes**:
1. ccusage not installed
2. ccusage not in PATH
3. No transcript data available yet
4. Background fetch still in progress

**Solutions**:
```bash
# Check if ccusage is installed
which ccusage

# Test ccusage manually
ccusage session --json --offline -o desc

# Check cache files
ls -lh /tmp/claude_cost_cache_*.txt

# Wait 5-10 seconds and check again (first fetch runs in background)
```

### Slow Statusline

**Symptoms**: Statusline takes >1 second to appear

**Possible Causes**:
1. Cache not working (being regenerated too often)
2. ccusage taking too long to execute

**Solutions**:
```bash
# Check cache timestamp
ls -lh /tmp/claude_cost_cache_*.txt

# Test ccusage speed
time ccusage session --json --offline -o desc

# If slow, consider disabling cost tracking by commenting out cost section in script
```

### Incorrect Costs

**Symptoms**: Costs don't match expected values

**Possible Causes**:
1. Cache stale (showing old data)
2. ccusage database out of sync
3. Multiple Claude sessions confusing costs

**Solutions**:
```bash
# Clear cache to force refresh
rm /tmp/claude_cost_cache_*.txt

# Verify ccusage data
ccusage session -o desc | head -20
ccusage daily -o desc | head -20

# Check ccusage database location
ls -lh ~/.config/ccusage/
```

## Installing ccusage

If ccusage is not installed:

```bash
# Using npm (Node.js required)
npm install -g @anthropic-ai/ccusage

# Or check the official ccusage repository for latest installation instructions
```

## Disabling Cost Tracking

To disable costs (e.g., if ccusage not available), comment out the cost section in `generate_statusline.sh`:

```bash
# Cost information using ccusage with caching
cost_info=""
# cache_file="/tmp/claude_cost_cache_$(date +%Y%m%d_%H%M).txt"
# ... rest of cost section commented out
```

Then update the final printf to remove `%s` for cost_info:

```bash
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m\n\033[01;37m%s\033[00m\n%s' \
    "$username" "$model" "$short_path" "$git_info"
```
```

### references/color_codes.md

```markdown
# ANSI Color Codes Reference

This reference provides ANSI escape codes for customizing statusline colors.

## Format

ANSI color codes follow this format:
```
\033[<attributes>m<text>\033[00m
```

- `\033[` - Escape sequence start
- `<attributes>` - Color and style codes (see below)
- `m` - Marks end of escape sequence
- `\033[00m` - Reset to default

## Common Color Codes

### Regular Colors
- `\033[00;30m` - Black
- `\033[00;31m` - Red
- `\033[00;32m` - Green
- `\033[00;33m` - Yellow
- `\033[00;34m` - Blue
- `\033[00;35m` - Magenta
- `\033[00;36m` - Cyan
- `\033[00;37m` - White

### Bright/Bold Colors (Used in Default Statusline)
- `\033[01;30m` - Bright Black (Gray)
- `\033[01;31m` - Bright Red
- `\033[01;32m` - Bright Green
- `\033[01;33m` - Bright Yellow
- `\033[01;34m` - Bright Blue
- `\033[01;35m` - Bright Magenta
- `\033[01;36m` - Bright Cyan
- `\033[01;37m` - Bright White

## Default Statusline Colors

The generated statusline uses these colors by default:

| Element | Color Code | Color Name | Visibility |
|---------|-----------|------------|-----------|
| Username | `\033[01;32m` | Bright Green | Excellent |
| Model | `\033[01;36m` | Bright Cyan | Excellent |
| Costs | `\033[01;35m` | Bright Magenta | Excellent |
| Path | `\033[01;37m` | Bright White | Excellent |
| Git (clean) | `\033[01;33m` | Bright Yellow | Excellent |
| Git (dirty) | `\033[01;31m` | Bright Red | Excellent |

## Customizing Colors

To customize colors in the statusline script, edit the `printf` statements:

### Example: Change username to bright blue
```bash
# Original:
printf '\033[01;32m%s\033[00m' "$username"

# Modified:
printf '\033[01;34m%s\033[00m' "$username"
```

### Example: Change path to yellow
```bash
# Original:
printf '\033[01;37m%s\033[00m' "$short_path"

# Modified:
printf '\033[01;33m%s\033[00m' "$short_path"
```

## Testing Colors

Test color codes in terminal:
```bash
echo -e "\033[01;32mGreen\033[00m \033[01;36mCyan\033[00m \033[01;35mMagenta\033[00m"
```

## Tips

1. **Always reset**: End each colored section with `\033[00m` to reset colors
2. **Visibility**: Bright colors (01;3X) are more visible than regular (00;3X)
3. **Contrast**: Choose colors that contrast well with your terminal background
4. **Consistency**: Use consistent colors for similar elements across your environment
```