{"id":28969803,"url":"https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor","last_synced_at":"2025-06-24T10:04:38.192Z","repository":{"id":299919851,"uuid":"1004631442","full_name":"Maciek-roboblog/Claude-Code-Usage-Monitor","owner":"Maciek-roboblog","description":"Real-time Claude Code usage monitor with predictions and warnings","archived":false,"fork":false,"pushed_at":"2025-06-19T01:07:17.000Z","size":69,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T01:29:32.444Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Maciek-roboblog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T00:00:05.000Z","updated_at":"2025-06-19T01:21:29.000Z","dependencies_parsed_at":"2025-06-19T01:39:47.551Z","dependency_job_id":null,"html_url":"https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor","commit_stats":null,"previous_names":["maciek-roboblog/claude-code-usage-monitor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Maciek-roboblog/Claude-Code-Usage-Monitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maciek-roboblog%2FClaude-Code-Usage-Monitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maciek-roboblog%2FClaude-Code-Usage-Monitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maciek-roboblog%2FClaude-Code-Usage-Monitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maciek-roboblog%2FClaude-Code-Usage-Monitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Maciek-roboblog","download_url":"https://codeload.github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maciek-roboblog%2FClaude-Code-Usage-Monitor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261129605,"owners_count":23113861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-24T10:01:36.100Z","updated_at":"2025-06-24T10:04:37.874Z","avatar_url":"https://github.com/Maciek-roboblog.png","language":"Python","funding_links":[],"categories":["Tooling 🧰","🚀 AI Tools for Vim, Neovim, and Terminal","\u003ca name=\"monitor\"\u003e\u003c/a\u003eSystem monitoring","Python","Claude Code Ecosystem","Monitoring \u0026 Analytics","HarmonyOS","Usage Tracker","Table of Contents","监控与分析","Productivity Tools","Code Analysis \u0026 Search","AI Coding Agents","Code \u0026 Developer Tools","工具 🧰"],"sub_categories":["Usage Monitors","Monitoring \u0026 Analytics","Windows Manager","Monitoring \u0026 Observability","Other IDEs","Claude Code","使用监控"],"readme":"# 🎯 Claude Code Usage Monitor\n[![PyPI Version](https://img.shields.io/pypi/v/claude-monitor.svg)](https://pypi.org/project/claude-monitor/)\n[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\nA beautiful real-time terminal monitoring tool for Claude AI token usage. Track your token consumption, burn rate, and get predictions about when you'll run out of tokens.\n\n![Claude Token Monitor Screenshot](https://raw.githubusercontent.com/Maciek-roboblog/Claude-Code-Usage-Monitor/main/doc/sc.png)\n\n---\n\n## 📑 Table of Contents\n\n- [✨ Key Features](#-key-features)\n- [🚀 Installation](#-installation)\n  - [⚡ Modern Installation with uv (Recommended)](#-modern-installation-with-uv-recommended)\n  - [📦 Installation with pip](#-installation-with-pip)\n  - [🛠️ Other Package Managers](#️-other-package-managers)\n- [📖 Usage](#-usage)\n  - [Basic Usage](#basic-usage)\n  - [Configuration Options](#configuration-options)\n  - [Available Plans](#available-plans)\n- [🙏 Please Help Test This Release!](#-please-help-test-this-release)\n- [✨ Features \u0026 How It Works](#-features--how-it-works)\n  - [Current Features](#current-features)\n  - [Understanding Claude Sessions](#understanding-claude-sessions)\n  - [Token Limits by Plan](#token-limits-by-plan)\n  - [Smart Detection Features](#smart-detection-features)\n- [🚀 Usage Examples](#-usage-examples)\n  - [Common Scenarios](#common-scenarios)\n  - [Best Practices](#best-practices)\n- [🔧 Development Installation](#-development-installation)\n- [Troubleshooting](#troubleshooting)\n  - [Installation Issues](#installation-issues)\n  - [Runtime Issues](#runtime-issues)\n- [📞 Contact](#-contact)\n- [📚 Additional Documentation](#-additional-documentation)\n- [📝 License](#-license)\n- [🤝 Contributors](#-contributors)\n- [🙏 Acknowledgments](#-acknowledgments)\n\n\n\n## ✨ Key Features\n\n- **🔄 Real-time monitoring** - Updates every 3 seconds with smooth refresh\n- **📊 Visual progress bars** - Beautiful color-coded token and time progress bars\n- **🔮 Smart predictions** - Calculates when tokens will run out based on current burn rate\n- **🤖 Auto-detection** - Automatically switches to custom max when Pro limit is exceeded\n- **📋 Multiple plan support** - Works with Pro, Max5, Max20, and auto-detect plans\n- **⚠️ Warning system** - Alerts when tokens exceed limits or will deplete before session reset\n- **💼 Professional UI** - Clean, colorful terminal interface with emojis\n- **⏰ Customizable scheduling** - Set your own reset times and timezones\n\n\n## 🚀 Installation\n### ⚡ Modern Installation with uv (Recommended)\n\n**Why uv is the best choice:**\n- ✅ Creates isolated environments automatically (no system conflicts)\n- ✅ No Python version issues\n- ✅ No \"externally-managed-environment\" errors\n- ✅ Easy updates and uninstallation\n- ✅ Works on all platforms\n\nThe fastest and easiest way to install and use the monitor:\n\n[![PyPI](https://img.shields.io/pypi/v/claude-monitor.svg)](https://pypi.org/project/claude-monitor/)\n\n#### Install from PyPI\n\n```bash\n# Install directly from PyPI with uv (easiest)\nuv tool install claude-monitor\n\n# Run from anywhere\nclaude-monitor\n```\n\n#### Install from Source\n\n```bash\n# Clone and install from source\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\nuv tool install .\n\n# Run from anywhere\nclaude-monitor\n```\n\n#### First-time uv users\nIf you don't have uv installed yet, get it with one command:\n\n```bash\n# On Linux/macOS:\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows:\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# After installation, restart your terminal\n```\n\n### 📦 Installation with pip\n\n```bash\n# Install from PyPI\npip install claude-monitor\n\n# If claude-monitor command is not found, add ~/.local/bin to PATH:\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc  # or restart your terminal\n\n# Run from anywhere (dependencies auto-install on first run)\nclaude-monitor\n```\n\n\u003e\n\u003e **⚠️ PATH Setup**: If you see `WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH`, follow the export PATH command above.\n\u003e\n\u003e **⚠️ Important**: On modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter an \"externally-managed-environment\" error. Instead of using `--break-system-packages`, we strongly recommend:\n\u003e 1. **Use uv instead** (see above) - it's safer and easier\n\u003e 2. **Use a virtual environment** - `python3 -m venv myenv \u0026\u0026 source myenv/bin/activate`\n\u003e 3. **Use pipx** - `pipx install claude-monitor`\n\u003e\n\u003e See the Troubleshooting section for detailed solutions.\n\n### 🛠️ Other Package Managers\n\n#### pipx (Isolated Environments)\n```bash\n# Install with pipx\npipx install claude-monitor\n\n# Run from anywhere (dependencies auto-install on first run)\nclaude-monitor\n```\n\n#### conda/mamba\n```bash\n# Install with pip in conda environment\npip install claude-monitor\n\n# Run from anywhere (dependencies auto-install on first run)\nclaude-monitor\n```\n\n## 📖 Usage\n\n### Basic Usage\n\n#### With uv tool installation (Recommended)\n```bash\n# Default (Pro plan - 7,000 tokens)\nclaude-monitor\n\n# Exit the monitor\n# Press Ctrl+C to gracefully exit\n```\n\n#### Development mode\nIf running from source, use `./claude_monitor.py` instead of `claude-monitor`.\n\n### Configuration Options\n\n#### Specify Your Plan\n\n```bash\n# Pro plan (~7,000 tokens) - Default\nclaude-monitor --plan pro\n\n# Max5 plan (~35,000 tokens)\nclaude-monitor --plan max5\n\n# Max20 plan (~140,000 tokens)\nclaude-monitor --plan max20\n\n# Auto-detect from highest previous session\nclaude-monitor --plan custom_max\n```\n\n#### Custom Reset Times\n\n```bash\n# Reset at 3 AM\nclaude-monitor --reset-hour 3\n\n# Reset at 10 PM\nclaude-monitor --reset-hour 22\n```\n\n#### Timezone Configuration\n\nThe default timezone is **Europe/Warsaw**. Change it to any valid timezone:\n\n```bash\n# Use US Eastern Time\nclaude-monitor --timezone US/Eastern\n\n# Use Tokyo time\nclaude-monitor --timezone Asia/Tokyo\n\n# Use UTC\nclaude-monitor --timezone UTC\n\n# Use London time\nclaude-monitor --timezone Europe/London\n```\n\n### Available Plans\n\n| Plan | Token Limit | Best For |\n|------|-------------|----------|\n| **pro** | ~7,000 | Light usage, testing (default) |\n| **max5** | ~35,000 | Regular development |\n| **max20** | ~140,000 | Heavy usage, large projects |\n| **custom_max** | Auto-detect | Uses highest from previous sessions |\n\n\n## 🙏 Please Help Test This Release!\n\n\u003e **We need your help!** This is a new release and we want to ensure it works perfectly on all systems.\n\u003e\n\u003e **If something doesn't work:**\n\u003e 1. Switch to the [develop branch](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/tree/develop) for the latest fixes:\n\u003e    ```bash\n\u003e    git clone -b develop https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\n\u003e    cd Claude-Code-Usage-Monitor\n\u003e    python3 -m venv venv\n\u003e    source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\u003e    pip install -e .\n\u003e    claude-monitor\n\u003e    ```\n\u003e 2. Create an issue with title format: **[MAIN-PROBLEM]: Your specific problem**\n\u003e    - Example: `[MAIN-PROBLEM]: Command not found after pip install on Ubuntu 24.04`\n\u003e    - Include your OS, Python version, and installation method\n\u003e    - [Create Issue Here](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues/new)\n\u003e\n\u003e **Thank you for helping make this tool better! 🚀**\n\n## LATEST STABLE VERSION FOR USE IS ON PYPI THIS VERSION IS LITTLE BIT TRICKY AND I WILL FIX IT 24.06.2025\n\n\n## ✨ Features \u0026 How It Works\n\n### Current Features\n\n#### 🔄 Real-time Monitoring\n- Updates every 3 seconds with smooth refresh\n- No screen flicker - intelligent display updates\n- Live token consumption tracking across multiple sessions\n\n#### 📊 Visual Progress Bars\n- **Token Progress**: Color-coded bars showing current usage vs limits\n- **Time Progress**: Visual countdown to next session reset\n- **Burn Rate Indicator**: Real-time consumption velocity\n\n#### 🔮 Smart Predictions\n- Calculates when tokens will run out based on current burn rate\n- Warns if tokens will deplete before next session reset\n- Analyzes usage patterns from the last hour\n\n#### 🤖 Auto-Detection System\n- **Smart Plan Switching**: Automatically switches from Pro to custom_max when limits exceeded\n- **Limit Discovery**: Scans previous sessions to find your actual token limits\n- **Intelligent Notifications**: Shows when automatic switches occur\n\n### Understanding Claude Sessions\n\n#### How Claude Code Sessions Work\n\nClaude Code operates on a **5-hour rolling session window system**:\n\n1. **Session Start**: Begins with your first message to Claude\n2. **Session Duration**: Lasts exactly 5 hours from that first message\n3. **Token Limits**: Apply within each 5-hour session window\n4. **Multiple Sessions**: Can have several active sessions simultaneously\n5. **Rolling Windows**: New sessions can start while others are still active\n\n#### Session Reset Schedule\n\n**Default reference times** (in your configured timezone):\n- `04:00`, `09:00`, `14:00`, `18:00`, `23:00`\n\n\u003e **⚠️ Important**: These are reference times for planning. Your actual token refresh happens exactly 5 hours after YOUR first message in each session.\n\n**Example Session Timeline:**\n```\n10:30 AM - First message (Session A starts)\n03:30 PM - Session A expires (5 hours later)\n\n12:15 PM - First message (Session B starts)\n05:15 PM - Session B expires (5 hours later)\n```\n\n#### Burn Rate Calculation\n\nThe monitor calculates burn rate using sophisticated analysis:\n\n1. **Data Collection**: Gathers token usage from all sessions in the last hour\n2. **Pattern Analysis**: Identifies consumption trends across overlapping sessions\n3. **Velocity Tracking**: Calculates tokens consumed per minute\n4. **Prediction Engine**: Estimates when current session tokens will deplete\n5. **Real-time Updates**: Adjusts predictions as usage patterns change\n\n### Token Limits by Plan\n\n#### Standard Plans\n\n| Plan | Approximate Limit | Typical Usage |\n|------|------------------|---------------|\n| **Claude Pro** | ~7,000 tokens | Light coding, testing, learning |\n| **Claude Max5** | ~35,000 tokens | Regular development work |\n| **Claude Max20** | ~140,000 tokens | Heavy usage, large projects |\n\n#### Auto-Detection Plans\n\n| Plan | How It Works | Best For |\n|------|-------------|----------|\n| **custom_max** | Scans all previous sessions, uses highest token count found | Users with variable/unknown limits |\n\n### Smart Detection Features\n\n#### Automatic Plan Switching\n\nWhen using the default Pro plan:\n\n1. **Detection**: Monitor notices token usage exceeding 7,000\n2. **Analysis**: Scans previous sessions for actual limits\n3. **Switch**: Automatically changes to custom_max mode\n4. **Notification**: Displays clear message about the change\n5. **Continuation**: Keeps monitoring with new, higher limit\n\n#### Limit Discovery Process\n\nThe auto-detection system:\n\n1. **Scans History**: Examines all available session blocks\n2. **Finds Peaks**: Identifies highest token usage achieved\n3. **Validates Data**: Ensures data quality and recency\n4. **Sets Limits**: Uses discovered maximum as new limit\n5. **Learns Patterns**: Adapts to your actual usage capabilities\n\n\n## 🚀 Usage Examples\n\n### Common Scenarios\n\n#### 🌅 Morning Developer\n**Scenario**: You start work at 9 AM and want tokens to reset aligned with your schedule.\n\n```bash\n# Set custom reset time to 9 AM\n./claude_monitor.py --reset-hour 9\n\n# With your timezone\n./claude_monitor.py --reset-hour 9 --timezone US/Eastern\n```\n\n**Benefits**:\n- Reset times align with your work schedule\n- Better planning for daily token allocation\n- Predictable session windows\n\n#### 🌙 Night Owl Coder\n**Scenario**: You often work past midnight and need flexible reset scheduling.\n\n```bash\n# Reset at midnight for clean daily boundaries\n./claude_monitor.py --reset-hour 0\n\n# Late evening reset (11 PM)\n./claude_monitor.py --reset-hour 23\n```\n\n**Strategy**:\n- Plan heavy coding sessions around reset times\n- Use late resets to span midnight work sessions\n- Monitor burn rate during peak hours\n\n#### 🔄 Heavy User with Variable Limits\n**Scenario**: Your token limits seem to change, and you're not sure of your exact plan.\n\n```bash\n# Auto-detect your highest previous usage\nclaude-monitor --plan custom_max\n\n# Monitor with custom scheduling\nclaude-monitor --plan custom_max --reset-hour 6\n```\n\n**Approach**:\n- Let auto-detection find your real limits\n- Monitor for a week to understand patterns\n- Note when limits change or reset\n\n#### 🌍 International User\n**Scenario**: You're working across different timezones or traveling.\n\n```bash\n# US East Coast\nclaude-monitor --timezone America/New_York\n\n# Europe\nclaude-monitor --timezone Europe/London\n\n# Asia Pacific\nclaude-monitor --timezone Asia/Singapore\n\n# UTC for international team coordination\nclaude-monitor --timezone UTC --reset-hour 12\n```\n\n#### ⚡ Quick Check\n**Scenario**: You just want to see current status without configuration.\n\n```bash\n# Just run it with defaults\nclaude-monitor\n\n# Press Ctrl+C after checking status\n```\n\n### Plan Selection Strategies\n\n#### How to Choose Your Plan\n\n**Start with Default (Recommended for New Users)**\n```bash\n# Pro plan detection with auto-switching\nclaude-monitor\n```\n- Monitor will detect if you exceed Pro limits\n- Automatically switches to custom_max if needed\n- Shows notification when switching occurs\n\n**Known Subscription Users**\n```bash\n# If you know you have Max5\nclaude-monitor --plan max5\n\n# If you know you have Max20\nclaude-monitor --plan max20\n```\n\n**Unknown Limits**\n```bash\n# Auto-detect from previous usage\nclaude-monitor --plan custom_max\n```\n\n### Best Practices\n\n#### Setup Best Practices\n\n1. **Start Early in Sessions**\n   ```bash\n   # Begin monitoring when starting Claude work (uv installation)\n   claude-monitor\n\n   # Or development mode\n   ./claude_monitor.py\n   ```\n   - Gives accurate session tracking from the start\n   - Better burn rate calculations\n   - Early warning for limit approaches\n\n2. **Use Modern Installation (Recommended)**\n   ```bash\n   # Easy installation and updates with uv\n   uv tool install claude-monitor\n   claude-monitor --plan max5\n   ```\n   - Clean system installation\n   - Easy updates and maintenance\n   - Available from anywhere\n\n3. **Custom Shell Alias (Legacy Setup)**\n   ```bash\n   # Add to ~/.bashrc or ~/.zshrc (only for development setup)\n   alias claude-monitor='cd ~/Claude-Code-Usage-Monitor \u0026\u0026 source venv/bin/activate \u0026\u0026 ./claude_monitor.py'\n   ```\n\n#### Usage Best Practices\n\n1. **Monitor Burn Rate Velocity**\n   - Watch for sudden spikes in token consumption\n   - Adjust coding intensity based on remaining time\n   - Plan big refactors around session resets\n\n2. **Strategic Session Planning**\n   ```bash\n   # Plan heavy usage around reset times\n   claude-monitor --reset-hour 9\n   ```\n   - Schedule large tasks after resets\n   - Use lighter tasks when approaching limits\n   - Leverage multiple overlapping sessions\n\n3. **Timezone Awareness**\n   ```bash\n   # Always use your actual timezone\n   claude-monitor --timezone Europe/Warsaw\n   ```\n   - Accurate reset time predictions\n   - Better planning for work schedules\n   - Correct session expiration estimates\n\n#### Optimization Tips\n\n1. **Terminal Setup**\n   - Use terminals with at least 80 character width\n   - Enable color support for better visual feedback\n   - Consider dedicated terminal window for monitoring\n\n2. **Workflow Integration**\n   ```bash\n   # Start monitoring with your development session (uv installation)\n   tmux new-session -d -s claude-monitor 'claude-monitor'\n\n   # Or development mode\n   tmux new-session -d -s claude-monitor './claude_monitor.py'\n\n   # Check status anytime\n   tmux attach -t claude-monitor\n   ```\n\n3. **Multi-Session Strategy**\n   - Remember sessions last exactly 5 hours\n   - You can have multiple overlapping sessions\n   - Plan work across session boundaries\n\n#### Real-World Workflows\n\n**Large Project Development**\n```bash\n# Setup for sustained development\nclaude-monitor --plan max20 --reset-hour 8 --timezone America/New_York\n```\n\n**Daily Routine**:\n1. **8:00 AM**: Fresh tokens, start major features\n2. **10:00 AM**: Check burn rate, adjust intensity\n3. **12:00 PM**: Monitor for afternoon session planning\n4. **2:00 PM**: New session window, tackle complex problems\n5. **4:00 PM**: Light tasks, prepare for evening session\n\n**Learning \u0026 Experimentation**\n```bash\n# Flexible setup for learning\nclaude-monitor --plan pro\n```\n\n**Sprint Development**\n```bash\n# High-intensity development setup\nclaude-monitor --plan max20 --reset-hour 6\n```\n\n## 🔧 Development Installation\n\nFor contributors and developers who want to work with the source code:\n\n### Quick Start (Development/Testing)\n\nFor immediate testing or development:\n\n```bash\n# Install Python dependency\npip install pytz\npip install rich\u003e=13.0.0\n\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\npython claude_monitor.py\n```\n\n### Prerequisites\n\n1. **Python 3.7+** installed on your system\n\n\n### Virtual Environment Setup\n\n#### Why Use Virtual Environment?\n\nUsing a virtual environment is **strongly recommended** because:\n\n- **🛡️ Isolation**: Keeps your system Python clean and prevents dependency conflicts\n- **📦 Portability**: Easy to replicate the exact environment on different machines\n- **🔄 Version Control**: Lock specific versions of dependencies for stability\n- **🧹 Clean Uninstall**: Simply delete the virtual environment folder to remove everything\n- **👥 Team Collaboration**: Everyone uses the same Python and package versions\n\n#### Installing virtualenv (if needed)\n\nIf you don't have `venv` module available:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install python3-venv\n\n# Fedora/RHEL/CentOS\nsudo dnf install python3-venv\n\n# macOS (usually comes with Python)\n# If not available, install Python via Homebrew:\nbrew install python3\n\n# Windows (usually comes with Python)\n# If not available, reinstall Python from python.org\n# Make sure to check \"Add Python to PATH\" during installation\n```\n\nAlternatively, use the `virtualenv` package:\n```bash\n# Install virtualenv via pip\npip install virtualenv\n\n# Then create virtual environment with:\nvirtualenv venv\n# instead of: python3 -m venv venv\n```\n\n#### Step-by-Step Setup\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\n\n# 2. Create virtual environment\npython3 -m venv venv\n# Or if using virtualenv package:\n# virtualenv venv\n\n# 3. Activate virtual environment\n# On Linux/Mac:\nsource venv/bin/activate\n# On Windows:\n# venv\\Scripts\\activate\n\n# 4. Install Python dependencies\npip install pytz\npip install rich\u003e=13.0.0\n# 5. Make script executable (Linux/Mac only)\nchmod +x claude_monitor.py\n\n# 6. Run the monitor\npython claude_monitor.py\n```\n\n#### Daily Usage\n\nAfter initial setup, you only need:\n\n```bash\n# Navigate to project directory\ncd Claude-Code-Usage-Monitor\n\n# Activate virtual environment\nsource venv/bin/activate  # Linux/Mac\n# venv\\Scripts\\activate   # Windows\n\n# Run monitor\n./claude_monitor.py  # Linux/Mac\n# python claude_monitor.py  # Windows\n\n# When done, deactivate\ndeactivate\n```\n\n#### Pro Tip: Shell Alias\n\nCreate an alias for quick access:\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nalias claude-monitor='cd ~/Claude-Code-Usage-Monitor \u0026\u0026 source venv/bin/activate \u0026\u0026 ./claude_monitor.py'\n\n# Then just run:\nclaude-monitor\n```\n\n## Troubleshooting\n\n### Installation Issues\n\n#### \"externally-managed-environment\" Error\n\nOn modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter:\n```\nerror: externally-managed-environment\n× This environment is externally managed\n```\n\n**Solutions (in order of preference):**\n\n1. **Use uv (Recommended)**\n   ```bash\n   # Install uv first\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Then install with uv\n   uv tool install claude-monitor\n   ```\n\n2. **Use pipx (Isolated Environment)**\n   ```bash\n   # Install pipx\n   sudo apt install pipx  # Ubuntu/Debian\n   # or\n   python3 -m pip install --user pipx\n\n   # Install claude-monitor\n   pipx install claude-monitor\n   ```\n\n3. **Use virtual environment**\n   ```bash\n   python3 -m venv myenv\n   source myenv/bin/activate\n   pip install claude-monitor\n   ```\n\n4. **Force installation (Not Recommended)**\n   ```bash\n   pip install --user claude-monitor --break-system-packages\n   ```\n   ⚠️ **Warning**: This bypasses system protection and may cause conflicts. We strongly recommend using a virtual environment instead.\n\n#### Command Not Found After pip Install\n\nIf `claude-monitor` command is not found after pip installation:\n\n1. **Check if it's a PATH issue**\n   ```bash\n   # Look for the warning message during pip install:\n   # WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH\n   ```\n\n2. **Add to PATH**\n   ```bash\n   # Add this to ~/.bashrc or ~/.zshrc\n   echo 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\n\n   # Reload shell\n   source ~/.bashrc  # or source ~/.zshrc\n   ```\n\n3. **Verify installation location**\n   ```bash\n   # Find where pip installed the script\n   pip show -f claude-monitor | grep claude-monitor\n   ```\n\n4. **Run directly with Python**\n   ```bash\n   python3 -m claude_monitor\n   ```\n\n#### Python Version Conflicts\n\nIf you have multiple Python versions:\n\n1. **Check Python version**\n   ```bash\n   python3 --version\n   pip3 --version\n   ```\n\n2. **Use specific Python version**\n   ```bash\n   python3.11 -m pip install claude-monitor\n   python3.11 -m claude_monitor\n   ```\n\n3. **Use uv (handles Python versions automatically)**\n   ```bash\n   uv tool install claude-monitor\n   ```\n\n### Runtime Issues\n\n#### No active session found\nIf you encounter the error `No active session found`, please follow these steps:\n\n1. **Initial Test**:\n   Launch Claude Code and send at least two messages. In some cases, the session may not initialize correctly on the first attempt, but it resolves after a few interactions.\n\n2. **Configuration Path**:\n   If the issue persists, consider specifying a custom configuration path. By default, Claude Code uses `~/.config/claude`. You may need to adjust this path depending on your environment.\n\n```bash\nCLAUDE_CONFIG_DIR=~/.config/claude ./claude_monitor.py\n```\n\n\n## 📞 Contact\n\nHave questions, suggestions, or want to collaborate? Feel free to reach out!\n\n**📧 Email**: [maciek@roboblog.eu](mailto:maciek@roboblog.eu)\n\nWhether you need help with setup, have feature requests, found a bug, or want to discuss potential improvements, don't hesitate to get in touch. I'm always happy to help and hear from users of the Claude Code Usage Monitor!\n\n\n## 📚 Additional Documentation\n\n- **[Development Roadmap](DEVELOPMENT.md)** - ML features, PyPI package, Docker plans\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute, development guidelines\n- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions\n\n\n## 📝 License\n\n[MIT License](LICENSE) - feel free to use and modify as needed.\n\n## 🤝 Contributors\n\n- [@adawalli](https://github.com/adawalli)\n- [@taylorwilsdon](https://github.com/taylorwilsdon)\n- [@moneroexamples](https://github.com/moneroexamples)\n\nWant to contribute? Check out our [Contributing Guide](CONTRIBUTING.md)!\n\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Maciek-roboblog/Claude-Code-Usage-Monitor\u0026type=Date)](https://www.star-history.com/#Maciek-roboblog/Claude-Code-Usage-Monitor\u0026Date)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ Star this repo if you find it useful! ⭐**\n\n[Report Bug](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) • [Request Feature](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) • [Contribute](CONTRIBUTING.md)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMaciek-roboblog%2FClaude-Code-Usage-Monitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMaciek-roboblog%2FClaude-Code-Usage-Monitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMaciek-roboblog%2FClaude-Code-Usage-Monitor/lists"}