Configure the statusline
Run the setup command to configure Claude Code to use Claude HUD as your statusline:The setup command will:
- Detect your platform and runtime (Bun preferred, Node.js fallback)
- Find the installed plugin path
- Test the generated command
- Write the
statusLineconfiguration to~/.claude/settings.json - Offer optional features you can enable right away
Restart Claude Code
The
statusLine configuration requires a restart to take effect. Quit Claude Code completely and run claude again in your terminal.- Line 1 — Your model, plan (or
Bedrock), project path, git branch - Line 2 — Context bar (green → yellow → red) and usage rate limits
Optional features
After setup, you can enable additional display lines at any time:| Feature | What you see | Config key |
|---|---|---|
| Tools activity | ◐ Edit: auth.ts | ✓ Read ×3 | display.showTools |
| Agent tracking | ◐ explore [haiku]: Finding code (2m 15s) | display.showAgents |
| Todo progress | ▸ Fix authentication bug (2/5) | display.showTodos |
| Session duration | ⏱️ 5m | display.showDuration |
| Config counts | 2 CLAUDE.md | 4 rules | display.showConfigCounts |
/claude-hud:configure to enable any of these interactively.
Next steps
Configuration
Customize your layout, toggle features, and adjust colors and thresholds.
How it works
Understand how Claude HUD reads native token data and parses your transcript.
/claude-hud:configure
Interactive guided flow for configuring your HUD display options.
Troubleshooting
Fix common issues with setup, display, and usage limits.