ClaudeStatus/README.md

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:

   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:

   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:

   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.