8b5d2f4283
Add Cinnamon panel applet that displays Claude Pro subscription usage and limits with configurable refresh interval and colors. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
133 lines
4.1 KiB
Markdown
133 lines
4.1 KiB
Markdown
# Claude Status - Cinnamon Applet
|
|
|
|
A Cinnamon panel applet that displays your Claude Pro subscription usage and limits.
|
|
|
|
## Features
|
|
|
|
- Displays current session (5-hour) usage percentage on the panel
|
|
- Color-coded indicator (green < 50%, yellow 50-80%, red > 80%)
|
|
- Popup menu showing:
|
|
- Session usage percentage and reset time
|
|
- Weekly (7-day) usage percentage and reset time
|
|
- Manual refresh button
|
|
- Automatically refreshes every 5 minutes
|
|
- Uses Claude Code OAuth credentials for authentication
|
|
|
|
## Installation
|
|
|
|
The applet has already been installed to:
|
|
```
|
|
~/.local/share/cinnamon/applets/claude-status@ksmith/
|
|
```
|
|
|
|
### Adding to Panel
|
|
|
|
1. Right-click on your Cinnamon panel
|
|
2. Select "Applets"
|
|
3. Click "Download" or "Manage" tab
|
|
4. Find "Claude Status" in the list
|
|
5. Click the "+" button or drag it to your panel
|
|
|
|
Alternatively, you can reload Cinnamon to make the applet available:
|
|
- Press `Alt+F2`
|
|
- Type `r` and press Enter
|
|
- This will restart Cinnamon and reload all applets
|
|
|
|
## Requirements
|
|
|
|
- Cinnamon desktop environment
|
|
- Claude Code credentials file at `~/.claude/.credentials.json`
|
|
- Active internet connection for API calls
|
|
|
|
## Usage
|
|
|
|
Once added to the panel:
|
|
|
|
- The applet displays your current session usage percentage (e.g., "85%")
|
|
- Click the applet to open a popup menu with detailed information:
|
|
- Session usage and time until reset
|
|
- Weekly usage and time until reset
|
|
- Refresh button to manually update the data
|
|
|
|
The applet will automatically refresh usage data every 5 minutes (configurable).
|
|
|
|
## Configuration
|
|
|
|
Right-click the applet and select "Configure..." to access settings:
|
|
|
|
### Available Settings
|
|
|
|
- **Refresh interval**: How often to check for usage updates (1-60 minutes, default: 5)
|
|
- **Color for low usage (< 50%)**: Color displayed when usage is below 50% (default: green)
|
|
- **Color for medium usage (50-80%)**: Color displayed when usage is between 50% and 80% (default: yellow)
|
|
- **Color for high usage (> 80%)**: Color displayed when usage is above 80% (default: red)
|
|
- **Show 'Claude:' prefix**: Display "Claude: " before the percentage on the panel (default: off)
|
|
|
|
Settings are applied immediately without requiring a Cinnamon restart.
|
|
|
|
## API
|
|
|
|
The applet uses the Claude API endpoint:
|
|
- **Endpoint**: `https://api.anthropic.com/api/oauth/usage`
|
|
- **Authentication**: OAuth token from `~/.claude/.credentials.json`
|
|
- **Headers**:
|
|
- `Authorization: Bearer {accessToken}`
|
|
- `anthropic-beta: oauth-2025-04-20`
|
|
|
|
## Files
|
|
|
|
- `metadata.json` - Applet metadata and configuration
|
|
- `applet.js` - Main applet logic (JavaScript with GJS bindings)
|
|
- `settings-schema.json` - Configuration options schema
|
|
- `README.md` - This file
|
|
|
|
## Troubleshooting
|
|
|
|
### Applet shows "ERR"
|
|
|
|
This indicates an error occurred. Click the applet to see the error message in the popup menu. Common issues:
|
|
|
|
1. **"Could not read credentials file"**: The credentials file is missing or inaccessible
|
|
- Check that `~/.claude/.credentials.json` exists
|
|
- Verify file permissions
|
|
|
|
2. **"Authentication failed"**: The OAuth token is invalid or expired
|
|
- Try logging in again with Claude Code
|
|
- Check that the credentials file contains a valid `accessToken`
|
|
|
|
3. **"API error: [status code]"**: The API request failed
|
|
- Check your internet connection
|
|
- The API might be temporarily unavailable
|
|
|
|
### Applet doesn't appear
|
|
|
|
1. Make sure the files are in the correct location:
|
|
```bash
|
|
ls -la ~/.local/share/cinnamon/applets/claude-status@ksmith/
|
|
```
|
|
|
|
2. Restart Cinnamon:
|
|
- Press `Alt+F2`
|
|
- Type `r` and press Enter
|
|
|
|
3. Check Cinnamon logs for errors:
|
|
```bash
|
|
journalctl -f /usr/bin/cinnamon
|
|
```
|
|
|
|
## Development
|
|
|
|
To update the applet:
|
|
|
|
1. Make changes to the source files in `/home/ksmith/Projects/ClaudeStatus/`
|
|
2. Copy updated files to the applet directory:
|
|
```bash
|
|
cp /home/ksmith/Projects/ClaudeStatus/*.js ~/.local/share/cinnamon/applets/claude-status@ksmith/
|
|
cp /home/ksmith/Projects/ClaudeStatus/metadata.json ~/.local/share/cinnamon/applets/claude-status@ksmith/
|
|
```
|
|
3. Restart Cinnamon or reload the applet
|
|
|
|
## License
|
|
|
|
This applet is provided as-is for personal use.
|