Context Management

Context Management Skill

Purpose

This skill enables proactive management of Claude Code's context window through intelligent token monitoring, context extraction, and selective rehydration. Instead of reactive recovery after compaction, this skill helps users preserve essential context before hitting limits and restore it efficiently when needed.

Version 3.0 Enhancements:

• Predictive Budget Monitoring: Estimate when capacity thresholds will be reached
• Context Health Indicators: Visual indicators for statusline integration
• Priority-Based Retention: Keep requirements and decisions, archive verbose logs
• Burn Rate Tracking: Monitor token consumption velocity for early warnings

When to Use This Skill

• Token monitoring: Check current usage and get recommendations
• Approaching limits: Create snapshots at 70-85% usage
• After compaction: Restore essential context without full conversation
• Long sessions: Preserve key decisions and state proactively
• Complex tasks: Keep requirements and progress accessible
• Context switching: Save state when pausing work
• Team handoffs: Package context for others to continue
• Predictive planning: Get early warnings before capacity is reached
• Session health: Monitor context health for sustained productivity

Quick Start

Check Token Status

User: Check my current token usage

I'll use the context_manager tool to check status:

from context_manager import check_context_status

status = check_context_status(current_tokens=<current_count>)
# Returns: ContextStatus with usage percentage and recommendations

Create a Snapshot

User: Create a context snapshot named "auth-implementation"

I'll use the context_manager tool to create a snapshot:

from context_manager import create_context_snapshot

snapshot = create_context_snapshot(
    conversation_data=<conversation_history>,
    name="auth-implementation"
)
# Returns: ContextSnapshot with snapshot_id, file_path, and token_count

Restore Context

User: Restore context from snapshot <snapshot_id> at essential level

I'll use the context_manager tool to rehydrate:

from context_manager import rehydrate_from_snapshot

context = rehydrate_from_snapshot(
    snapshot_id="20251116_143522",
    level="essential"  # or "standard" or "comprehensive"
)
# Returns: Formatted context text ready to process

List Snapshots

User: List my context snapshots

I'll use the context_manager tool to list snapshots:

from context_manager import list_context_snapshots

snapshots = list_context_snapshots()
# Returns: List of snapshot metadata dicts

Detail Levels

When rehydrating context, choose the appropriate detail level:

• Essential (smallest): Requirements + current state only (~250 tokens)
• Standard (balanced): + key decisions + open items (~800 tokens)
• Comprehensive (complete): + full decisions + tools used + metadata (~1,250 tokens)

Start with essential and upgrade if more context is needed.

Actions

Action: status

Check current token usage and get recommendations.

Usage:

from context_manager import check_context_status

status = check_context_status(current_tokens=750000)
print(f"Usage: {status.percentage}%")
print(f"Status: {status.threshold_status}")
print(f"Recommendation: {status.recommendation}")

Returns:

• ContextStatus object with usage details
• threshold_status: 'ok', 'consider', 'recommended', or 'urgent'
• recommendation: Human-readable action suggestion

Action: snapshot

Create intelligent context snapshot.

Usage:

from context_manager import create_context_snapshot

snapshot = create_context_snapshot(
    conversation_data=messages,
    name="feature-name"  # Optional
)
print(f"Snapshot ID: {snapshot.snapshot_id}")
print(f"Token count: {snapshot.token_count}")
print(f"Saved to: {snapshot.file_path}")

Returns:

• ContextSnapshot object with metadata
• Snapshot saved to ~/.amplihack/.claude/runtime/context-snapshots/

Action: rehydrate

Restore context from snapshot at specified detail level.

Usage:

from context_manager import rehydrate_from_snapshot

context = rehydrate_from_snapshot(
    snapshot_id="20251116_143522",
    level="standard"  # essential, standard, or comprehensive
)
print(context)  # Display restored context

Returns:

• Formatted markdown text with restored context
• Ready to process and continue work

Action: list

List all available context snapshots.

Usage:

from context_manager import list_context_snapshots

snapshots = list_context_snapshots()
for snapshot in snapshots:
    print(f"{snapshot['id']}: {snapshot['name']} ({snapshot['size']})")

Returns:

• List of snapshot metadata dicts
• Includes: id, name, timestamp, size, token_count

Proactive Features (v3.0)

Predictive Budget Monitoring

Instead of just checking current usage, predict when thresholds will be reached:

# The system tracks token burn rate over time
# When checking status, you get predictive insights

status = check_context_status(current_tokens=500000)

# Status includes predictions (when automation is running):
# - Estimated tool uses until 70% threshold
# - Time estimate based on current burn rate
# - Early warning before you hit capacity

# Example output interpretation:
# "At current rate, you'll hit 70% in ~15 tool uses"
# "Consider creating a checkpoint before your next major operation"

How Prediction Works:

The automation tracks:

1. Token count at each check interval 2. Number of tool uses between checks 3. Average tokens consumed per tool use 4. Time elapsed between checks

From this data, it estimates:

• Tools remaining until threshold
• Approximate time until threshold
• Whether current task will complete before limit

Context Health Indicators

Visual indicators for session health, suitable for statusline integration:

Statusline Integration Example:

# In your statusline script, check context health:
# The automation state file contains health status

# Example statusline addition:
if [ -f ".claude/runtime/context-automation-state.json" ]; then
    LAST_PCT=$(jq -r '.last_percentage // 0' .claude/runtime/context-automation-state.json)
    if [ "$LAST_PCT" -lt 30 ]; then
        echo "[CTX:OK]"
    elif [ "$LAST_PCT" -lt 50 ]; then
        echo "[CTX:WATCH]"
    elif [ "$LAST_PCT" -lt 70 ]; then
        echo "[CTX:WARN]"
    else
        echo "[CTX:CRITICAL]"
    fi
fi

Priority-Based Context Retention

When creating snapshots, the system prioritizes content by importance:

High Priority (Always Retained):

• Original user requirements (first user message)
• Key architectural decisions
• Current implementation state
• Open items and blockers

Medium Priority (Retained in Standard+):

• Tool usage history
• Decision rationales
• Questions and clarifications

Low Priority (Only in Comprehensive):

• Verbose output logs
• Intermediate steps
• Debugging information

Usage Pattern:

# Create snapshot with priority awareness
snapshot = create_context_snapshot(
    conversation_data=messages,
    name='feature-checkpoint'
)

# Essential level (~200 tokens): Only high priority content
# Standard level (~800 tokens): High + medium priority
# Comprehensive level (~1250 tokens): Everything

# Start minimal, upgrade as needed:
context = rehydrate_from_snapshot(snapshot_id, level='essential')

Burn Rate Tracking

Monitor how fast you're consuming context:

# The automation tracks consumption velocity
# Adaptive checking frequency based on burn rate:

# Low burn rate (< 1K tokens/tool): Check every 50 tools
# Medium burn rate (1-5K tokens/tool): Check every 10 tools
# High burn rate (> 5K tokens/tool): Check every 3 tools
# Critical zone (70%+): Check every tool

# This means:
# - Normal development: Minimal overhead (checks rarely)
# - Large file operations: Increased monitoring
# - Approaching limits: Continuous monitoring

Burn Rate Thresholds:

Auto-Summarization Triggers

The system automatically creates snapshots before limits are hit:

# Automatic snapshot triggers (already implemented):
# - 30% usage: First checkpoint created
# - 40% usage: Second checkpoint created
# - 50% usage: Third checkpoint created (for 1M models)

# For smaller context windows (< 800K):
# - 55% usage: First checkpoint
# - 70% usage: Second checkpoint
# - 85% usage: Urgent checkpoint

# After compaction detected (30% token drop):
# - Automatically rehydrates from most recent snapshot
# - Uses smart level selection based on previous usage

Proactive Usage Workflow

Step 1: Monitor Token Usage

Periodically check status during long sessions:

status = check_context_status(current_tokens=current)

if status.threshold_status == 'consider':
    # Usage at 70%+ - consider creating snapshot
    print("Consider creating a snapshot soon")
elif status.threshold_status == 'recommended':
    # Usage at 85%+ - snapshot recommended
    create_context_snapshot(messages, name='current-work')
elif status.threshold_status == 'urgent':
    # Usage at 95%+ - create snapshot immediately
    create_context_snapshot(messages, name='urgent-backup')

Step 2: Create Snapshot at Threshold

When 70-85% threshold reached, create a named snapshot:

snapshot = create_context_snapshot(
    conversation_data=messages,
    name='descriptive-name'
)
# Save snapshot ID for later rehydration

Step 3: Continue Working

After snapshot creation:

• Continue conversation naturally
• Let Claude Code compact if needed
• Use /transcripts for full history if desired
• PreCompact hook saves everything automatically

Step 4: Rehydrate After Compaction

After compaction, restore essential context:

# Start minimal
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='essential'
)

# If more context needed, upgrade to standard
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='standard'
)

# For complete context, use comprehensive
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='comprehensive'
)

Integration with Existing Systems

vs. PreCompact Hook

PreCompact Hook (automatic safety net):

• Triggered by Claude Code before compaction
• Saves complete conversation transcript
• Automatic, no user action needed
• Full conversation export to markdown

Context Skill (proactive optimization):

• Triggered by user when monitoring indicates
• Saves intelligent context extraction
• User-initiated, deliberate choice
• Essential context only, not full dump

Relationship: Complementary, not competing. Hook = safety net, Skill = optimization.

vs. /transcripts Command

/transcripts (reactive restoration):

• Restores full conversation after compaction
• Complete history, all messages
• Used when you need everything back
• Reactive recovery tool

Context Skill (proactive preservation):

• Preserves essential context before compaction
• Selective rehydration, not full history
• Used when you want efficient context
• Proactive optimization tool

Relationship: Transcripts for full recovery, skill for efficient management.

Storage Locations

• Snapshots: ~/.amplihack/.claude/runtime/context-snapshots/ (JSON)
• Transcripts: ~/.amplihack/.claude/runtime/logs/<session_id>/CONVERSATION_TRANSCRIPT.md
• No conflicts: Different directories, different purposes

Automatic Management

Context management runs automatically via the post_tool_use hook:

• Monitors token usage every Nth tool use (adaptive frequency)
• Creates snapshots at thresholds (30%, 40%, 50% for 1M models)
• Detects compaction (token drop > 30%)
• Auto-rehydrates after compaction at appropriate level

This happens transparently without user intervention.

Implementation

All context management functionality is provided by:

• Tool: ~/.amplihack/.claude/tools/amplihack/context_manager.py
• Hook Integration: ~/.amplihack/.claude/tools/amplihack/context_automation_hook.py
• Hook System: ~/.amplihack/.claude/tools/amplihack/hooks/tool_registry.py

See tool documentation for complete API reference and implementation details.

Common Patterns

Pattern 1: Preventive Snapshotting

Check before long operation and create snapshot if needed:

status = check_context_status(current_tokens=current)
if status.threshold_status in ['recommended', 'urgent']:
    create_context_snapshot(messages, name='before-refactoring')

Pattern 2: Context Switching

Save state when pausing work on one feature to start another:

# Pausing work on Feature A
create_context_snapshot(messages, name='feature-a-paused')

# [... work on Feature B ...]

# Resume Feature A later
context = rehydrate_from_snapshot('feature-a-snapshot-id', level='standard')

Pattern 3: Team Handoff

Create comprehensive snapshot for teammate:

snapshot = create_context_snapshot(
    messages,
    name='handoff-to-alice-api-work'
)
# Share snapshot ID with teammate
# Alice can rehydrate and continue work

Philosophy Alignment

Ruthless Simplicity

• Four single-purpose components in one tool
• On-demand invocation, no background processes
• Standard library only, no external dependencies
• Clear public API with convenience functions

Single Responsibility

• ContextManager coordinates all operations
• Token monitoring, extraction, rehydration in one place
• No duplicate code or scattered logic

Zero-BS Implementation

• No stubs or placeholders
• All functions work completely
• Real token estimation, not fake
• Actual file operations, not simulated

Trust in Emergence

• User decides when to snapshot, not automatic (unless via hook)
• User chooses detail level, not system
• Proactive choice empowers the user

Tips for Effective Context Management

1. Monitor regularly: Check status at natural breakpoints 2. Snapshot strategically: At 70-85% or before long operations 3. Start minimal: Use essential level first, upgrade if needed 4. Name descriptively: Use clear snapshot names for later reference 5. List periodically: Review and clean old snapshots 6. Combine tools: Use with /transcripts for full recovery option 7. Trust emergence: Don't over-snapshot, let context flow naturally

Resources

• Tool: ~/.amplihack/.claude/tools/amplihack/context_manager.py
• Hook: ~/.amplihack/.claude/tools/amplihack/context_automation_hook.py
• Philosophy: ~/.amplihack/.claude/context/PHILOSOPHY.md
• Patterns: ~/.amplihack/.claude/context/PATTERNS.md

Remember

This skill provides proactive context management through a clean, reusable tool. The tool can be called from skills, commands, and hooks. It complements existing tools (PreCompact hook, /transcripts) rather than replacing them. Use it to maintain clean, efficient context throughout long sessions.

Key Takeaway: Business logic lives in context_manager.py, this skill just tells you how to use it.

Basic Usage Examples

Simple examples showing how to use the context-management skill for common tasks.

Example 1: Check Token Usage

from context_management import check_status

# Check current token usage
status = check_status(current_tokens=500_000)

print(f"Status: {status['status']}")
print(f"Percentage: {status['usage']['percentage']}%")
print(f"Recommendation: {status['usage']['recommendation']}")

Output:

Status: ok
Percentage: 50.0%
Recommendation: Context is healthy. No action needed.

Example 2: Create a Snapshot

from context_management import create_snapshot

# Sample conversation data
messages = [
    {'role': 'user', 'content': 'Build a JWT authentication system'},
    {'role': 'assistant', 'content': 'I decided to use RS256 encryption...'},
    {'role': 'tool_use', 'tool_name': 'Write', 'parameters': {}}
]

# Create snapshot
result = create_snapshot(
    conversation_data=messages,
    name='auth-implementation'
)

print(f"Snapshot ID: {result['snapshot']['snapshot_id']}")
print(f"Name: {result['snapshot']['name']}")
print(f"Token count: {result['snapshot']['token_count']}")
print(f"File: {result['snapshot']['file_path']}")

Output:

Snapshot ID: 20251116_143522
Name: auth-implementation
Token count: 1250
File: .claude/runtime/context-snapshots/20251116_143522.json

Example 3: List All Snapshots

from context_management import list_snapshots

# Get all snapshots
result = list_snapshots()

print(f"Total snapshots: {result['count']}")
print(f"Total size: {result['total_size']}")

for snapshot in result['snapshots']:
    print(f"\nID: {snapshot['id']}")
    print(f"Name: {snapshot['name']}")
    print(f"Created: {snapshot['timestamp']}")
    print(f"Size: {snapshot['size']}")

Output:

Total snapshots: 3
Total size: 55KB

ID: 20251116_143522
Name: auth-implementation
Created: 2025-11-16 14:35:22
Size: 15KB

ID: 20251116_092315
Name: database-migration
Created: 2025-11-16 09:23:15
Size: 22KB

ID: 20251115_163045
Name: frontend-redesign
Created: 2025-11-15 16:30:45
Size: 18KB

Example 4: Rehydrate Context

from context_management import rehydrate_context

# Rehydrate at essential level
result = rehydrate_context(
    snapshot_id='20251116_143522',
    level='essential'
)

if result['status'] == 'success':
    print(result['context'])
else:
    print(f"Error: {result['error']}")

Output:

# Restored Context: auth-implementation

*Snapshot created: 2025-11-16 14:35:22*

## Original Requirements

Build a JWT authentication system for API endpoints...

## Current State

JWT handler created, middleware integration in progress
Tests: 12/15 passing

Example 5: Progressive Detail Levels

from context_management import rehydrate_context

snapshot_id = '20251116_143522'

# Start with essential
print("=== ESSENTIAL LEVEL ===")
result = rehydrate_context(snapshot_id, level='essential')
print(f"Tokens: ~200")
print(result['context'][:200], "...\n")

# Upgrade to standard
print("=== STANDARD LEVEL ===")
result = rehydrate_context(snapshot_id, level='standard')
print(f"Tokens: ~800")
print(result['context'][:200], "...\n")

# Get comprehensive
print("=== COMPREHENSIVE LEVEL ===")
result = rehydrate_context(snapshot_id, level='comprehensive')
print(f"Tokens: ~1250")
print(result['context'][:200], "...")

Example 6: Error Handling

from context_management import (
    create_snapshot,
    rehydrate_context,
    list_snapshots
)

# Handle missing conversation data
result = create_snapshot(conversation_data=None, name='test')
if result['status'] == 'error':
    print(f"Error: {result['error']}")
    # Output: Error: conversation_data is required for snapshot action

# Handle non-existent snapshot
result = rehydrate_context('nonexistent_id')
if result['status'] == 'error':
    print(f"Error: {result['error']}")
    # Output: Error: Snapshot not found: nonexistent_id

    # List valid snapshots
    snapshots = list_snapshots()
    print(f"Valid snapshot IDs:")
    for snap in snapshots['snapshots']:
        print(f"  - {snap['id']}: {snap['name']}")

Example 7: Using Main Skill Function

from context_management import context_management_skill

# All actions through single function

# Status
result = context_management_skill('status', current_tokens=750_000)

# Snapshot
result = context_management_skill(
    'snapshot',
    conversation_data=messages,
    name='my-feature'
)

# Rehydrate
result = context_management_skill(
    'rehydrate',
    snapshot_id='20251116_143522',
    level='standard'
)

# List
result = context_management_skill('list')

Example 8: Custom Configuration

from pathlib import Path
from context_management import context_management_skill

# Custom snapshot directory
custom_dir = Path('/tmp/my-snapshots')

# Create snapshot in custom location
result = context_management_skill(
    'snapshot',
    conversation_data=messages,
    snapshot_dir=custom_dir,
    name='custom-location'
)

# List from custom location
result = context_management_skill('list', snapshot_dir=custom_dir)

# Custom max tokens
result = context_management_skill(
    'status',
    current_tokens=400_000,
    max_tokens=500_000  # 500k context window instead of 1M
)

Example 9: Complete Workflow

from context_management import (
    check_status,
    create_snapshot,
    rehydrate_context,
    list_snapshots
)

# Step 1: Monitor token usage
current_tokens = 850_000
status = check_status(current_tokens)

print(f"Current usage: {status['usage']['percentage']}%")
print(f"Status: {status['status']}")
print(f"Recommendation: {status['usage']['recommendation']}")

# Step 2: Create snapshot if recommended
if status['status'] in ['recommended', 'urgent']:
    print("\nCreating snapshot...")
    snapshot = create_snapshot(
        conversation_data=messages,
        name='high-usage-snapshot'
    )
    snapshot_id = snapshot['snapshot']['snapshot_id']
    print(f"Created: {snapshot_id}")

# Step 3: Continue working...
# [... Claude may compact context ...]

# Step 4: After compaction, rehydrate
print(f"\nRestoring context from {snapshot_id}...")
context = rehydrate_context(snapshot_id, level='essential')

if context['status'] == 'success':
    print("Context restored successfully!")
    print(f"\nRestored content preview:")
    print(context['context'][:300], "...")

Tips

1. Start Simple: Use essential level first, upgrade if needed 2. Name Descriptively: Use clear names like 'auth-feature' not 'snapshot-1' 3. Monitor Regularly: Check status at natural breakpoints 4. Handle Errors: Always check result['status'] before using data 5. Clean Up: Periodically review and remove old snapshots

Next Steps

• See proactive_workflow.md for proactive context management patterns
• See rehydration_levels.md for when to use each detail level
• See SKILL.md for complete documentation

Proactive Context Management

Real-world examples of proactive context management patterns using version 3.0 features.

Scenario 1: Predictive Budget Monitoring

Context

You're working on a complex feature implementation and want to know when you'll need to create a checkpoint.

Workflow

from context_management import check_status

# At the start of a complex operation
current_tokens = 350_000  # 35% of 1M context
status = check_status(current_tokens)

print(f"Current usage: {status.percentage}%")
print(f"Status: {status.threshold_status}")
print(f"Recommendation: {status.recommendation}")

# The automation tracks burn rate in the background
# Check the state file for predictions:
import json
from pathlib import Path

state_file = Path(".claude/runtime/context-automation-state.json")
if state_file.exists():
    state = json.loads(state_file.read_text())

    # Calculate burn rate from history
    last_tokens = state.get("last_token_count", 0)
    tool_count = state.get("tool_use_count", 0)

    if last_tokens > 0 and tool_count > 0:
        avg_tokens_per_tool = (current_tokens - last_tokens) / max(1, tool_count)
        tokens_until_70pct = (700_000 - current_tokens)
        tools_until_70pct = int(tokens_until_70pct / max(1, avg_tokens_per_tool))

        print(f"\n--- Prediction ---")
        print(f"Average tokens per tool: {avg_tokens_per_tool:.0f}")
        print(f"Estimated tools until 70%: {tools_until_70pct}")
        print(f"Action: {'Create snapshot soon' if tools_until_70pct < 20 else 'Continue normally'}")

Expected Output

Current usage: 35.0%
Status: consider
Recommendation: Consider creating a snapshot soon. Context usage is rising.

--- Prediction ---
Average tokens per tool: 5000
Estimated tools until 70%: 70
Action: Continue normally

Scenario 2: Context Health Indicators for Statusline

Context

You want to add a context health indicator to your terminal statusline.

Statusline Script Addition

#!/bin/bash
# Add to your existing statusline.sh

# Function to get context health indicator
get_context_health() {
    local state_file=".claude/runtime/context-automation-state.json"

    if [ ! -f "$state_file" ]; then
        echo "[CTX:?]"  # Unknown - no state file
        return
    fi

    # Get last percentage from state
    local pct=$(jq -r '.last_percentage // 0' "$state_file" 2>/dev/null)

    # Determine health indicator
    if [ "$pct" -lt 30 ]; then
        echo -e "\033[32m[CTX:OK]\033[0m"      # Green
    elif [ "$pct" -lt 50 ]; then
        echo -e "\033[33m[CTX:WATCH]\033[0m"   # Yellow
    elif [ "$pct" -lt 70 ]; then
        echo -e "\033[38;5;208m[CTX:WARN]\033[0m"  # Orange
    else
        echo -e "\033[31m[CTX:CRITICAL]\033[0m"  # Red
    fi
}

# Usage in statusline:
# echo "$(get_context_health) | other | status | items"

Integration with Existing Statusline

# In your main statusline output:
CTX_HEALTH=$(get_context_health)

# Combine with other indicators
echo "$GIT_BRANCH | $TOKEN_COUNT | $CTX_HEALTH | $DURATION"

Visual Output Examples

main | 350K tokens | [CTX:OK] | 15m        # Healthy session
main | 550K tokens | [CTX:WATCH] | 45m     # Monitor closely
main | 750K tokens | [CTX:WARN] | 1h 20m   # Create snapshot soon
main | 850K tokens | [CTX:CRITICAL] | 2h   # Snapshot immediately

Scenario 3: Priority-Based Snapshot Strategy

Context

You're working on a feature with multiple phases and want to create strategic snapshots that preserve the most important context.

Workflow

from context_management import create_snapshot, rehydrate_context

# Phase 1: After requirements gathering
# Creates high-priority snapshot with requirements
snapshot1 = create_snapshot(
    conversation_data=messages,
    name='phase1-requirements-complete'
)
print(f"Phase 1 snapshot: {snapshot1.snapshot_id}")
print(f"Token count: {snapshot1.token_count}")  # ~200 tokens (essential only)

# Phase 2: After architecture decisions
# Includes requirements + decisions
snapshot2 = create_snapshot(
    conversation_data=messages,
    name='phase2-architecture-complete'
)
print(f"Phase 2 snapshot: {snapshot2.snapshot_id}")
print(f"Token count: {snapshot2.token_count}")  # ~800 tokens (standard)

# Phase 3: After implementation
# Full context including tool usage
snapshot3 = create_snapshot(
    conversation_data=messages,
    name='phase3-implementation-complete'
)
print(f"Phase 3 snapshot: {snapshot3.snapshot_id}")
print(f"Token count: {snapshot3.token_count}")  # ~1250 tokens (comprehensive)

# After compaction, restore progressively
print("\n--- After Compaction ---")

# Start with just requirements (smallest footprint)
context = rehydrate_context(snapshot3.snapshot_id, level='essential')
print(f"Essential context loaded: ~200 tokens")

# Need to remember decisions? Upgrade
context = rehydrate_context(snapshot3.snapshot_id, level='standard')
print(f"Standard context loaded: ~800 tokens")

# Need full history? Use comprehensive
context = rehydrate_context(snapshot3.snapshot_id, level='comprehensive')
print(f"Comprehensive context loaded: ~1250 tokens")

Priority Hierarchy

The system automatically prioritizes content:

High Priority (Essential Level):
+--------------------------------------------------+
| Original Requirements                             |
| "Build authentication with JWT and refresh tokens"|
+--------------------------------------------------+
| Current State                                     |
| "Files modified: auth.py, middleware.py"          |
+--------------------------------------------------+

Medium Priority (Standard Level adds):
+--------------------------------------------------+
| Key Decisions                                     |
| 1. Use RS256 for JWT signing                      |
| 2. 15-minute token expiry                         |
+--------------------------------------------------+
| Open Items                                        |
| - Implement refresh token rotation                |
| - Add rate limiting                               |
+--------------------------------------------------+

Low Priority (Comprehensive Level adds):
+--------------------------------------------------+
| Tools Used                                        |
| Write, Edit, Read, Bash                           |
+--------------------------------------------------+
| Verbose Details                                   |
| Full decision rationales                          |
| Alternative approaches considered                 |
+--------------------------------------------------+

Scenario 4: Burn Rate Awareness

Context

You're doing heavy file operations and want to monitor your context consumption rate.

Workflow

import json
from pathlib import Path

def get_burn_rate_status():
    """Check current burn rate and monitoring frequency."""
    state_file = Path(".claude/runtime/context-automation-state.json")

    if not state_file.exists():
        return "No state data yet"

    state = json.loads(state_file.read_text())

    # Calculate burn rate
    last_tokens = state.get("last_token_count", 0)
    current_tokens = state.get("current_tokens", 0)  # You'd pass this in
    tool_count = state.get("tool_use_count", 0)

    if tool_count < 5:
        return "Insufficient data (need 5+ tool uses)"

    avg_tokens = (current_tokens - last_tokens) / tool_count

    # Determine monitoring frequency
    if avg_tokens < 1000:
        freq = 50
        risk = "Low"
    elif avg_tokens < 5000:
        freq = 10
        risk = "Medium"
    else:
        freq = 3
        risk = "High"

    return f"""
Burn Rate Analysis:
- Average tokens per tool: {avg_tokens:.0f}
- Risk level: {risk}
- Check frequency: Every {freq} tools
- Tools until next check: {freq - (tool_count % freq)}
"""

# Example output:
# Burn Rate Analysis:
# - Average tokens per tool: 3500
# - Risk level: Medium
# - Check frequency: Every 10 tools
# - Tools until next check: 7

Burn Rate Scenarios

Scenario: Normal Development (Reading/Light Edits)
+-------------------------------------------+
| Burn Rate: ~500 tokens/tool               |
| Risk: Low                                 |
| Check Every: 50 tools                     |
| Overhead: Minimal                         |
+-------------------------------------------+

Scenario: Heavy File Operations (Large Writes)
+-------------------------------------------+
| Burn Rate: ~8000 tokens/tool              |
| Risk: High                                |
| Check Every: 3 tools                      |
| Recommendation: Create checkpoint soon    |
+-------------------------------------------+

Scenario: Approaching Limits (70%+ usage)
+-------------------------------------------+
| Burn Rate: Any                            |
| Risk: Critical                            |
| Check Every: 1 tool                       |
| Action: Snapshot immediately              |
+-------------------------------------------+

Scenario 5: Proactive Session Planning

Context

You're starting a new feature and want to plan your context usage proactively.

Pre-Session Planning

# Before starting complex work, assess your context budget

from context_management import check_status

# Current state
current_tokens = 150_000  # 15% used
status = check_status(current_tokens)

# Plan your session
print("=== Session Planning ===")
print(f"Current usage: {status.percentage}%")
print(f"Available budget: {1_000_000 - current_tokens:,} tokens")

# Estimate work ahead
estimated_work = {
    "requirements_gathering": 50_000,   # Back-and-forth discussion
    "architecture_review": 100_000,     # Code exploration
    "implementation": 200_000,          # Writing files
    "testing": 100_000,                 # Running tests, debugging
    "documentation": 50_000,            # Writing docs
}

total_estimated = sum(estimated_work.values())
final_usage = current_tokens + total_estimated

print(f"\nEstimated token usage:")
for phase, tokens in estimated_work.items():
    print(f"  {phase}: {tokens:,} tokens")
print(f"  Total: {total_estimated:,} tokens")
print(f"\nProjected final usage: {final_usage / 1_000_000 * 100:.1f}%")

# Recommend checkpoint strategy
if final_usage > 700_000:
    print("\nRecommendation: Create checkpoints at:")
    print("  - After requirements (35%)")
    print("  - After architecture (45%)")
    print("  - After implementation (65%)")
    print("  - Final checkpoint before documentation")
else:
    print("\nRecommendation: Single checkpoint after implementation should suffice")

Expected Output

=== Session Planning ===
Current usage: 15.0%
Available budget: 850,000 tokens

Estimated token usage:
  requirements_gathering: 50,000 tokens
  architecture_review: 100,000 tokens
  implementation: 200,000 tokens
  testing: 100,000 tokens
  documentation: 50,000 tokens
  Total: 500,000 tokens

Projected final usage: 65.0%

Recommendation: Single checkpoint after implementation should suffice

Best Practices for Proactive Management

1. Start Sessions with Health Check

# First thing in any session
status = check_status(current_tokens)
if status.threshold_status != 'ok':
    print(f"Warning: Starting at {status.percentage}% usage")
    print("Consider clearing context or creating checkpoint first")

2. Create Checkpoints at Natural Boundaries

# After completing a logical unit of work
if task_completed:
    create_snapshot(messages, name=f'{task_name}-complete')
    print(f"Checkpoint created: {task_name}")

3. Monitor During Heavy Operations

# Before large file operations
if operation_size > 10_000_chars:
    status = check_status(current_tokens)
    if status.percentage > 60:
        create_snapshot(messages, name='pre-large-operation')

4. Use Progressive Restoration

# After compaction, start minimal
context = rehydrate_context(snapshot_id, level='essential')

# Upgrade only if needed
if need_decisions:
    context = rehydrate_context(snapshot_id, level='standard')

5. Trust the Automation

# The system handles:
# - Adaptive check frequency
# - Auto-snapshots at thresholds
# - Auto-rehydration after compaction

# You focus on:
# - Creating meaningful named checkpoints
# - Choosing appropriate restoration levels
# - Planning complex sessions proactively

Summary

Next Steps

• See basic_usage.md for fundamental operations
• See proactive_workflow.md for complete workflow patterns
• See rehydration_levels.md for level selection guidance
• See SKILL.md for complete documentation

Proactive Context Management Workflow

Real-world examples of proactive context management patterns using this skill.

Scenario 1: Long Feature Implementation

Context

You're implementing a complex authentication system that requires multiple iterations and may exceed token limits.

Workflow

from context_management import check_status, create_snapshot, rehydrate_context

# === PHASE 1: Start Implementation ===
# Begin working on authentication feature
# [... initial implementation ...]

# Check token usage after initial work
status = check_status(current_tokens=500_000)
print(f"After initial implementation: {status['usage']['percentage']}% used")
# Output: "50% used" - All good

# === PHASE 2: Continue Development ===
# Add JWT validation, middleware, tests
# [... more implementation ...]

# Check again
status = check_status(current_tokens=750_000)
print(f"After JWT implementation: {status['usage']['percentage']}% used")
print(f"Recommendation: {status['usage']['recommendation']}")
# Output: "75% used" - "Consider creating snapshot soon"

# === PHASE 3: Approaching Threshold ===
# Add refresh token logic
# [... more implementation ...]

# Check again
status = check_status(current_tokens=870_000)
print(f"After refresh tokens: {status['usage']['percentage']}% used")
# Output: "87% used" - "Snapshot recommended"

# Create snapshot NOW
snapshot = create_snapshot(
    conversation_data=messages,
    name='auth-before-error-handling'
)
snapshot_id = snapshot['snapshot']['snapshot_id']
print(f"Snapshot created: {snapshot_id}")

# === PHASE 4: Continue Safely ===
# Continue with error handling implementation
# Let Claude manage context naturally
# If compaction happens, no problem - we have snapshot

# === PHASE 5: After Compaction ===
# If context was compacted, restore essentials
context = rehydrate_context(snapshot_id, level='essential')
print("Essential context restored. Continuing work...")

Scenario 2: Context Switching Between Features

Context

You need to switch between multiple features frequently without losing context.

Workflow

from context_management import create_snapshot, rehydrate_context, list_snapshots

# === Working on Feature A ===
# Implement payment processing
# [... implementation ...]

# Need to switch to urgent bug fix
# Save Feature A context
snapshot_a = create_snapshot(
    messages_a,
    name='feature-a-payment-processing'
)
feature_a_id = snapshot_a['snapshot']['snapshot_id']
print(f"Feature A saved: {feature_a_id}")

# === Switch to Bug Fix ===
# Start fresh conversation for bug fix
# [... bug fix work ...]

# Bug fixed, now need to switch to Feature B
# [... Feature B work ...]

# === Later: Resume Feature A ===
# List available snapshots
snapshots = list_snapshots()
for snap in snapshots['snapshots']:
    if 'payment' in snap['name'].lower():
        print(f"Found Feature A snapshot: {snap['id']}")

# Restore Feature A context
context = rehydrate_context(feature_a_id, level='standard')
print("Feature A context restored. Continuing where I left off...")

Scenario 3: Preventive Snapshotting Before Risky Operations

Context

You're about to perform a large refactoring that might use a lot of tokens for discussion.

Workflow

from context_management import check_status, create_snapshot

# === Before Refactoring ===
# Check current state
status = check_status(current_tokens=650_000)
print(f"Current usage: {status['usage']['percentage']}%")

# Even though we're only at 65%, create preventive snapshot
# because refactoring discussion will use many tokens
snapshot = create_snapshot(
    messages,
    name='before-large-refactoring'
)
snapshot_id = snapshot['snapshot']['snapshot_id']
print(f"Preventive snapshot created: {snapshot_id}")
print("Safe to proceed with refactoring discussion.")

# === During Refactoring ===
# Extensive discussion about refactoring approaches
# Multiple iterations, code reviews, adjustments
# [... large refactoring discussion ...]

# === Monitor Throughout ===
status = check_status(current_tokens=920_000)
if status['status'] == 'urgent':
    print("Token usage critical!")
    # Create another snapshot at this point
    snapshot2 = create_snapshot(
        messages,
        name='refactoring-in-progress'
    )
    print(f"Progress snapshot created: {snapshot2['snapshot']['snapshot_id']}")

Scenario 4: Team Handoff

Context

You need to hand off work to a teammate with full context.

Workflow

from context_management import create_snapshot

# === End of Your Work Session ===
# Create comprehensive snapshot for handoff
snapshot = create_snapshot(
    messages,
    name='handoff-to-alice-api-implementation'
)

# Share snapshot details
print(f"""
Handoff Package:
----------------
Snapshot ID: {snapshot['snapshot']['snapshot_id']}
Name: {snapshot['snapshot']['name']}
Location: {snapshot['snapshot']['file_path']}
Token Count: {snapshot['snapshot']['token_count']}

Components included:
- Original requirements
- Key architecture decisions
- Current implementation state
- Open items and blockers
- Tools/files modified

Alice can restore this with:
rehydrate_context('{snapshot['snapshot']['snapshot_id']}', level='comprehensive')
""")

# === Alice's Side (Later) ===
# Alice starts new session and restores context
from context_management import rehydrate_context

context = rehydrate_context(
    '20251116_143522',  # The snapshot ID you shared
    level='comprehensive'  # Full details for handoff
)

print("Full context restored. I can continue from where you left off.")
print(context['context'])

Scenario 5: Milestone Snapshots

Context

Create snapshots at key milestones for easy rollback or reference.

Workflow

from context_management import create_snapshot

# === Milestone 1: Basic Implementation Complete ===
snapshot1 = create_snapshot(
    messages,
    name='milestone-01-basic-auth-complete'
)
print(f"Milestone 1 saved: {snapshot1['snapshot']['snapshot_id']}")

# Continue to next phase
# [... add middleware integration ...]

# === Milestone 2: Middleware Integration Complete ===
snapshot2 = create_snapshot(
    messages,
    name='milestone-02-middleware-complete'
)
print(f"Milestone 2 saved: {snapshot2['snapshot']['snapshot_id']}")

# Continue to next phase
# [... add tests ...]

# === Milestone 3: Tests Passing ===
snapshot3 = create_snapshot(
    messages,
    name='milestone-03-tests-passing'
)
print(f"Milestone 3 saved: {snapshot3['snapshot']['snapshot_id']}")

# Now you have snapshots at each major milestone
# Can restore to any point if needed

Scenario 6: Progressive Detail Restoration

Context

Start with minimal context, progressively add more as needed.

Workflow

from context_management import rehydrate_context

snapshot_id = '20251116_143522'

# === Phase 1: Quick Refresh ===
# Start with just the essentials
print("=== Quick Refresh (Essential) ===")
context = rehydrate_context(snapshot_id, level='essential')
print(f"Restored: Requirements + Current State")
print(f"Token cost: ~200 tokens")

# Try to continue work
# [... working ...]

# Realize you need to know the decisions made
print("\n=== Need More Context (Standard) ===")
context = rehydrate_context(snapshot_id, level='standard')
print(f"Now have: + Key Decisions + Open Items")
print(f"Token cost: ~800 tokens")

# Continue work
# [... working ...]

# Need full context for complex debugging
print("\n=== Need Everything (Comprehensive) ===")
context = rehydrate_context(snapshot_id, level='comprehensive')
print(f"Now have: Everything + Metadata")
print(f"Token cost: ~1250 tokens")

# Now have full context for debugging

Scenario 7: Automated Monitoring Loop

Context

Integrate token monitoring into your workflow.

Workflow

from context_management import check_status, create_snapshot

class ContextManager:
    """Helper class for automated monitoring."""

    def __init__(self):
        self.last_snapshot_id = None
        self.snapshots_created = 0

    def check_and_snapshot(self, current_tokens, messages, task_name=None):
        """Check usage and create snapshot if recommended."""
        status = check_status(current_tokens)

        print(f"Token usage: {status['usage']['percentage']}%")
        print(f"Status: {status['status']}")

        if status['status'] in ['recommended', 'urgent']:
            print(f"Creating snapshot (threshold reached)...")

            snapshot_name = task_name or f'auto-snapshot-{self.snapshots_created + 1}'
            result = create_snapshot(messages, name=snapshot_name)

            if result['status'] == 'success':
                self.last_snapshot_id = result['snapshot']['snapshot_id']
                self.snapshots_created += 1
                print(f"Snapshot created: {self.last_snapshot_id}")
                return self.last_snapshot_id

        return None

# Usage in workflow
manager = ContextManager()

# Check periodically throughout work
manager.check_and_snapshot(500_000, messages, 'initial-implementation')
# Output: "Token usage: 50%, Status: ok"

manager.check_and_snapshot(750_000, messages, 'middleware-added')
# Output: "Token usage: 75%, Status: consider"

manager.check_and_snapshot(880_000, messages, 'tests-added')
# Output: "Token usage: 88%, Status: recommended"
# "Creating snapshot... Snapshot created: 20251116_143522"

Best Practices

1. Monitor Regularly

# Check at natural breakpoints
# - After completing a module
# - Before starting complex discussions
# - Every hour in long sessions
status = check_status(current_tokens=current)

2. Name Descriptively

# Good naming
create_snapshot(messages, name='auth-jwt-validation-complete')
create_snapshot(messages, name='before-database-refactoring')
create_snapshot(messages, name='handoff-to-bob-frontend-work')

# Bad naming
create_snapshot(messages, name='snapshot1')
create_snapshot(messages, name='temp')
create_snapshot(messages, name='test')

3. Create Snapshots Proactively

# Don't wait for 95% - snapshot at 70-85%
if status['status'] in ['consider', 'recommended']:
    create_snapshot(messages, name=f'{current_task}-snapshot')

4. Start Minimal on Restoration

# Always start with essential
context = rehydrate_context(snapshot_id, level='essential')

# Only upgrade if needed
if need_more_context:
    context = rehydrate_context(snapshot_id, level='standard')

5. Clean Up Old Snapshots

from context_management import list_snapshots

# Periodically review snapshots
snapshots = list_snapshots()
print(f"You have {snapshots['count']} snapshots using {snapshots['total_size']}")

# Manually delete old snapshots from .claude/runtime/context-snapshots/
# Keep only active work and important milestones

Remember

• Proactive > Reactive: Create snapshots before problems
• Monitor Often: Check token usage regularly
• Name Well: Descriptive names help later
• Start Small: Use essential level first
• Trust System: Let Claude manage context naturally

Next Steps

• See rehydration_levels.md for detail level guidance
• See basic_usage.md for syntax examples
• See SKILL.md for complete documentation

Rehydration Level Guide

Comprehensive guide for choosing the right detail level when restoring context.

Three Levels Overview

Level 1: Essential

What's Included

• Original user requirements
• Current implementation state

What's NOT Included

• Key decisions and rationales
• Open items and questions
• Tools used
• Metadata

When to Use

1. Quick refresh after short break

• "What was I working on?"
• Just need the basics to remember context

2. Starting point after compaction

• Get essentials first
• Upgrade later if needed

3. Token budget is tight

• Already high token usage
• Only need minimal context

4. Continuing straightforward work

• Implementation is clear
• No complex decisions needed

Example Output

# Restored Context: auth-feature

_Snapshot created: 2025-11-16 14:35:22_

## Original Requirements

Build a JWT authentication system for API endpoints with user login,
token generation, and validation. Support refresh tokens.

## Current State

Tools invoked: 8
Files modified: jwt_handler.py, middleware.py, auth_service.py

Code Example

from context_management import rehydrate_context

# Quick refresh - just need the basics
context = rehydrate_context(
    snapshot_id='20251116_143522',
    level='essential'
)

print(context['context'])
# Output: Requirements + State (~200 tokens)

Level 2: Standard (Recommended)

What's Included

• Original user requirements
• Current implementation state
• Key decisions and rationales
• Open items and blockers

What's NOT Included

• Full decision details with alternatives
• Complete tool usage list
• Metadata and timestamps

When to Use

1. Normal context restoration (Most common)

• Default choice for most situations
• Balanced token cost vs information

2. Need to understand decisions made

• Why we chose approach X?
• What trade-offs were considered?

3. Have open questions or blockers

• Need to know what's pending
• Want to see blockers

4. Resuming work after compaction

• Good balance of context
• Usually sufficient for continuation

Example Output

# Restored Context: auth-feature

_Snapshot created: 2025-11-16 14:35:22_

## Original Requirements

Build a JWT authentication system for API endpoints with user login,
token generation, and validation. Support refresh tokens.

## Current State

Tools invoked: 8
Files modified: jwt_handler.py, middleware.py, auth_service.py

## Key Decisions

1. Use RS256 encryption instead of HS256
   - Rationale: Better security for distributed systems

2. 15-minute token expiry with refresh tokens
   - Rationale: Balance between security and UX

## Open Items

- Implement refresh token rotation
- Add error handling for expired tokens
- Decide on token storage strategy

Code Example

from context_management import rehydrate_context

# Standard restoration - most common choice
context = rehydrate_context(
    snapshot_id='20251116_143522',
    level='standard'
)

print(context['context'])
# Output: Requirements + State + Decisions + Open Items (~800 tokens)

Level 3: Comprehensive

What's Included

• Original user requirements
• Current implementation state
• Full key decisions with:
• What was decided
• Why (rationale)
• Alternatives considered
• Open items and questions
• Complete tools used list
• Metadata (timestamp, token count)

When to Use

1. Complex debugging needed

• Need full context for diagnosis
• Want to see all decisions and tools

2. Team handoffs

• Transferring work to another developer
• Need complete picture

3. After long break

• Haven't worked on this in days/weeks
• Need to fully rebuild mental model

4. Critical decision point

• Making architectural changes
• Need full history to decide

5. Documentation or review

• Writing docs about the work
• Explaining implementation to others

Example Output

# Restored Context: auth-feature

_Snapshot created: 2025-11-16 14:35:22_
_Estimated tokens: 1250_

## Original Requirements

Build a JWT authentication system for API endpoints with user login,
token generation, and validation. Support refresh tokens.

## Current State

Tools invoked: 8
Files modified: jwt_handler.py, middleware.py, auth_service.py

## Key Decisions

### Decision 1

**What:** Use RS256 asymmetric encryption
**Why:** Better security for distributed systems, public key verification
**Alternatives:** HS256 (symmetric), ES256 (elliptic curve)

### Decision 2

**What:** 15-minute access token expiry with refresh tokens
**Why:** Balance between security (short-lived) and UX (not constant re-auth)
**Alternatives:** 1-hour expiry, 5-minute expiry, no expiry

## Open Items & Questions

- Implement refresh token rotation (security requirement)
- Add error handling for expired tokens
- Decide on token storage strategy (Redis vs database?)
- How to handle token revocation?

## Tools Used

- Write
- Edit
- Read
- Bash

Code Example

from context_management import rehydrate_context

# Comprehensive - need everything
context = rehydrate_context(
    snapshot_id='20251116_143522',
    level='comprehensive'
)

print(context['context'])
# Output: Everything (~1250 tokens)

Decision Flow

Need context?
│
├─ Just checking what task was? → Essential
├─ Resuming normal work? → Standard
├─ Need full picture? → Comprehensive
│
├─ Token budget tight? → Essential, upgrade if needed
├─ Not sure? → Start with Standard
└─ Team handoff or documentation? → Comprehensive

Progressive Upgrade Pattern

Start minimal, upgrade as needed:

from context_management import rehydrate_context

snapshot_id = '20251116_143522'

# Phase 1: Start essential
context = rehydrate_context(snapshot_id, level='essential')
# "Hmm, I need to know why we chose RS256..."

# Phase 2: Upgrade to standard
context = rehydrate_context(snapshot_id, level='standard')
# "Now I see the decision, but need more details..."

# Phase 3: Get comprehensive
context = rehydrate_context(snapshot_id, level='comprehensive')
# "Perfect, now I have everything"

Token Cost Comparison

Scenario: Same Snapshot, Different Levels

snapshot_id = '20251116_143522'

# Essential: ~200 tokens
essential = rehydrate_context(snapshot_id, level='essential')
print(f"Essential tokens: ~200")

# Standard: ~800 tokens (4x essential)
standard = rehydrate_context(snapshot_id, level='standard')
print(f"Standard tokens: ~800 (4x essential)")

# Comprehensive: ~1250 tokens (6x essential, 1.5x standard)
comprehensive = rehydrate_context(snapshot_id, level='comprehensive')
print(f"Comprehensive tokens: ~1250 (6x essential)")

Token Budget Planning

If you have 900,000 tokens used and need context:

# Current usage: 900k / 1M (90%)
# Remaining: 100k tokens

# Essential: 200 tokens → 90.02% after restoration
# Safe choice, leaves room for work

# Standard: 800 tokens → 90.08% after restoration
# Acceptable, still has breathing room

# Comprehensive: 1250 tokens → 90.125% after restoration
# Risky, approaching limit again

Use Case Examples

Use Case 1: Quick Task Continuation

Scenario: Working on feature, took lunch break, coming back

Level: Essential

Why: Just need to remember what I was doing, task is straightforward

context = rehydrate_context(snapshot_id, level='essential')
# Quick refresh, back to work

Use Case 2: After Weekend

Scenario: Haven't worked on project since Friday, need to resume Monday

Level: Standard

Why: Need to rebuild mental model, remember decisions and open items

context = rehydrate_context(snapshot_id, level='standard')
# Good context refresh for new week

Use Case 3: Debugging Complex Issue

Scenario: Production bug, need to understand all implementation details

Level: Comprehensive

Why: Need complete picture including all decisions and tools used

context = rehydrate_context(snapshot_id, level='comprehensive')
# Full context for debugging

Use Case 4: Code Review Prep

Scenario: Need to explain implementation to reviewer

Level: Comprehensive

Why: Reviewer needs full context including rationales and alternatives

context = rehydrate_context(snapshot_id, level='comprehensive')
# Complete picture for review

Use Case 5: Token Budget Crisis

Scenario: Already at 950k tokens, need some context

Level: Essential

Why: Can't afford more tokens, get minimum needed

context = rehydrate_context(snapshot_id, level='essential')
# Minimal tokens, essential info only

Common Patterns

Pattern 1: Start Small, Grow

# Always start with essential
context = rehydrate_context(snapshot_id, level='essential')

# Work with that...
# If need more, upgrade to standard
if need_decisions:
    context = rehydrate_context(snapshot_id, level='standard')

# Still need more? Go comprehensive
if need_everything:
    context = rehydrate_context(snapshot_id, level='comprehensive')

Pattern 2: Match Use Case

def choose_level(use_case):
    """Helper to choose appropriate level."""
    if use_case in ['quick_refresh', 'short_break']:
        return 'essential'
    elif use_case in ['normal_work', 'resume_session', 'after_compaction']:
        return 'standard'
    elif use_case in ['debugging', 'handoff', 'review', 'long_break']:
        return 'comprehensive'
    else:
        return 'standard'  # Default

level = choose_level('debugging')
context = rehydrate_context(snapshot_id, level=level)

Pattern 3: Token Budget Aware

def safe_rehydrate(snapshot_id, current_tokens, max_tokens=1_000_000):
    """Choose level based on available token budget."""
    remaining = max_tokens - current_tokens

    if remaining > 50_000:
        # Plenty of room, use standard
        return rehydrate_context(snapshot_id, level='standard')
    elif remaining > 10_000:
        # Some room, use essential
        return rehydrate_context(snapshot_id, level='essential')
    else:
        # Very tight, warn user
        print("Warning: Token budget very tight!")
        return rehydrate_context(snapshot_id, level='essential')

context = safe_rehydrate(snapshot_id, current_tokens=950_000)

Summary

• Essential (200 tokens): Quick refresh, tight budget, simple tasks
• Standard (800 tokens): Default choice, normal work, balanced context
• Comprehensive (1250 tokens): Full picture, debugging, handoffs, reviews

Default recommendation: Start with `standard`, adjust as needed.

Next Steps

• See basic_usage.md for code examples
• See proactive_workflow.md for workflow patterns
• See SKILL.md for complete documentation

Context Management Skill - Quick Start

One-page reference for the context-management skill.

Four Actions

Basic Usage

from context_management import context_management_skill

# 1. Check status
result = context_management_skill('status', current_tokens=750000)
# Returns: {'status': 'consider', 'usage': {...}}

# 2. Create snapshot
result = context_management_skill(
    'snapshot',
    conversation_data=messages,
    name='feature-name'
)
# Returns: {'status': 'success', 'snapshot': {'snapshot_id': '...'}}

# 3. Rehydrate context
result = context_management_skill(
    'rehydrate',
    snapshot_id='20251116_143522',
    level='essential'
)
# Returns: {'status': 'success', 'context': '# Restored Context...'}

# 4. List snapshots
result = context_management_skill('list')
# Returns: {'snapshots': [...], 'count': N}

Convenience Functions

from context_management import (
    check_status,
    create_snapshot,
    rehydrate_context,
    list_snapshots
)

# Simpler API
status = check_status(current_tokens=750000)
snapshot = create_snapshot(messages, name='my-feature')
context = rehydrate_context('20251116_143522', level='standard')
snapshots = list_snapshots()

Token Thresholds

Rehydration Levels

Typical Workflow

# 1. Monitor usage
status = check_status(current_tokens=850000)

# 2. If recommended, create snapshot
if status['status'] == 'recommended':
    snapshot = create_snapshot(messages, name='current-work')
    snapshot_id = snapshot['snapshot']['snapshot_id']

# 3. Continue working...
# [Claude may compact context naturally]

# 4. After compaction, rehydrate
context = rehydrate_context(snapshot_id, level='essential')
# Claude now has essential context restored

Quick Examples

Example 1: Preventive Snapshot

# Before starting risky operation
status = check_status(current_tokens=current)
if status['status'] != 'ok':
    create_snapshot(messages, name='before-refactor')

Example 2: Context Switching

# Pause feature A
snap_a = create_snapshot(messages, name='feature-a')

# Work on feature B...

# Resume feature A
context = rehydrate_context(snap_a['snapshot']['snapshot_id'])

Example 3: Progressive Restoration

# Start minimal
context = rehydrate_context(snapshot_id, level='essential')

# Need more? Upgrade
context = rehydrate_context(snapshot_id, level='standard')

# Still need more? Go comprehensive
context = rehydrate_context(snapshot_id, level='comprehensive')

Common Patterns

Pattern: Monitor-Snapshot-Rehydrate

1. check_status() → If 70%+, create snapshot
2. create_snapshot() → Save current context
3. Continue working → Let Claude manage naturally
4. rehydrate_context() → Restore after compaction

Pattern: Snapshot at Milestones

# After completing major tasks
create_snapshot(messages, name='api-completed')
create_snapshot(messages, name='tests-passing')
create_snapshot(messages, name='ready-for-review')

Error Handling

# Status always succeeds
status = check_status(current_tokens=current)

# Snapshot requires conversation_data
result = create_snapshot(messages, name='my-feature')
if result['status'] == 'error':
    print(result['error'])

# Rehydrate requires valid snapshot_id
result = rehydrate_context('invalid_id')
if result['status'] == 'error':
    # Snapshot not found - list to find valid IDs
    snapshots = list_snapshots()

# List always succeeds (returns empty list if none)
result = list_snapshots()

File Locations

Integration

All three are complementary.

Configuration Options

# Custom snapshot directory
context_management_skill(
    'snapshot',
    conversation_data=messages,
    snapshot_dir='/custom/path'
)

# Custom max tokens
context_management_skill(
    'status',
    current_tokens=current,
    max_tokens=500_000
)

Testing

# Run all tests
pytest .claude/skills/context-management/tests/

# Run with coverage
pytest --cov=context_management tests/

Troubleshooting

Philosophy

• Proactive: User decides when to snapshot
• Selective: Extract essentials, not full dump
• Flexible: Three detail levels for rehydration
• Simple: Four bricks, clear contracts
• Standard library: No external dependencies

Remember

1. Monitor usage periodically 2. Snapshot at 70-85% threshold 3. Start with essential level 4. Upgrade detail level if needed 5. Name snapshots descriptively 6. Clean old snapshots occasionally

More Information

• Complete docs: See SKILL.md
• Architecture: See README.md
• Specification: See Specs/context-management-skill.md
• Examples: See examples/ directory

Context Management Skill

Proactive context window management for Claude Code sessions via intelligent token monitoring, context extraction, and selective rehydration.

Version 3.0 - Now with predictive budget monitoring, context health indicators, and priority-based retention.

What This Skill Does

This skill helps you proactively manage Claude's context window by:

1. Monitoring token usage against configurable thresholds 2. Extracting essential context (requirements, decisions, state) into snapshots 3. Restoring context at appropriate detail levels after compaction 4. Managing snapshots with list, create, and retrieve operations 5. Predicting capacity limits before they're reached (v3.0) 6. Providing health indicators for statusline integration (v3.0) 7. Prioritizing content retention for efficient snapshots (v3.0)

Quick Start

from context_management import context_management_skill

# Check current token usage
result = context_management_skill('status', current_tokens=750000)
# Returns: {'status': 'consider', 'usage': {...}}

# Create a snapshot
result = context_management_skill(
    'snapshot',
    conversation_data=messages,
    name='my-feature'
)
# Returns: {'status': 'success', 'snapshot': {...}}

# Rehydrate context
result = context_management_skill(
    'rehydrate',
    snapshot_id='20251116_143522',
    level='essential'
)
# Returns: {'status': 'success', 'context': '# Restored Context...'}

# List all snapshots
result = context_management_skill('list')
# Returns: {'snapshots': [...], 'count': N}

Installation

This skill uses only Python standard library - no external dependencies required.

# The skill is ready to use immediately
# No installation needed

Architecture

Four Component Bricks

This skill follows the brick philosophy with four independent, single-responsibility components:

1. TokenMonitor (token_monitor.py)

• Tracks token usage against thresholds (50%, 70%, 85%, 95%)
• Provides recommendations based on usage percentage
• Calculates tokens until next threshold

2. ContextExtractor (context_extractor.py)

• Extracts original requirements from conversation
• Identifies key decisions and rationales
• Summarizes implementation state
• Captures open items and questions
• Tracks tools used during session
• Creates snapshot files

3. ContextRehydrator (context_rehydrator.py)

• Restores context from snapshot files
• Provides three detail levels:
• Essential: Requirements + current state
• Standard: + decisions + open items
• Comprehensive: + full details + metadata
• Lists available snapshots
• Formats context for Claude to process

4. ContextManagementOrchestrator (orchestrator.py)

• Coordinates the three bricks
• Handles skill action dispatch
• Manages component lifecycle

Public Interface

# Main skill entry point
context_management_skill(action, **kwargs)

# Convenience functions
check_status(current_tokens)
create_snapshot(conversation_data, name=None)
rehydrate_context(snapshot_id, level='standard')
list_snapshots()

Usage Patterns

Pattern 1: Preventive Monitoring

# Check token usage periodically
status = check_status(current_tokens=current)

if status['status'] == 'recommended':
    # Create snapshot before hitting limit
    snapshot = create_snapshot(messages, name='before-limit')

Pattern 2: Progressive Rehydration

# Start with minimal context
context = rehydrate_context(snapshot_id, level='essential')

# Upgrade if more detail needed
if need_more_context:
    context = rehydrate_context(snapshot_id, level='standard')

# Full context if necessary
if need_everything:
    context = rehydrate_context(snapshot_id, level='comprehensive')

Pattern 3: Context Switching

# Pause current work
snapshot_a = create_snapshot(messages, name='feature-a-paused')

# Work on something else
# [... new conversation ...]

# Resume previous work
context = rehydrate_context(snapshot_a_id, level='standard')

Integration with Existing Tools

PreCompact Hook (Safety Net)

• What: Automatically saves full conversation before compaction
• When: Triggered by Claude Code
• Where: ~/.amplihack/.claude/runtime/logs/<session_id>/CONVERSATION_TRANSCRIPT.md
• Relationship: Safety net for complete recovery

/transcripts Command (Reactive Recovery)

• What: Restores full conversation history after compaction
• When: User invoked after losing context
• Where: Reads from logs directory
• Relationship: Full recovery tool

Context Management Skill (Proactive Optimization)

• What: Intelligent context extraction and selective rehydration
• When: User invoked at threshold warnings
• Where: ~/.amplihack/.claude/runtime/context-snapshots/*.json
• Relationship: Proactive optimization tool

All three are complementary, not competing.

Configuration

Token Thresholds

Default thresholds (in token_monitor.py):

THRESHOLDS = {
    'ok': 0.5,          # 0-50%: No action needed
    'consider': 0.7,    # 70%+: Consider snapshotting
    'recommended': 0.85, # 85%+: Snapshot recommended
    'urgent': 0.95      # 95%+: Snapshot urgent
}

Snapshot Storage

Default location: ~/.amplihack/.claude/runtime/context-snapshots/

Can be customized:

result = context_management_skill(
    'snapshot',
    conversation_data=messages,
    snapshot_dir='/custom/path'
)

Context Window Size

Default: 1,000,000 tokens (Claude's context window)

Can be customized:

result = context_management_skill(
    'status',
    current_tokens=current,
    max_tokens=500_000  # Custom window size
)

Testing

Comprehensive test suite with 85%+ coverage:

# Run all tests
pytest .claude/skills/context-management/tests/

# Run specific test file
pytest .claude/skills/context-management/tests/test_token_monitor.py

# Run with coverage
pytest --cov=context_management .claude/skills/context-management/tests/

Test organization:

• test_token_monitor.py: 25+ tests for TokenMonitor
• test_context_extractor.py: 20+ tests for ContextExtractor
• test_context_rehydrator.py: 25+ tests for ContextRehydrator
• test_orchestrator.py: 20+ tests for Orchestrator
• test_integration.py: 10+ end-to-end workflow tests

Philosophy Alignment

Ruthless Simplicity

• Four single-purpose bricks, no complex abstractions
• On-demand invocation, no background processes
• Pure Python standard library, zero external dependencies
• Clear contracts between components

Single Responsibility

Each brick has ONE job:

• TokenMonitor: Track usage
• ContextExtractor: Extract and snapshot
• ContextRehydrator: Restore context
• Orchestrator: Coordinate components

Zero-BS Implementation

• No stubs or placeholders
• All functions work completely
• Real file I/O, not simulated
• Actual token estimation

Trust in Emergence

• User decides when to snapshot
• User chooses detail level
• No automatic behavior
• Proactive choice, not reactive automation

File Structure

.claude/skills/context-management/
├── SKILL.md                    # Claude Code skill definition
├── README.md                   # This file
├── QUICK_START.md              # Quick reference guide
├── __init__.py                 # Public interface exports
├── core.py                     # Main skill entry point
├── models.py                   # Data models (UsageStats, ContextSnapshot)
├── token_monitor.py            # TokenMonitor brick
├── context_extractor.py        # ContextExtractor brick
├── context_rehydrator.py       # ContextRehydrator brick
├── orchestrator.py             # ContextManagementOrchestrator
├── tests/
│   ├── __init__.py
│   ├── test_token_monitor.py
│   ├── test_context_extractor.py
│   ├── test_context_rehydrator.py
│   ├── test_orchestrator.py
│   ├── test_integration.py
│   └── fixtures/
│       ├── sample_conversation.json
│       ├── sample_snapshot.json
│       └── high_token_usage.json
└── examples/
    ├── basic_usage.md
    ├── proactive_workflow.md
    ├── proactive_management.md  # NEW in v3.0
    └── rehydration_levels.md

Troubleshooting

Snapshot not found

result = rehydrate_context('invalid_id')
# Returns: {'status': 'error', 'error': 'Snapshot not found: invalid_id'}

# Solution: List snapshots to find valid IDs
snapshots = list_snapshots()

Corrupted snapshot

If a snapshot JSON is corrupted, the skill will:

• Skip it in list operations
• Raise JSONDecodeError on rehydration

Solution: Create a new snapshot with fresh data.

Token estimation inaccurate

Token estimation uses rough calculation: ~1 token per 4 characters.

This is intentional for simplicity. For exact counts, use Claude's token counter.

Contributing

This skill follows amplihack's brick philosophy. When extending:

1. Keep bricks independent (single responsibility) 2. Use only standard library 3. Write comprehensive tests (85%+ coverage) 4. Update documentation 5. Follow existing patterns

License

Part of the amplihack framework. See project LICENSE.

Support

For issues, questions, or contributions:

• See: ~/.amplihack/.claude/context/PHILOSOPHY.md for principles
• See: Specs/context-management-skill.md for specification
• See: SKILL.md for complete skill documentation
• See: QUICK_START.md for quick reference

Version

3.0.0 - Proactive features

Changelog

3.0.0 (2025-11-25)

• Added predictive budget monitoring (burn rate tracking)
• Added context health indicators for statusline integration
• Added priority-based context retention
• Added proactive_management.md example
• Updated SKILL.md with v3.0 features documentation
• Enhanced automation with smarter threshold adaptation

2.0.0 (2025-11-22)

• Refactored to use centralized context_manager.py tool
• Improved automation with adaptive checking frequency
• Added compaction detection and auto-rehydration

1.0.0 (2025-11-16)

• Initial implementation with four bricks
• Token monitoring with configurable thresholds
• Intelligent context extraction
• Three-level rehydration system
• Comprehensive test suite (85%+ coverage)
• Full documentation and examples