[FEATURE] Context Budget Monitoring API for Session Checkpoints

Problem Statement

Claude Code sessions lack visibility into remaining context token budget, which prevents:

• Autonomous checkpointing before context exhaustion
• Multi-agent coordination around shared budget
• Graceful session closure with saved state
• Early warning systems before failures

Currently, when context nears capacity (~20%), there's no mechanism for Claude to detect this and trigger preventive actions. Sessions can end abruptly with work-in-progress lost.

Example failure scenario:

• User runs /gen-continuation --save to create session snapshot
• Command spawns background agent to build session memory
• Agent runs out of context mid-execution
• Session crashes, snapshot incomplete, no state persisted

Proposed Solution

Expose context token budget information to commands/agents via one of these approaches:

Option A: Environment Variables (Recommended)

Make the following variables available to all commands:

$CLAUDE_CONTEXT_REMAINING    # Percentage remaining (20, 15, 5, etc)
$CLAUDE_TOKENS_USED          # Total tokens consumed this session
$CLAUDE_TOKENS_MAX           # Maximum budget (typically 200000)
$CLAUDE_SESSION_ID           # Unique session identifier

Option B: Query Command

Provide a command that returns context status:

claude-context-status
# Output: {"remaining_percent": 20, "tokens_used": 160000, "tokens_max": 200000}

Option C: Hook System

Add a new hook type triggered when context reaches threshold:

# PreContextThreshold hook at 25%, 10%, etc

Alternative Solutions

• Client-side estimation: Calculate tokens from conversation length (unreliable)
• User prompts: Ask user when to save (loses autonomy benefit)
• Fixed timers: Checkpoint at regular intervals (inefficient)
• Hook on final output: Only save when about to crash (data loss risk)

Priority

High - Blocks autonomous session persistence and multi-agent workflows

Feature Category

• CLI commands
• Developer tools

Use Case Example

Scenario: Long-running multi-step task requiring session handoff

# Step 1: Monitor context during work
if [ $(echo $CLAUDE_CONTEXT_REMAINING) -lt 25 ]; then
  # Step 2: Gracefully save state
  /gen-continuation --save \
    --auto-triggered \
    --context-remaining 20 \
    --accomplishments "Implemented async handler, added 5 tests" \
    --decisions "Chose mutex lock over RW lock for simplicity" \
    --blockers "15% performance regression needs investigation"

  # Step 3: Notify user
  echo "⚠️  Context at 20% capacity"
  echo "✅ Session memory saved to .claude-continuation.md"
  echo "Safe to close this window - work available next session"
  exit 0
fi

# Step 4: Continue work with full context
npm run tests

Result: Session checkpoint saved, user closes window, new session reads .claude-continuation.md and resumes immediately with full context.

Additional Context

Investigation Prompts for Implementation

For Claude Code developers reviewing this feature:

Prompt 1 - Token Accounting:

Where in the codebase is token usage tracked?
- Token counter implementations
- Budget enforcement logic
- Session token accounting

Prompt 2 - Environment Setup:

How are environment variables exposed to commands?
- Which variables are already available?
- How is the execution environment configured?
- Where would new context metrics fit?

Prompt 3 - Hook System:

Could a new hook be added for context thresholds?
- Current hook types and implementation
- Hook triggering mechanism
- Parameter passing to hooks

Related Context

This feature enables:

• Autonomous Session Memory - /gen-continuation checkpoints automatically
• Multi-Agent Coordination - Agents aware of shared budget
• Graceful Degradation - Warnings instead of crashes
• Work Persistence - Session state survives context exhaustion

Technical Notes

• Works with all Claude Code session types
• Enables conditional logic in bash commands
• Minimal performance impact (query/var access only)
• Complements existing /bug and error handling systems