[FEATURE] Expose context usage to AI model for proactive memory management

[FEATURE] Expose context usage to AI model for proactive memory management

Problem

The AI model has no visibility into its own context usage. While the Claude Code UI displays "Context left until auto-compact: X%" in the status bar, this information is not accessible to the AI.

This creates a significant problem:

1. AI cannot proactively save state before auto-compact triggers
2. AI cannot warn users when context is running low
3. Users lose important context/memory when auto-compact happens unexpectedly
4. No way to implement intelligent memory management workflows

Current Behavior

┌─────────────────────────────────────┐
│ Claude Code UI                      │
│ Status: "Context left: 7%"          │  ← Only visible to human
│                                     │
│ AI Model:                           │
│ - Cannot see context %              │
│ - Cannot run /context               │
│ - Blindsided by auto-compact        │
└─────────────────────────────────────┘

Screenshot

The status bar shows context info, but AI is unaware:


Proposed Solutions

Option 1: Context Tool (Preferred)

Expose a tool the AI can call:

// AI could invoke this tool
get_context_usage() → {
  used_tokens: 185000,
  max_tokens: 200000,
  percent_used: 92.5,
  percent_remaining: 7.5,
  auto_compact_threshold: 95
}

Option 2: Environment Variable

Expose context info as environment variables readable via bash:

echo $CLAUDE_CONTEXT_PERCENT    # 92
echo $CLAUDE_CONTEXT_TOKENS     # 185000
echo $CLAUDE_CONTEXT_MAX        # 200000

Option 3: System Prompt Injection

Automatically append context usage to system prompt each turn:

[System: Context usage: 92% (185k/200k tokens). Auto-compact at 95%.]

Option 4: Pre-Compact Hook

Allow users to define a hook that runs before auto-compact:

# .claude/settings.yaml
hooks:
  pre_compact:
    - command: "save_memory_state"
    - notify_ai: true

Use Cases

1. Automatic Memory Saving: AI detects 80% usage → saves key context to file → user can restore in new session

1. User Warnings: AI can say "We're at 85% context, should I save our progress?"

1. Smart Context Management: AI can proactively summarize/compress less important info

1. Session Continuity: AI writes session-state.yaml before compact, loads it after

Example Workflow (If Implemented)

User: Continue working on the authentication module

AI: [calls get_context_usage() → 78%]
    [continues working normally]

... later ...

AI: [calls get_context_usage() → 88%]
    "⚠️ We're at 88% context. Let me save our current state..."
    [writes session-state.md with key decisions, progress, next steps]
    "State saved. We can continue, or start fresh with /compact and I'll reload context."

Environment

• Claude Code version: latest
• OS: Linux / Windows / macOS
• This is a fundamental architectural limitation, not version-specific

Additional Context

Currently, the only workarounds are:

• User manually watches status bar and asks AI to save
• User manually runs /context and tells AI the result
• Adding CLAUDE.md rules asking AI to periodically request context check (unreliable)

None of these are reliable for automated memory management.

---

This feature would significantly improve session continuity and user experience, especially for long-running complex tasks.