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:

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

Available Fields (CC 2.1.6)

Field	Description	Example
`context_window.used_percentage`	Current context usage as percentage	`45`
`context_window.remaining_percentage`	Available context as percentage	`55`
`session.cost`	Current session cost	`$0.23`
`session.duration`	Session duration	`15m`

CC 2.1.7 New Fields

Field	Description	Example
`turn.duration`	Current turn duration	`2.3s`
`context_window.effective`	Effective window size	`160000`
`context_window.effective_percentage`	Usage vs effective window	`28`
`mcp.deferred`	MCP tools deferred status	`true`

Turn Duration Display (CC 2.1.7)

Enable turn duration tracking in your statusline:

{
  "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:

Static 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).

[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

State	Usage	Action
GREEN	< 60%	Normal operation
YELLOW	60-80%	Break large tasks into chunks
ORANGE	80-95%	Use `/context-compression` or summarize
RED	> 95%	COMPACT IMMEDIATELY

Configuration Options

Basic Template

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

With Cost Tracking

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

With Progress Bar

{
  "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:

# 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:

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

Troubleshooting

Statusline Not Showing

Verify CC version: claude --version (need >= 2.1.6)
Check settings.json syntax
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:

/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:

{
  "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)

claude-hud