claude-hud-glm: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Claude HUD is a Claude Code plugin that displays a real-time multi-line statusline. It shows context health, tool activity, agent status, and todo progress.

Build Commands

npm ci               # Install dependencies
npm run build        # Build TypeScript to dist/

# Test with sample stdin data
echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | node dist/index.js

Architecture

Data Flow

Claude Code → stdin JSON → parse → render lines → stdout → Claude Code displays
           ↘ transcript_path → parse JSONL → tools/agents/todos

Key insight: The statusline is invoked every ~300ms by Claude Code. Each invocation:

1. Receives JSON via stdin (model, context, tokens - native accurate data)
2. Parses the transcript JSONL file for tools, agents, and todos
3. Renders multi-line output to stdout
4. Claude Code displays all lines

Data Sources

Native from stdin JSON (accurate, no estimation):

• model.display_name - Current model
• context_window.current_usage - Token counts
• context_window.context_window_size - Max context
• transcript_path - Path to session transcript

From transcript JSONL parsing:

• tool_use blocks → tool name, input, start time
• tool_result blocks → completion, duration
• Running tools = tool_use without matching tool_result
• TodoWrite calls → todo list
• Task calls → agent info

From config files:

• MCP count from ~/.claude/settings.json (mcpServers)
• Hooks count from ~/.claude/settings.json (hooks)
• Rules count from CLAUDE.md files

From OAuth credentials (~/.claude/.credentials.json, when display.showUsage enabled):

• claudeAiOauth.accessToken - OAuth token for API calls
• claudeAiOauth.subscriptionType - User's plan (Pro, Max, Team)

From Anthropic Usage API (api.anthropic.com/api/oauth/usage):

• 5-hour and 7-day usage percentages
• Reset timestamps (cached 60s success, 15s failure)