claude-hud

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

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

```json
{
  "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