Claude Usage Monitor
Monitor your Claude.ai chat usage directly in VS Code. This extension uses Puppeteer to fetch your current usage percentage and reset time from the Claude.ai settings page.
Features
- Real-time Usage Monitoring: See your Claude.ai usage percentage at a glance
- Status Bar Integration: Quick view in the VS Code status bar
- Tree View Panel: Detailed usage information in a dedicated side panel
- Smart Activity-Based Refresh: Automatically adjusts refresh rate based on your coding activity
- Heavy coding (100+ edits/15min): Refresh every 5 minutes
- Moderate activity (30-100 edits/15min): Refresh every 15 minutes
- Light activity (1-30 edits/15min): Refresh every 30 minutes
- Idle (no activity): Refresh every 60 minutes
- 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
- Direct Navigation: Optimized scraping that goes straight to the usage page
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 smart intervals based on your coding activity
- 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.activityBasedRefresh 🆕
- Type: Boolean
- Default:
true ✅
- Description: Automatically adjust refresh rate based on coding activity (5-60 minutes). Disable to use fixed interval.
claudeUsage.autoRefreshMinutes
- Type: Number
- Default:
15
- Description: Fixed auto-refresh interval in minutes (only used when Activity-Based Refresh is disabled)
Recommended Configuration (settings.json):
{
"claudeUsage.fetchOnStartup": true,
"claudeUsage.headless": true,
"claudeUsage.activityBasedRefresh": true
}
For Fixed Interval Instead (settings.json):
{
"claudeUsage.fetchOnStartup": true,
"claudeUsage.headless": true,
"claudeUsage.activityBasedRefresh": false,
"claudeUsage.autoRefreshMinutes": 30
}
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
Smart Activity Detection
The extension monitors your VS Code activity to optimize refresh timing:
- Tracks text edits, file saves, and editor changes
- Calculates activity level every 15 minutes
- Adjusts refresh rate automatically:
- Heavy coding: 5-minute intervals
- Moderate work: 15-minute intervals
- Light activity: 30-minute intervals
- Idle/break: 60-minute intervals
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- Activity-based refresh automatically reduces frequency when idle
- The browser closes automatically after fetching to save memory
- If using fixed interval, increase
autoRefreshMinutes to reduce frequency
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.
