kyuna0312/Token Status Line

Token Status Line

Add live context window usage and CLAUDE.md token cost to the Claude Code status bar — visible at all times without asking.

What It Shows

ctx [████████░░] 82%  │  md:~650t

• ctx bar — 10-char visual bar of context window usage (color-coded: green → yellow → orange → red)
• md:~Nt — estimated tokens loaded from CLAUDE.md files at session start

Rate limit usage appears only when near limits (≥70%) and on Claude.ai accounts.

Quick Setup

Step 1: Copy plugin script to a stable path (recommended — plugin path may change):

# Copy to permanent location
cp "${CLAUDE_PLUGIN_ROOT}/skills/token-statusline/scripts/token-status.sh" ~/.claude/token-status.sh
chmod +x ~/.claude/token-status.sh

Step 2: Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/token-status.sh",
    "refreshInterval": 30
  }
}

Step 3: Restart Claude Code. Status line appears at bottom of terminal.

If an Existing Status Line Is Already Configured

If settings.json already has a statusLine.command, choose:

• Replace: Swap the command path to token-status.sh
• Extend: Add the bar rendering block to the existing script (see references/statusline-setup.md Option B/C)

Color Thresholds

Context window:

• Green → under 50%
• Yellow → 50–74%
• Orange → 75–89%
• Red → 90%+ (compact now)

CLAUDE.md token cost:

• Green → under 390 tokens (optimal)
• Yellow → 390–779 (acceptable)
• Orange → 780–1299 (bloated)
• Red → 1300+ (optimize immediately)

refreshInterval

"refreshInterval": 30

Status line reruns every 30 seconds. Set lower (10) for faster updates; higher (60) for less CPU. Without refreshInterval, updates only on session events.

Requires Claude Code v2.1.97 or later.

Manual Test

Test script output before wiring it up:

echo '{"context_window":{"used_percentage":72},"workspace":{"current_dir":"'"$PWD"'"}}' \
  | bash ~/.claude/token-status.sh

Should print a colored bar with ctx [███████░░░] 72% and CLAUDE.md token count.

LTX Schema

Emit structured output as LTX rows when reporting current status line state.

@v1:context_pct|bar|md_tokens|color

| Field | Description | |-------|-------------| | context_pct | Context window usage percentage (0–100) | | bar | 10-char visual bar string (e.g. ████████░░) | | md_tokens | Estimated tokens loaded from CLAUDE.md files | | color | green, yellow, orange, red based on context % |

Example:

@v1:context_pct|bar|md_tokens|color
82|████████░░|650|orange

Additional Resources

• references/statusline-setup.md — Full JSON input schema, all setup options, troubleshooting
• scripts/token-status.sh — Standalone status line script (copy to ~/.claude/ for permanent use)