# Claude Context Monitor
[](https://opensource.org/licenses/MIT)
[](https://claude.ai/code)
[](https://badge.fury.io/py/claude-context-monitor)
**Advanced context monitoring and adaptive threshold learning for Claude Code**
## 🚀 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
```
## ⚡ Installation
### 🚀 Recommended: UV + UVX (Modern Python)
```bash
# Install with uvx (no global installation needed)
uvx claude-context-monitor status
# Or install globally
uv tool install claude-context-monitor
# Use commands anywhere
claude-context status
ccm handoff --record
```
### 📦 Traditional pip
```bash
pip install claude-context-monitor
claude-context install
```
### 🔧 Legacy Shell Install
```bash
curl -fsSL https://raw.githubusercontent.com/XiaoConstantine/claude-context-monitor/main/install.sh | bash
```
### Development Install
```bash
git clone https://github.com/XiaoConstantine/claude-context-monitor.git
cd claude-context-monitor
./install.sh
```
## 🎯 Usage
### CLI Commands
```bash
# Status monitoring
claude-context status # Current context status
claude-context status -f json # JSON output
ccm status -f compact # Compact format (short alias)
# Plan detection
claude-context plan # Detect Claude plan automatically
claude-context plan --json # JSON output
# Handoff tracking & adaptive learning
claude-context handoff --record # Record handoff for threshold learning
claude-context handoff --stats # Show historical handoff statistics
claude-context handoff --summary # Get summary for documents
# Configuration
claude-context config --show # Show current config
claude-context config --set CLAUDE_PLAN=max # Set values
claude-context config --get CONTEXT_THRESHOLD
# Installation (legacy compatibility)
claude-context install # Install to ~/.claude
claude-context install --force # Force reinstall
```
### Global Claude Commands
```
/handoff # Generate handoff document (auto-records context %)
/handoff --force # Force generation
```
### Automatic Features
- **Real-time status**: Shows in Claude Code status line
- **Adaptive thresholds**: Learns from your handoff patterns
- **Plan detection**: Automatically detects Pro/Max plans
- **Git integration**: Shows branch and dirty status
# 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.
```json
{
"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](docs/INSTALL.md)
- [Configuration Reference](docs/CONFIG.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Contributing Guide](CONTRIBUTING.md)
## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built for the [Claude Code](https://claude.ai/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](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor)
---
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-context-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ai, claude, context, llm, monitoring",
"author": null,
"author_email": "Xiao <constantine124@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4b/d1/8a566ac6de8896733b159e53eeeb34327b4d3da7748d59fb2fc72d0249c6/claude_context_monitor-1.3.0.tar.gz",
"platform": null,
"description": "# Claude Context Monitor\n\n[](https://opensource.org/licenses/MIT)\n[](https://claude.ai/code)\n[](https://badge.fury.io/py/claude-context-monitor)\n\n**Advanced context monitoring and adaptive threshold learning for Claude Code**\n\n## \ud83d\ude80 Features\n\n- **Real-time status line** showing context usage in all projects\n- **Intelligent plan detection** using P90 analysis - no manual configuration needed!\n- **Automatic handoff generation** when approaching context limits \n- **Claude Max/Pro support** with appropriate token limits\n- **Global `/handoff` command** available everywhere\n- **Git integration** showing branch and status\n- **Zero configuration** for new projects\n\n## \ud83d\udcfa Demo\n\nYour Claude Code status line will show:\n```\n\ud83d\udcbb user:project \u2502 \ud83d\udd35 16.3% (98K) \u2502 \ud83c\udf3fmain \u00b1 \u2502 \ud83c\udfafMAX\n```\n\n## \u26a1 Installation\n\n### \ud83d\ude80 Recommended: UV + UVX (Modern Python)\n```bash\n# Install with uvx (no global installation needed)\nuvx claude-context-monitor status\n\n# Or install globally\nuv tool install claude-context-monitor\n\n# Use commands anywhere\nclaude-context status\nccm handoff --record\n```\n\n### \ud83d\udce6 Traditional pip\n```bash\npip install claude-context-monitor\nclaude-context install\n```\n\n### \ud83d\udd27 Legacy Shell Install\n```bash\ncurl -fsSL https://raw.githubusercontent.com/XiaoConstantine/claude-context-monitor/main/install.sh | bash\n```\n\n### Development Install\n```bash\ngit clone https://github.com/XiaoConstantine/claude-context-monitor.git\ncd claude-context-monitor\n./install.sh\n```\n\n## \ud83c\udfaf Usage\n\n### CLI Commands\n\n```bash\n# Status monitoring\nclaude-context status # Current context status \nclaude-context status -f json # JSON output\nccm status -f compact # Compact format (short alias)\n\n# Plan detection\nclaude-context plan # Detect Claude plan automatically\nclaude-context plan --json # JSON output\n\n# Handoff tracking & adaptive learning \nclaude-context handoff --record # Record handoff for threshold learning\nclaude-context handoff --stats # Show historical handoff statistics\nclaude-context handoff --summary # Get summary for documents\n\n# Configuration\nclaude-context config --show # Show current config\nclaude-context config --set CLAUDE_PLAN=max # Set values\nclaude-context config --get CONTEXT_THRESHOLD\n\n# Installation (legacy compatibility)\nclaude-context install # Install to ~/.claude\nclaude-context install --force # Force reinstall\n```\n\n### Global Claude Commands\n```\n/handoff # Generate handoff document (auto-records context %)\n/handoff --force # Force generation\n```\n\n### Automatic Features\n- **Real-time status**: Shows in Claude Code status line\n- **Adaptive thresholds**: Learns from your handoff patterns \n- **Plan detection**: Automatically detects Pro/Max plans\n- **Git integration**: Shows branch and dirty status\n\n# Manual plan override (optional - auto-detection is recommended)\nexport CLAUDE_PLAN=max # Force Claude Max (600K tokens)\nexport CLAUDE_PLAN=pro # Force Claude Pro (200K tokens)\n# Leave unset for intelligent auto-detection\n```\n\n## \ud83e\udde0 Intelligent Plan Detection\n\nThe monitor automatically detects your Claude plan using **P90 analysis** of your usage history:\n\n- **Analyzes** your last 8 days of token usage patterns\n- **Calculates** 90th percentile usage from recent sessions \n- **Detects** if you're on Pro (200K) or Max (600K) plan with 85% confidence\n- **Falls back** to conservative Pro limits if insufficient data\n\nNo manual configuration needed! The system learns from your actual usage patterns.\n\n```json\n{\n \"detected_plan\": \"max\",\n \"confidence\": 0.85,\n \"method\": \"p90_analysis\", \n \"p90_limit\": 160000,\n \"token_limit\": 600000,\n \"sessions_analyzed\": 8\n}\n```\n\n## \ud83d\udd27 How It Works\n\n1. **Real-time monitoring**: Reads token usage from Claude Code's session files (`~/.claude/projects/`)\n2. **Intelligent detection**: Uses P90 analysis to automatically detect your Claude plan\n3. **Smart limits**: Adjusts thresholds for Claude Max (600K) vs Pro (200K) tokens\n4. **Auto-handoff**: Generates detailed handoff documents at 90% usage\n5. **Git integration**: Shows current branch and dirty status\n\n## \ud83d\udcca Status Indicators\n\n### Context Usage Colors\n- \ud83d\udd35 **Low** (0-49%): Plenty of context remaining\n- \ud83d\udfe2 **OK** (50-74%): Context usage moderate \n- \ud83d\udfe1 **High** (75-89%): Approaching context limit\n- \ud83d\udd34 **Critical** (90%+): Handoff generation triggered\n\n### Git Status\n- \ud83d\udcc1 **Clean**: No uncommitted changes\n- \u26a1 **Dirty**: Uncommitted changes present\n\n## \ud83d\udccb Requirements\n\n- **Claude Code**: Latest version with statusLine support\n- **Python 3.8+**: For status monitoring scripts\n- **jq**: For JSON configuration management\n- **Git**: For project status detection (optional)\n\n## \ud83d\udcd6 Documentation\n\n- [Installation Guide](docs/INSTALL.md)\n- [Configuration Reference](docs/CONFIG.md) \n- [Troubleshooting](docs/TROUBLESHOOTING.md)\n- [Contributing Guide](CONTRIBUTING.md)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built for the [Claude Code](https://claude.ai/code) community\n- Inspired by the need for better context management in AI-assisted development\n- P90 analysis approach inspired by [Maciek's Claude Code Usage Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor)\n\n---\n",
"bugtrack_url": null,
"license": null,
"summary": "Advanced context monitoring and management for Claude Code",
"version": "1.3.0",
"project_urls": {
"Issues": "https://github.com/XiaoConstantine/claude-context-monitor/issues",
"Repository": "https://github.com/XiaoConstantine/claude-context-monitor"
},
"split_keywords": [
"ai",
" claude",
" context",
" llm",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e18c9f1beae793ae491c8028ee9c05032ba3e848eaa3d42e1e626e34cc0c09e4",
"md5": "f5d21ed78e3895391e25a1a41390e724",
"sha256": "cee20cd8c3bdd6c05ef3e867c78ac02a6d9b33d813cea573fae3236630a0cfd7"
},
"downloads": -1,
"filename": "claude_context_monitor-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5d21ed78e3895391e25a1a41390e724",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18632,
"upload_time": "2025-08-17T00:20:49",
"upload_time_iso_8601": "2025-08-17T00:20:49.245826Z",
"url": "https://files.pythonhosted.org/packages/e1/8c/9f1beae793ae491c8028ee9c05032ba3e848eaa3d42e1e626e34cc0c09e4/claude_context_monitor-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4bd18a566ac6de8896733b159e53eeeb34327b4d3da7748d59fb2fc72d0249c6",
"md5": "4354081901e681d2949433b2ebf43c47",
"sha256": "43ffd8ac82af9e6f5e41e5378ce6692360e2223978b70346535c61cbb5652b8e"
},
"downloads": -1,
"filename": "claude_context_monitor-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "4354081901e681d2949433b2ebf43c47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29363,
"upload_time": "2025-08-17T00:20:50",
"upload_time_iso_8601": "2025-08-17T00:20:50.324025Z",
"url": "https://files.pythonhosted.org/packages/4b/d1/8a566ac6de8896733b159e53eeeb34327b4d3da7748d59fb2fc72d0249c6/claude_context_monitor-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 00:20:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "XiaoConstantine",
"github_project": "claude-context-monitor",
"github_not_found": true,
"lcname": "claude-context-monitor"
}
JSON
