| name | pulseline-troubleshoot |
| description | Diagnose and fix cc-pulseline statusline issues. Use when the user mentions their statusline is blank, broken, not updating, showing wrong data, or displaying rendering problems. Also use when users report missing segments, broken icons, or color issues. |
| tools | Bash, Read |
| user-invocable | false |
Pulseline Troubleshooter
You are automatically diagnosing a cc-pulseline statusline issue. Run quick diagnostics, identify the problem, and suggest a fix.
Quick Diagnostics
Run these checks to identify the issue:
1. Binary Health
ls -la ~/.claude/pulseline/cc-pulseline 2>/dev/null
~/.claude/pulseline/cc-pulseline --check 2>&1
echo '{"session_id":"diag","version":"1.0.2"}' | ~/.claude/pulseline/cc-pulseline 2>&1
2. Settings Registration
Read ~/.claude/settings.json and check that statusLine.command points to ~/.claude/pulseline/cc-pulseline.
3. Config Validation
~/.claude/pulseline/cc-pulseline --check 2>&1
~/.claude/pulseline/cc-pulseline --print 2>&1
4. Cache State
ls -la ${TMPDIR:-/tmp}/cc-pulseline-*.json 2>/dev/null
Common Issues and Resolutions
Blank Statusline
- Binary not found: Binary missing or wrong path in settings.json. Fix:
/pulseline:setup
- Binary crashes: Check stderr output from test payload. May need rebuild:
/pulseline:setup cargo
- Settings not registered:
statusLine key missing from settings.json. Fix: /pulseline:setup
- Performance timeout: Binary taking >50ms. Check for slow git operations or large transcript files
Wrong or Stale Data
- Stale cache: Remove cache files:
rm -f ${TMPDIR:-/tmp}/cc-pulseline-*.json
- Config mismatch: Project config overriding user config unexpectedly. Run
/pulseline:config show to see merged result
- Segment disabled: A segment toggle is set to
false. Run /pulseline:config edit to re-enable
Broken Icons or Formatting
- Missing Nerd Font: Icons require a Nerd Font patched terminal font. Set
use_icons = false in config to use ASCII fallback
- Color issues: Check
color_enabled in config. Set to false if terminal doesn't support 256-color, or set theme = "light" for light terminal backgrounds
- Truncated output: Terminal width too narrow. Widen terminal or reduce segments via
/pulseline:config edit
Missing Segments
- Segment toggled off: Check
show_* fields in config via /pulseline:config show
- No data available: Some segments only appear when data exists (e.g., agents only show during agent activity, cost only shows after API calls)
- Width degradation: When terminal is narrow, activity lines are dropped first, then L2 is compressed. Widen terminal or reduce content
Resolution
After diagnosing, recommend the appropriate /pulseline:* command:
/pulseline:setup — reinstall or re-register/pulseline:config edit — adjust display settings/pulseline:config reset — reset to defaults/pulseline:status — full diagnostic report
