claude-code - 💡(How to fix) Fix Feature request: expose context window utilization to hooks (CLAUDE_CONTEXT_PERCENT)

The Ask

Expose context window utilization as an environment variable to hook scripts. One env var: CLAUDE_CONTEXT_PERCENT (integer 0-100), set on every hook invocation.

Why

We built a Write-Ahead Log (WAL) system for Claude Code that prevents context loss across compaction. It works — 100% recovery on first test. But it can't prevent gradual drift during long sessions because hooks have no way to know how full the context is.

The WAL refresh system re-injects operating principles and checkpoint data at escalating intervals. Today we use tool-count as a rough proxy for context consumption. It's imprecise — 30 small file edits consume far less context than 30 large file reads. We just violated our own branch discipline principle because the refresh hadn't fired at the right moment.

With CLAUDE_CONTEXT_PERCENT, hooks could fire at exactly the right moments (25%, 50%, 75%) instead of guessing from tool counts.

What Exists Today

• PreCompact / PostCompact hooks fire when compaction happens — too late
• No env var, no API, no status line metric for context percentage
• /context command shows it interactively but is not automatable
• Hook input JSON has no context metrics

What Would Work

Any of these:

1. Env var — CLAUDE_CONTEXT_PERCENT=73 available to all hook scripts (simplest)
2. New hook event — ContextThreshold that fires at configurable percentages
3. Field in hook input JSON — {"context_percent": 73} alongside cwd and tool_name

Option 1 is trivial to implement and enables everything else in userspace.

Concrete Use Case

The WAL system (github.com/jodybrownell/claude-wal) uses hooks to maintain context continuity. It currently:

• Logs events via PostToolUse
• Captures checkpoints via PreCompact
• Replays state via PostCompact
• Refreshes principles every N tool calls via Stop hook

With context percentage, the refresh becomes precise instead of approximated. The branch check, drift detection, and principle re-injection all fire at the right moments.

Impact

This unblocks any hook-based system that needs context awareness — not just the WAL. Cost monitoring, auto-summarization triggers, session health dashboards, proactive compaction — all become possible with one env var.