claude-tray

System tray indicator for Claude Code API usage limits.

Displays your current utilization percentage as a live icon in your system tray, so you always know how close you are to hitting rate limits.

Features

• Live tray icon showing your 5-hour rolling utilization as a percentage
• Color-coded states: orange (normal), amber (75%+), red (90%+)
• Tooltip & menu with all limit details (5hr, 7day, 7day opus) and reset times
• Auto-refresh every 60 seconds (configurable)
• Hook integration for instant refresh after Claude Code sessions
• Cross-platform: Windows 10/11 and macOS 12+
• Startup registration to run automatically on login

Install

npm install -g claude-tray

Requires Node.js 18+ and an authenticated Claude Code session (the tool reads your existing OAuth credentials).

Quick Start

# Start the tray daemon
claude-tray start

# Check usage from the terminal (no tray needed)
claude-tray status

Commands

| Command | Description | |---|---| | start | Start the tray daemon (detached) | | start -f | Start in foreground (for debugging) | | stop | Stop the running daemon | | status | Print current usage to the terminal | | install-hook | Print Claude Code hook config | | hook-path | Print resolved path to hook script | | install-startup | Register to run at login | | remove-startup | Remove login registration | | config | Show config file path and contents |

How It Works

Claude Code credentials
        │
        │  OAuth access token
        ▼
GET api.anthropic.com/api/oauth/usage
        │
        │  { five_hour: { utilization: 37.0 }, ... }
        ▼
   Tray icon: [37]

claude-tray reads your existing Claude Code OAuth token and polls the usage API. The utilization field is already a 0-100 percentage — no math needed.

Icon States

| Icon | Meaning | |---|---| | Orange circle with % | Normal usage (0-74%) | | Amber circle with % | Elevated usage (75-89%) | | Red circle with % | Near limit (90-99%) | | Red circle with !! | At limit (100%) | | Gray circle with — | No data / idle | | Dark gray circle with ✕ | Error (auth / network) |

Configuration

Config file: ~/.claude-tray.json

{
  "pollIntervalSeconds": 60,
  "displayLimit": "five_hour"
}

| Option | Default | Description | |---|---|---| | pollIntervalSeconds | 60 | Seconds between API polls | | displayLimit | "five_hour" | Which limit to show in the icon: five_hour, seven_day, or seven_day_opus |

Claude Code Hook (Optional)

For instant refresh after each Claude Code session ends, add the hook to your settings:

claude-tray install-hook

This prints the JSON to add to ~/.claude/settings.json. The hook touches a trigger file that the daemon watches, causing an immediate usage refresh instead of waiting for the next poll cycle.

Start on Login

# Register
claude-tray install-startup

# Unregister
claude-tray remove-startup

• Windows: Adds a registry entry under HKCU\...\Run
• macOS: Creates a LaunchAgent plist

Requirements

• Node.js 18+
• Authenticated Claude Code session (run claude at least once and log in)
• sharp (installed automatically)

Troubleshooting

"No OAuth token found" — Run Claude Code (claude) and log in first. The tray reads your existing credentials.

"Token expired" — Open Claude Code to refresh your session. The daemon will pick up the new token on the next poll.

Icon doesn't appear — On Windows, check the system tray overflow area and pin the icon. On macOS, check System Settings > Control Center.

sharp install fails — Ensure you have a supported platform. See sharp installation.

License

MIT