Claude Usage Monitor
Monitor your Claude.ai chat usage directly in VS Code. This extension uses direct API access (with intelligent fallback to web scraping) to fetch your current usage percentage and reset time from Claude.ai.
Features
- Direct API Access 🚀: Fast, reliable data retrieval using Claude.ai's internal API
- 2-3x faster than traditional web scraping
- More reliable (JSON parsing vs HTML regex)
- Intelligent fallback to HTML scraping if API fails
- No breaking changes when Claude.ai updates their UI
- Dual Usage Monitoring: Track both Claude.ai usage AND development session token usage
- Claude.ai 5-hour and 7-day usage percentages
- Current session token count (from
session-data.json)
- Automatically updated when developing with Claude Code (see SESSION_TRACKING.md)
- Enhanced Usage Metrics: Separate tracking for different time windows
- 5-hour usage limit with reset time
- 7-day rolling usage with weekly reset
- Color-coded indicators for both metrics
- Status Bar Integration: See both percentages at a glance (e.g., "Claude: 45% | Tokens: 26%")
- Tree View Panel: Detailed usage information in a dedicated side panel
- Configurable Auto-Refresh: Customizable refresh interval (1-60 minutes, default 5 minutes)
- Usage Level Indicator: Shows how much "Claude time" remains (Idle/Light/Moderate/Heavy)
- Based on max of Claude.ai usage % or session token %
- Idle (0-24%): Plenty of Claude time! | Light (25-49%): Quarter+ used
- Moderate (50-79%): Much work, many thought | Heavy (80-100%): Running low!
- Auto-Start: Fetches usage data automatically when VS Code starts
- Silent Mode: Runs browser in headless (hidden) mode, shows window only if login needed
- Session Persistence: Log in once, stay authenticated across VS Code sessions
- Visual Indicators: Color-coded warnings when approaching usage limits
Installation
Prerequisites
- VS Code 1.80.0 or higher
- Node.js installed (for Puppeteer/Chromium)
Install from VSIX
- Download the
.vsix file
- Open VS Code
- Go to Extensions view (
Ctrl+Shift+X)
- Click the
... menu at the top
- Select "Install from VSIX..."
- Choose the downloaded file
First-Time Setup
The extension will automatically fetch usage data when VS Code starts. If you haven't logged in before:
- A browser window will appear (the extension detected you need to log in)
- Log in to Claude.ai with your credentials (Google, email, etc.)
- Once logged in, the extension automatically fetches your usage data
- Your session is saved locally - you won't need to log in again!
- Future fetches run silently in the background (no browser window)
That's it! The extension will now:
- Fetch usage automatically on startup
- Refresh at your configured interval (default: every 5 minutes, range: 1-60 minutes)
- Display both Claude.ai and session token usage
- Show your usage level
- Run completely hidden unless login is required
Usage
Fetch Usage Data
There are several ways to fetch your usage data:
- Click the status bar item (right side of VS Code)
- Use Command Palette (
Ctrl+Shift+P / Cmd+Shift+P):
- Search for "Fetch Claude Usage Now"
- View the Activity Bar panel:
- Click the Claude Usage icon in the Activity Bar (left sidebar)
- View detailed usage information
Configuration
Open VS Code Settings and search for "Claude Usage" to configure:
claudeUsage.fetchOnStartup
- Type: Boolean
- Default:
true ✅
- Description: Automatically fetch usage data when VS Code starts
claudeUsage.headless
- Type: Boolean
- Default:
true ✅
- Description: Run browser in headless (hidden) mode. Browser will show automatically if login is needed.
claudeUsage.autoRefreshMinutes
- Type: Number
- Default:
5
- Range:
1-60 minutes
- Description: Auto-refresh interval in minutes for checking Claude.ai usage and session token data
Recommended Configuration (settings.json):
{
"claudeUsage.fetchOnStartup": true,
"claudeUsage.headless": true,
"claudeUsage.autoRefreshMinutes": 5
}
Example: Custom Refresh Interval (settings.json):
{
"claudeUsage.fetchOnStartup": true,
"claudeUsage.headless": true,
"claudeUsage.autoRefreshMinutes": 15
}
Commands
All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
Claude: Fetch Claude Usage Now - Manually fetch current usage dataClaude: Open Claude Settings Page - Open claude.ai/settings in your default browser
How It Works
Automatic Refresh
The extension automatically refreshes usage data at configurable intervals:
- Default: Every 5 minutes
- Customizable: 1-60 minute range
- Updates both Claude.ai usage and session token data
- Runs silently in the background
Headless Browser Operation
- The extension uses Puppeteer to launch a Chromium browser
- On first run, it detects you need to log in (no session cookies found)
- Browser launches in visible mode so you can log in manually
- Your session is saved to
~/.claude-browser-session/ for future use
- Subsequent fetches launch browser in headless mode (completely hidden)
- The extension navigates directly to
https://claude.ai/settings/usage
- Usage data is extracted from the page and displayed in VS Code
- Browser closes automatically to save resources
Session Persistence
- Session cookies are stored locally by Chromium
- No credentials are stored by the extension
- Sessions typically last several weeks before expiring
- If session expires, browser will show again for re-login
Privacy & Security
- No credentials stored: The extension never stores or transmits your credentials
- Local session only: Your authentication session is saved locally by Chromium
- No data transmission: Usage data stays on your machine
- Open source: All code is available for review
Troubleshooting
Browser won't launch
Problem: Error message "Failed to launch browser"
Solutions:
- Ensure you have enough disk space (~500MB for Chromium)
- Check that no antivirus is blocking Puppeteer
- Try running VS Code as administrator (Windows)
Login timeout
Problem: "Login timeout" error after 5 minutes
Solutions:
- Complete the login process more quickly
- Check your internet connection
- Try again - the browser window should still be open
Session expired
Problem: Browser keeps asking you to log in
Solutions:
- Delete the session folder:
~/.claude-browser-session/
- Log in again - session should persist this time
- Make sure
headless mode is false during login
Can't find usage data
Problem: "Could not find usage percentage" error
Solutions:
- Claude.ai may have changed their settings page layout
- Check if you can see your usage at claude.ai/settings
- Report an issue for the extension to be updated
Problem: Browser uses too much memory
Solutions:
headless mode is enabled by default - browser runs hidden- The browser closes automatically after fetching to save memory
- Increase
autoRefreshMinutes to reduce refresh frequency (e.g., 15, 30, or 60 minutes)
Known Limitations
- Requires Chromium to be downloaded by Puppeteer (~150-200MB)
- Fetch time: 2-10 seconds depending on network speed
- If Claude.ai changes their settings page, the extension may need updates
- Sessions can expire (typically after several weeks of inactivity)
Feedback & Issues
If you encounter any issues or have suggestions:
- Check the troubleshooting section above
- Review open issues on the project repository
- Submit a new issue with:
- VS Code version
- Extension version
- Error messages from the Output panel (View → Output → Claude Usage Monitor)
- Steps to reproduce
Version History
See CHANGELOG.md for version history and updates.
License
MIT License - See LICENSE file for details
Note: This is an unofficial extension and is not affiliated with Anthropic or Claude.ai.
