Claude-Code-Usage-Monitor

🥇Gold

Real-time monitoring of Claude Code usage with predictive analytics and warnings. Ideal for operations teams to track usage, avoid limits, and optimize workflows. Integrates with Python-based systems and terminal environments.

7,1393080Updated 2w ago

Intermediate30min to implementautomation

Saves ~45 min per use

Quick InstallView Source

git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git

Works with:

Claude

Overview

About This Skill

https://pypi.org/project/claude-monitor/

How to Use

1. **Install the Monitor**: Clone the Claude Code Usage Monitor repository (`git clone https://github.com/claude-ai/usage-monitor.git`) and install dependencies with `pip install -r requirements.txt`. Configure your project settings in `config.yaml` with your [LIMIT_TYPE] and [THRESHOLD_PERCENTAGE]. 2. **Run Real-Time Tracking**: Execute `claude-code-monitor --live` in your terminal to start monitoring. The tool will display current usage metrics and update every 30 seconds. For terminal integration, add `claude-code-monitor --watch` to your `.bashrc` or `.zshrc` file. 3. **Set Up Alerts**: Configure warning thresholds in `alerts.json` (e.g., `{"token_warning": 90, "session_warning": 85}`). Use `claude-code-monitor --setup-alerts` to integrate with Slack or email notifications via webhooks. 4. **Generate Reports**: Run `claude-code-monitor --report --output json` for detailed JSON reports or `claude-code-monitor --report --output markdown` for human-readable summaries. Schedule daily reports with cron: `0 8 * * * /path/to/claude-code-monitor --report --email team@company.com`. 5. **Optimize Workflows**: Use `claude-code-monitor --analyze --top-consumers` to identify resource-heavy operations. Apply recommendations by running `claude-code-monitor --optimize --pipeline [PIPELINE_NAME]` or manually adjusting batch sizes in your scripts. **Pro Tips:** - For Python-based systems, wrap your Claude Code calls with `with claude_code_monitor.track_operation('operation_name'):` to get granular usage data. - Use `--forecast` flag to simulate "what-if" scenarios (e.g., `claude-code-monitor --forecast --add-sessions 2`). - Integrate with CI/CD pipelines by adding `claude-code-monitor --pre-check` before deployments to prevent quota violations.

Use Cases

Monitor real-time token usage during Claude AI sessions to prevent exceeding limits.

Analyze historical usage data to optimize future Claude AI interactions and reduce costs.

Receive intelligent predictions and warnings about session limits based on past usage patterns.

Automatically switch plans based on usage to ensure optimal performance and cost management.

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Set up real-time monitoring for Claude Code usage in [PROJECT_NAME] with predictive analytics. Track [SPECIFIC_METRICS] (e.g., tokens per hour, concurrent sessions, API call frequency) and generate warnings when usage approaches [THRESHOLD_PERCENTAGE]% of [LIMIT_TYPE] (e.g., daily quota, concurrent session cap). Provide a 24-hour forecast of usage trends and suggest optimization strategies to avoid hitting limits. Include a breakdown of top resource-consuming operations and their estimated costs if applicable.

Example Output

### Claude Code Usage Monitor Report - Project: Acme Corp Analytics Suite
**Report Generated:** 2024-06-15 14:32:00 UTC

#### Current Usage Status
- **Daily Token Usage:** 18,450 / 20,000 tokens (92.25% of daily limit)
- **Concurrent Sessions:** 4 / 5 active sessions (80% of concurrent session cap)
- **API Call Frequency:** 127 calls/hour (avg. 2.12/min)
- **Estimated Cost:** $187.20 today (projected: $201.45 by EOD)

#### Predictive Analytics
- **24-hour Forecast:** Token usage will reach 98.7% of daily limit by 18:45 UTC
- **Peak Risk Period:** 16:00-19:00 UTC (high batch processing activity)
- **Concurrent Session Risk:** 95% probability of hitting cap at 17:30 UTC

#### Top Resource Consumers
1. **Data Processing Pipeline** (45% of tokens): Batch processing 500K records (avg. 2.3M tokens/session)
2. **Report Generation** (32% of tokens): Monthly financial reports (avg. 1.8M tokens/session)
3. **Model Fine-tuning** (15% of tokens): Hyperparameter optimization (avg. 900K tokens/session)
4. **API Integration Tests** (8% of tokens): Automated test suites

#### Warnings & Recommendations
⚠️ **CRITICAL:** Concurrent session limit will be reached in 3.2 hours. Suggest:
- Pause non-critical batch jobs until after 19:00 UTC
- Split the data processing pipeline into smaller batches
- Consider temporarily reducing concurrent fine-tuning sessions

📊 **Cost Optimization:** Current spending is 12% over budget. Recommend:
- Implement token batching for report generation
- Schedule heavy processing for off-peak hours (after 20:00 UTC)
- Review fine-tuning job configurations for efficiency

#### Next Steps
1. Run `claude-code-monitor --pause-batch-jobs` to temporarily halt low-priority operations
2. Execute `claude-code-monitor --optimize-pipeline` to restructure the data processing workflow
3. Schedule a team review at 16:00 UTC to reassess priorities