Overview
The preview command loads an existing statusline script and tests it with realistic mock data. This lets you see exactly how your statusline will appear in Claude Code without needing to restart the application.
Syntax
cc-statusline preview <script-path>
Arguments
Path to the statusline.sh file you want to preview. This is typically .claude/statusline.sh or ~/.claude/statusline.sh.
What Preview Does
The preview command performs a comprehensive test of your statusline:
- Loads your actual statusline script from disk
- Detects configuration metadata from the script header (theme, colors, features)
- Generates realistic mock Claude Code JSON input data
- Executes the script with the mock data
- Displays the rendered statusline output
- Measures execution performance and reports metrics
- Validates that key features are working correctly
Mock Data
The preview command simulates Claude Code’s JSON input with realistic test data:
{
"workingDirectory": "/home/user/projects/my-app",
"gitBranch": "main",
"modelName": "claude-sonnet-4-20250514",
"claudeCodeVersion": "1.0.85",
"outputStyle": "default",
"contextUsed": 85000,
"contextTotal": 100000
}
Examples
Preview Project Statusline
Test your project-specific statusline:
cc-statusline preview .claude/statusline.sh
🔍 Statusline Preview Mode
⠋ Loading statusline script from .claude/statusline.sh...
✔ Script loaded!
Detected Configuration:
Theme: Modern 3-Line
Colors: Vibrant
Features: directory, git, model, claudecode, context, cost, session, tokens
Generated: 2026-03-04 10:30:15
Mock Claude Code Input:
{
"workingDirectory": "/home/user/projects/my-app",
"gitBranch": "feature/statusline",
"modelName": "claude-sonnet-4-20250514",
"claudeCodeVersion": "1.0.85",
"outputStyle": "default",
"contextUsed": 83000,
"contextTotal": 100000
}
⠋ Testing statusline with mock data...
✔ Test completed in 67ms
✅ Statusline Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 ~/projects/my-app 🌿 feature/statusline 🤖 Sonnet 4 📟 v1.0.85 🎨 default
🧠 Context Remaining: 83% [========--] ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
💰 $49.00 ($16.55/h) 📊 14638846 tok (279900 tpm)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Performance: 🚀 excellent (67ms)
✅ Statusline features appear to be working
✨ Preview complete! Use `cc-statusline init` to generate a new statusline.
Preview Global Statusline
Test your globally installed statusline:
cc-statusline preview ~/.claude/statusline.sh
Preview Custom Location
Test a statusline script saved to a custom path:
cc-statusline preview ~/my-custom-statusline.sh
| Performance | Time Range | Indicator |
|---|
| Excellent 🚀 | < 100ms | Optimal - no issues |
| Good ✅ | 100-500ms | Acceptable - may feel slightly slow |
| Slow ⚠️ | 500-1000ms | Noticeable delay - consider optimizing |
| Timeout 🐌 | > 1000ms | Too slow - disable features |
- Target: < 100ms for best user experience
- Typical: 45-80ms with all features enabled
- Maximum: < 500ms to avoid perceived lag
Configuration Detection
The preview command extracts metadata from your statusline script header:
# Generated by cc-statusline v1.4.0
# Custom Claude Code statusline - Created: 2026-03-04 10:30:15
# Theme: Modern 3-Line | Colors: Vibrant | Features: directory, git, model, context, cost, session, tokens
Feature Validation
After rendering the statusline, preview checks for common feature indicators:
- 📁 - Directory feature working
- 🌿 - Git branch feature working
- 🤖 - Model info feature working
- 🧠 - Context tracking working
- 💰 - Cost tracking working
- ⌛ - Session timer working
- 📊 - Token analytics working
If these indicators appear in the output, the corresponding features are functioning correctly.
Error Handling
Script Not Found
cc-statusline preview ./nonexistent.sh
🔍 Statusline Preview Mode
⠋ Loading statusline script from ./nonexistent.sh...
❌ Failed to load script: ENOENT: no such file or directory, open './nonexistent.sh'
.claude/statusline.sh for project statuslines or ~/.claude/statusline.sh for global ones.
Script Execution Failed
🔍 Statusline Preview Mode
✔ Script loaded!
⠋ Testing statusline with mock data...
✖ Test failed
❌ Error: Command failed with exit code 127
- Missing dependencies (
jq, git, etc.)
- Syntax errors in the script
- Permission issues (ensure script is executable:
chmod +x .claude/statusline.sh)
Partial Output
If the script partially executes, preview shows what was rendered:
✖ Test failed
❌ Error: Command exited with code 1
Partial output:
📁 ~/projects/my-app 🌿 main
- Disable heavy features - Token analytics and ccusage integration are the slowest
- Check jq installation - Fallback parser is significantly slower
- Reduce features - Run
cc-statusline init again with fewer features selected
- Test environment - Preview performance matches real-world performance
Comparison
# Test current statusline
cc-statusline preview .claude/statusline.sh
# Generate optimized version
cc-statusline init --output .claude/statusline-optimized.sh
# Compare performance
cc-statusline preview .claude/statusline-optimized.sh
Troubleshooting
No Configuration Detected
If the preview doesn’t show “Detected Configuration”, your statusline may have been manually edited or created outside cc-statusline. The preview will still work, but won’t display metadata.
Preview Shows Fallback Message
📁 ~/projects/my-app 🌿 main 🤖 Claude 💵 $2.48 ($12.50/h)
(Preview unavailable - will work when Claude Code runs it)
- Script depends on specific environment variables Claude Code provides
- ccusage integration requires real usage data
- Some features only work in interactive Claude Code sessions
Use Cases
Before Restarting Claude Code
# Generate new statusline
cc-statusline init
# Preview to verify output
cc-statusline preview .claude/statusline.sh
# If satisfied, restart Claude Code
Comparing Configurations
# Save current statusline as backup
cp .claude/statusline.sh .claude/statusline-backup.sh
# Generate new configuration
cc-statusline init
# Compare outputs
cc-statusline preview .claude/statusline-backup.sh
cc-statusline preview .claude/statusline.sh
Debugging Issues
# Preview shows exactly what Claude Code will see
cc-statusline preview .claude/statusline.sh
# Check for missing features or errors
# Verify performance is acceptable
init - Generate a new statusline configurationtest - Test statusline with real Claude Code JSON input
Source Reference
Command definition: src/index.ts:22-29
Implementation: src/cli/preview.ts:8-76