tokentray

Claude Code and Codex usage limits, right in your system tray.

English · 한국어

[!NOTE] Credits. tokentray is a from-scratch Python reimplementation derived from haomingkoo/claude-codex-monitor (MIT), originally a SwiftBar plugin and a PowerShell tray script. It follows that project's quota endpoints, pace and burn-out formulas and colour tiers, and brings them to Windows, macOS and Linux with one shared interface.

Features

• 🟢 Tray rings at a glance - Claude on the outside, Codex inside. Green above 50% left, amber down to 21%, red at 20% or below, grey without data.
• 📊 Detail panel - remaining %, time to reset, burn-out estimate and pace for every limit, including Opus/Sonnet and Codex model limits.
• 🔔 Alerts before you run out - at 50, 25 and 10% remaining, plus reminders before a reset.
• 🔑 One-click login recovery - opens a terminal with claude auth login or codex login when a login expires.
• 🌐 Webhooks - forward alerts to Slack, Discord, ntfy or any HTTP endpoint.
• 🖥️ Windows, macOS and Linux, in English or Korean.

A pace of 1.0x means you will hit the limit exactly at reset if you keep going at your average rate so far.

Install

[!TIP] uv is the recommended way. It downloads a matching Python for you and keeps tokentray in its own environment, so nothing else on your system changes.

Install uv once:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv and winget install --id=astral-sh.uv -e work too. Then:

uv tool install tokentray

If the shell cannot find tokentray afterwards, run uv tool update-shell and open a new terminal.

pipx

pipx install tokentray

pip

Needs Python 3.11-3.13. Install into a virtual environment:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install tokentray

Standalone builds (no Python needed)

Platform	Download	Then
	tokentray-windows-x86_64.zip	Unzip, run tokentray\tokentray-gui.exe
	tokentray-macos-arm64.zip	Move tokentray.app to Applications
	tokentray-linux-x86_64.tar.gz	Unpack, run ./install.sh

[!IMPORTANT] Standalone builds are not code-signed, so Windows SmartScreen and macOS Gatekeeper warn on first launch. See Platform notes.

Quick start

Sign in to Claude Code or Codex first - one of them is enough.

tokentray setup              # choose a language, check logins, offer start-at-login
tokentray                    # start the tray app

With a standalone build, the tokentray CLI sits next to the app (inside tokentray.app/Contents/MacOS on macOS).

Alerts and polling

tokentray config set poll_interval 300    # check every 5 minutes
tokentray config set thresholds 50,20,5   # alert at 50%, 20% and 5% left
tokentray config set remind_before 30,10  # remind 30 and 10 minutes before reset
tokentray config get thresholds

Changes reach the running app straight away, except poll_interval and language, which apply after a restart. tokentray config path shows where the config file lives.

[!TIP] Need some quiet? Choose Pause alerts for 1 hour in the tray menu. Test notification previews the alert cards with fresh data.

tokentray webhook setup --service slack
tokentray webhook test

Platform notes

• A new tray icon may land among the hidden icons. The welcome card links to the taskbar setting, where the entry's name starts with tokentray.
• On the SmartScreen prompt for a standalone build, choose More info then Run anyway.
• Installed with uv or pip, the background process shows in Task Manager as pythonw.exe.

• Builds are ad-hoc signed, not notarised. If Gatekeeper blocks the app:

  xattr -dr com.apple.quarantine /Applications/tokentray.app
  

• Apple silicon only. The app lives in the menu bar, so there is no Dock icon.

• The CLI is at /Applications/tokentray.app/Contents/MacOS/tokentray; symlink it onto your PATH to type tokentray.

• Reading Claude Code credentials from the login keychain may show an access prompt the first time.

• Notification Center delivery from a tray app is unreliable, so tokentray's own alert cards are the main channel. tokentray doctor shows what your build can do.

• x86_64 tarball only. ./install.sh adds a launcher entry and icon for your user; ./install.sh --uninstall removes them.

• Qt needs a few system libraries that minimal installs, including stock Ubuntu 24.04, may lack:

  sudo apt install libxcb-cursor0 libxkbcommon0 libegl1 libgl1 libdbus-1-3 libfontconfig1 libglib2.0-0
  

• GNOME needs the AppIndicator extension to show a tray icon; KDE works out of the box.

• On Wayland, tokentray runs through XWayland so alert cards can sit next to the tray. With linux.force_xwayland = false it runs natively, but the compositor decides where cards appear.

• Without a keyring service such as SecretService, secrets fall back to an owner-only local file, and setup tells you so.

More details

Privacy

[!NOTE] No telemetry. Claude and Codex tokens are sent only to api.anthropic.com, chatgpt.com and auth.openai.com over HTTPS. Webhooks receive alert text, never tokens.

Caches and the fallback secret file are owner-only (0600) on macOS and Linux; on Windows they inherit your user profile's permissions.

Contributing

Bug reports, ideas and pull requests are welcome, in English or Korean.

• 🐛 Found a bug? Open a bug report with tokentray --version and tokentray doctor output.
• 💡 Have an idea? Open a feature request.
• 🔒 Security issue? Report it privately - see SECURITY.md.
• 🛠️ Want to send code? Start with CONTRIBUTING.md.

License

MIT - see LICENSE, which also keeps the MIT notice of haomingkoo/claude-codex-monitor. Standalone builds bundle Qt through PySide6 (LGPLv3) as dynamically linked libraries.