---

name: claude-hud description: Configure Claude Code statusline with context window monitoring using CC 2.1.6 fields. Use when configuring statusline, monitoring context, displaying HUD. context: inherit version: 1.0.0 author: OrchestKit tags: [statusline, hud, context, monitoring, cc216] user-invocable: true

Claude HUD - Status Line Configuration

Overview

Use this skill when you need to:

• Monitor context window usage in real-time
• Configure statusline display for Claude Code
• Set up visual thresholds for context management
• Track session costs and duration

Configure Claude Code's statusline to display real-time context window usage and session information using CC 2.1.6 fields.

Quick Setup

Add to your .claude/settings.json:

Copy{
  "statusline": {
    "enabled": true,
    "template": "[CTX: {{context_window.used_percentage}}%] {{session.cost}}"
  }
}

Available Fields (CC 2.1.6)

CC 2.1.7 New Fields

Turn Duration Display (CC 2.1.7)

Enable turn duration tracking in your statusline:

Copy{
  "statusline": {
    "enabled": true,
    "showTurnDuration": true,
    "template": "[CTX: {{context_window.used_percentage}}%] [Turn: {{turn.duration}}]"
  }
}

Effective Context Window

CC 2.1.7 uses the effective context window rather than the static maximum:

CopyStatic Max:    200,000 tokens (theoretical limit)
Effective:     160,000 tokens (actual usable after overhead)
Your Usage:     45,000 tokens (28% of effective)

Visual States

Context usage thresholds help you know when to act.

CC 2.1.14 Context Window Fix: Claude Code now uses 98% of the context window (previously capped at ~65%). Thresholds below are calculated against the effective window (160K tokens for 200K max after ~20% system overhead).

Copy[CTX: 45%] ████████░░░░░░░░ - GREEN:  Plenty of room, work freely
[CTX: 72%] ██████████████░░ - YELLOW: Watch usage, consider chunking
[CTX: 89%] █████████████████ - ORANGE: Consider compacting soon
[CTX: 97%] ██████████████████ - RED:    COMPACT NOW or lose context

Note: These percentages are of the effective window (~160K tokens), not the static 200K max. A 50% reading means ~80K tokens used.

Recommended Actions by State

Configuration Options

Basic Template

Copy{
  "statusline": {
    "enabled": true,
    "template": "[{{context_window.used_percentage}}%]"
  }
}

With Cost Tracking

Copy{
  "statusline": {
    "enabled": true,
    "template": "[CTX: {{context_window.used_percentage}}%] Cost: {{session.cost}}"
  }
}

With Progress Bar

Copy{
  "statusline": {
    "enabled": true,
    "template": "[CTX: {{context_window.used_percentage}}%]",
    "elements": {
      "context_bar": {
        "field": "context_window.used_percentage",
        "format": "bar",
        "thresholds": {
          "normal": 60,
          "warning": 80,
          "critical": 95
        }
      }
    }
  }
}

Integration with OrchestKit

Automatic Context Management

OrchestKit's hooks can automatically suggest compression when context gets high:

Copy# In hooks/posttool/context-monitor.sh
if [ "$CONTEXT_USED_PCT" -gt 80 ]; then
  echo "SUGGESTION: Consider using /ork:context-compression"
fi

Progressive Loading Optimization

When context is above 60%, OrchestKit automatically:

1. Uses Tier 1 discovery more aggressively
2. Loads smaller reference files
3. Suggests skill completion before loading new skills

Troubleshooting

Statusline Not Showing

1. Verify CC version: claude --version (need >= 2.1.6)
2. Check settings.json syntax
3. Restart Claude Code session

Incorrect Percentages

Context percentages are calculated from:

• System prompt size
• Conversation history
• Loaded skills and context files
• Pending tool outputs

If numbers seem off, check for large files loaded in context.

VSCode Integration (CC 2.1.14)

When using Claude Code in VSCode, additional features are available:

/usage Command

Display current plan usage directly in VSCode:

Copy/usage

Shows:

• Tokens used in current billing period
• Cost breakdown by model
• Remaining quota (if applicable)

VSCode Status Bar

The statusline integrates with VSCode's status bar. Configure in VSCode settings:

Copy{
  "claudeCode.statusBar.enabled": true,
  "claudeCode.statusBar.position": "right"
}

Related Skills

• context-compression: Reduce context when hitting limits
• context-engineering: Optimize what goes in context
• brainstorming: Use before loading heavy context

Version Requirements

• Claude Code: >= 2.1.14
• Fields Available: CC 2.1.6 + CC 2.1.7 (turn.duration, context_window.effective, mcp.deferred)
• VSCode Features: CC 2.1.14 (/usage command)