FoundryVTT/.claude/STATUS_LINE_SETUP.md

# Status Line Customization

> **Status**: ✅ Configured
> **Date**: 2025-10-17

## Overview

The status line displays real-time information at the bottom of your Claude Code terminal. It's configured to show:
- 📁 Current directory (last 2 path segments)
- 🌿 Git branch (if in a git repository)
- ● Uncommitted changes indicator
- 🕐 Current time

## Current Configuration

**Location**: `.claude/statusline.sh`
**Format**: `📁 project/subdir 🌿 main ● | 🕐 14:30`

### What's Displayed

| Element | Description | Example |
|---------|-------------|---------|
| 📁 Directory | Last 2 path segments | `Claude Code Setup/subdir` |
| 🌿 Branch | Current git branch | `main` |
| ● Changes | Uncommitted changes indicator | Shows when dirty |
| 🕐 Time | Current time (HH:MM) | `14:30` |

## Customization Options

### Adding More Information

Edit [`.claude/statusline.sh`](.claude/statusline.sh) to add:

#### 1. **Token Count / Context Usage**
```bash
# This requires Claude Code to expose this info
# Currently not available in status line script
```

#### 2. **Model Name**
```bash
# Get from environment if set
MODEL="${CLAUDE_MODEL:-sonnet}"
echo "... | 🤖 $MODEL | ..."
```

#### 3. **Project Name**
```bash
# From package.json or project config
PROJECT=$(cat package.json 2>/dev/null | grep '"name"' | head -1 | cut -d'"' -f4)
if [ -n "$PROJECT" ]; then
  echo "📦 $PROJECT | ..."
fi
```

#### 4. **Git Commit Count**
```bash
COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null)
if [ -n "$COMMIT_COUNT" ]; then
  echo "... | 📝 $COMMIT_COUNT commits | ..."
fi
```

#### 5. **Pending Changes Count**
```bash
CHANGED_FILES=$(git diff --name-only 2>/dev/null | wc -l)
if [ "$CHANGED_FILES" -gt 0 ]; then
  echo "... | ✏️  $CHANGED_FILES files | ..."
fi
```

#### 6. **Last Commit Time**
```bash
LAST_COMMIT=$(git log -1 --format="%ar" 2>/dev/null)
if [ -n "$LAST_COMMIT" ]; then
  echo "... | ⏰ $LAST_COMMIT | ..."
fi
```

### Color and Styling

The status line supports ANSI escape codes:

```bash
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Example: Color git branch based on state
if [ -z "$(git status --porcelain 2>/dev/null)" ]; then
  # Clean
  echo "🌿 ${GREEN}$GIT_BRANCH${NC}"
else
  # Dirty
  echo "🌿 ${RED}$GIT_BRANCH${NC} ●"
fi
```

### Layout Options

#### Left-Heavy Layout
```bash
# More info on left, minimal on right
echo "📁 $DIR 🌿 $BRANCH ● ✏️  $CHANGED_FILES | $TIME"
```

#### Center Information
```bash
# Balance information
echo "$DIR | 🌿 $BRANCH $STATUS | 🕐 $TIME"
```

#### Minimal Layout
```bash
# Just essentials
echo "$DIR | $BRANCH"
```

### Dynamic Padding

Adjust spacing based on terminal width:

```bash
# Get terminal width
TERM_WIDTH=$(tput cols)

# Calculate available space
# Adjust content based on width
if [ "$TERM_WIDTH" -lt 80 ]; then
  # Narrow terminal - minimal info
  echo "$DIR | $TIME"
else
  # Wide terminal - full info
  echo "📁 $DIR 🌿 $BRANCH ● ✏️  $CHANGED 📝 $COMMITS | 🕐 $TIME"
fi
```

## Example Configurations

### Configuration 1: Developer Focus
```bash
#!/usr/bin/env bash
BRANCH=$(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')
CHANGED=$(git diff --name-only 2>/dev/null | wc -l)
STAGED=$(git diff --cached --name-only 2>/dev/null | wc -l)
echo "🌿 $BRANCH | ✏️  $CHANGED modified | ✅ $STAGED staged"
```

### Configuration 2: Project Overview
```bash
#!/usr/bin/env bash
PROJECT=$(basename $(pwd))
BRANCH=$(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')
COMMITS=$(git rev-list --count HEAD 2>/dev/null)
echo "📦 $PROJECT | 🌿 $BRANCH | 📝 $COMMITS commits"
```

### Configuration 3: Time Tracking
```bash
#!/usr/bin/env bash
SESSION_START=${SESSION_START:-$(date +%s)}
CURRENT=$(date +%s)
DURATION=$((CURRENT - SESSION_START))
MINUTES=$((DURATION / 60))
echo "⏱️  Session: ${MINUTES}m | 🕐 $(date +%H:%M)"
```

### Configuration 4: Full Featured
```bash
#!/usr/bin/env bash

# Directory
DIR=$(pwd | awk -F/ '{print $(NF-1)"/"$NF}')

# Git info
BRANCH=$(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')
if [ -n "$BRANCH" ]; then
  AHEAD=$(git rev-list @{u}..HEAD 2>/dev/null | wc -l)
  BEHIND=$(git rev-list HEAD..@{u} 2>/dev/null | wc -l)

  GIT_INFO="🌿 $BRANCH"

  if [ "$AHEAD" -gt 0 ]; then
    GIT_INFO="$GIT_INFO ↑$AHEAD"
  fi

  if [ "$BEHIND" -gt 0 ]; then
    GIT_INFO="$GIT_INFO ↓$BEHIND"
  fi

  if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
    GIT_INFO="$GIT_INFO ●"
  fi
else
  GIT_INFO=""
fi

# Time
TIME="🕐 $(date +%H:%M:%S)"

# Output
echo "📁 $DIR | $GIT_INFO | $TIME"
```

## Troubleshooting

### Status Line Not Showing
1. Check script is executable: `chmod +x .claude/statusline.sh`
2. Verify settings.json syntax is correct
3. Test script manually: `bash .claude/statusline.sh`
4. Check Claude Code logs: `.claude/logs/`

### Slow Performance
If status line updates feel slow:
```bash
# Cache expensive operations
# Example: Cache git status for 5 seconds
CACHE_FILE="/tmp/claude_statusline_cache"
CACHE_AGE=5

if [ -f "$CACHE_FILE" ] && [ $(($(date +%s) - $(stat -c %Y "$CACHE_FILE"))) -lt $CACHE_AGE ]; then
  cat "$CACHE_FILE"
else
  # Generate status line
  OUTPUT="📁 $(pwd) | ..."
  echo "$OUTPUT" | tee "$CACHE_FILE"
fi
```

### Script Errors
Enable debugging:
```bash
#!/usr/bin/env bash
set -x  # Print commands as they execute
# Your status line code
```

View errors in Claude Code logs or run manually:
```bash
bash .claude/statusline.sh 2>&1
```

## Best Practices

### Performance
- Keep scripts fast (< 100ms execution time)
- Cache expensive operations
- Avoid network calls
- Use built-in commands over external tools

### Information Density
- Don't overcrowd the status line
- Prioritize most useful information
- Consider terminal width
- Use abbreviations for long text

### Visual Design
- Use emoji icons sparingly
- Consider colorblind users (don't rely only on color)
- Test in different terminal emulators
- Ensure readability in light and dark themes

### Maintainability
- Comment complex logic
- Use functions for reusability
- Test edge cases (no git repo, etc.)
- Document custom icons/abbreviations

## Advanced: Conditional Status Lines

Show different info based on context:

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

# Detect context
if [ -f "package.json" ]; then
  # Node.js project
  PKG_NAME=$(cat package.json | grep '"name"' | head -1 | cut -d'"' -f4)
  PKG_VERSION=$(cat package.json | grep '"version"' | head -1 | cut -d'"' -f4)
  echo "📦 $PKG_NAME v$PKG_VERSION | 🌿 $(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')"

elif [ -f "Cargo.toml" ]; then
  # Rust project
  PKG_NAME=$(grep '^name' Cargo.toml | head -1 | cut -d'"' -f2)
  echo "🦀 $PKG_NAME | 🌿 $(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')"

elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  # Python project
  echo "🐍 Python | 🌿 $(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')"

else
  # Generic
  echo "📁 $(basename $(pwd)) | 🌿 $(git branch 2>/dev/null | grep '^\*' | sed 's/^\* //')"
fi
```

## Disabling Status Line

Temporarily disable:
```bash
# In current session
/settings statusLine.type none
```

Permanently disable:
```json
// Remove or comment out in .claude/settings.json
// "statusLine": { ... }
```

## Related Features

- **Hooks**: Run commands on events
- **Output Styles**: Change Claude's response format
- **Behaviors**: Modify Claude's behavior patterns

## Resources

- [Official Status Line Docs](https://docs.claude.com/en/docs/claude-code/status-line-configuration)
- [ANSI Color Codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
- [Bash Scripting Guide](https://www.gnu.org/software/bash/manual/)

---

**Configuration Version**: 1.0.0
**Last Updated**: 2025-10-17
**Maintainer**: [Your Name]