claude-context-monitor 1.0.0

Advanced context monitoring and management for Claude Code

Claude Code Context Monitor

🚀 Features

• Real-time status line showing context usage in all projects
• Intelligent plan detection using P90 analysis - no manual configuration needed!
• Automatic handoff generation when approaching context limits
• Claude Max/Pro support with appropriate token limits
• Global /handoff command available everywhere
• Git integration showing branch and status
• Zero configuration for new projects

📺 Demo

Your Claude Code status line will show:

💻 user:project │ 🔵 16.3% (98K) │ 🌿main ± │ 🎯MAX

⚡ Quick Install

One-Line Install

curl -fsSL https://raw.githubusercontent.com/XiaoConstantine/claude-context-monitor/main/install.sh | bash

Manual Install

git clone https://github.com/XiaoConstantine/claude-context-monitor.git
cd claude-context-monitor
./install.sh

🎯 Usage

Once installed, the system works automatically in all Claude Code projects:

Global Commands

/handoff          # Generate handoff document
/handoff --force  # Force generation

Configuration

# Switch status modes globally
claude-context-config detailed   # 💻 user:project │ 🔵 16.3% (98K) │ 🌿main ± │ 🎯MAX
claude-context-config compact    # 📁project │ 🔵16% │ 🌿±main │ 🎯M  
claude-context-config simple     # 🔵 16.3% (98K/600K) [MAX] LOW

# Check current settings
claude-context-config info

# Manual plan override (optional - auto-detection is recommended)
export CLAUDE_PLAN=max    # Force Claude Max (600K tokens)
export CLAUDE_PLAN=pro    # Force Claude Pro (200K tokens)
# Leave unset for intelligent auto-detection

🧠 Intelligent Plan Detection

The monitor automatically detects your Claude plan using P90 analysis of your usage history:

• Analyzes your last 8 days of token usage patterns
• Calculates 90th percentile usage from recent sessions
• Detects if you're on Pro (200K) or Max (600K) plan with 85% confidence
• Falls back to conservative Pro limits if insufficient data

No manual configuration needed! The system learns from your actual usage patterns.

{
  "detected_plan": "max",
  "confidence": 0.85,
  "method": "p90_analysis", 
  "p90_limit": 160000,
  "token_limit": 600000,
  "sessions_analyzed": 8
}

🔧 How It Works

1. Real-time monitoring: Reads token usage from Claude Code's session files (~/.claude/projects/)
2. Intelligent detection: Uses P90 analysis to automatically detect your Claude plan
3. Smart limits: Adjusts thresholds for Claude Max (600K) vs Pro (200K) tokens
4. Auto-handoff: Generates detailed handoff documents at 90% usage
5. Git integration: Shows current branch and dirty status

📊 Status Indicators

Context Usage Colors

• 🔵 Low (0-49%): Plenty of context remaining
• 🟢 OK (50-74%): Context usage moderate
• 🟡 High (75-89%): Approaching context limit
• 🔴 Critical (90%+): Handoff generation triggered

Git Status

• 📁 Clean: No uncommitted changes
• ⚡ Dirty: Uncommitted changes present

📋 Requirements

• Claude Code: Latest version with statusLine support
• Python 3.8+: For status monitoring scripts
• jq: For JSON configuration management
• Git: For project status detection (optional)

📖 Documentation

• Installation Guide
• Configuration Reference
• Troubleshooting
• Contributing Guide

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built for the Claude Code community
• Inspired by the need for better context management in AI-assisted development
• P90 analysis approach inspired by Maciek's Claude Code Usage Monitor

---