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)