Episode 10: Best Practices & FAQ

Key Takeaway: A battle-tested HUD config template + a quick-reference troubleshooting manual for common issues.

---

10.1 Recommended Config (Developer)

{
  "language": "en",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "promptCache", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true,
    "pushWarningThreshold": 5
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showSpeed": true,
    "showPromptCache": true,
    "showTokenBreakdown": true,
    "showSessionTokens": true,
    "contextCriticalThreshold": 30,
    "contextValue": "both",
    "promptCacheTtlSeconds": 300
  }
}

---

10.2 Context Management Golden Rules

Rule	Action
Watch the context bar	Start trimming at yellow, /clear immediately at red
Avoid debugging snowballs	/clear after 3-4 rounds with no progress
Periodic cache clearing	/clear once during long sessions
Slim system injection	Compress CLAUDE.md, control claude-mem load count
Use subagents	Big tasks go to subagents — main session context unaffected

---

10.3 Frequently Asked Questions

Q: HUD not showing

• Check Claude Code version ≥ v1.0.80
• Restart Claude Code
• Run /claude-hud:setup to reconfigure
• Check statusLine config in ~/.claude/settings.json

Q: Git status missing

• Confirm you're in a git repository
• Check gitStatus.enabled is not false

Q: Tool/Agent/Todo lines not showing

• Hidden by default — enable showTools / showAgents / showTodos in config
• Only shows when there's activity

Q: Config not taking effect

• Check for JSON syntax errors (invalid JSON silently falls back to defaults)
• Delete config.json and re-run /claude-hud:configure

Q: Was working, then disappeared

• Plugin updates may require re-running /claude-hud:setup

---

10.4 Cache Optimization in Practice

Scenario 1: Cache TTL about to expire

Cache TTL: 2m 18s    ← 2 minutes until cache expires

Action: Send any message before expiry (even just "continue"). System Prompt + CLAUDE.md + history all cache-hit, saving ~90% input token cost.

Scenario 2: Just ran /clear

Cache TTL: -          ← Cache cleared
Context ██░░░░░░░░ 12%   ← Context is low

Action: After /clear, cache is fully invalidated. First turn rebuilds cache. New session recovers quickly.

---

10.5 Complete Config Reference

Feature	Config Key	Default
Language	language	en
Layout	lineLayout	expanded
Path depth	pathLevels	1
Context bar	display.showContextBar	true
Context format	display.contextValue	percent
Token breakdown	display.showTokenBreakdown	true
Token threshold	display.contextCriticalThreshold	85
Usage	display.showUsage	true
Cost	display.showCost	false
Speed	display.showSpeed	false
Tools	display.showTools	false
Agent	display.showAgents	false
Todo	display.showTodos	false
Cache countdown	display.showPromptCache	false
Git status	gitStatus.enabled	true

---

Next Episode: Episode 11 dives into HUD data sources — complete analysis of the stdin JSON, Transcript JSONL, and Context Cache data pipelines.