 Liquid Glass · macOS 26+ |
 Normal · macOS, Windows, Linux |
TokenClock is a small, always-on-top clock for your desktop. It combines the time with today's token usage, message count, active AI tools, weather, and usage pace—without making you open several dashboards.
Click the clock for session and model details. Right-click it to change the face, size, city, timezone, language, transparency, and other preferences.
- 14 AI coding tools in one place. TokenClock finds their local usage data automatically and lets you correct a path in Settings when needed.
- 8 carefully designed clock faces. Glass, Classic, Glacier, Midnight, Luxe, Antique, Railgun, and Sky, plus saved custom faces.
- Useful details without leaving the desktop. Group usage by session or model, expand individual rows, and sort by percentage.
- Codex remaining quota in Normal. Open Codex Quota to see available windows and reset times. It only checks when you open it.
- Weather without a location permission popup. Automatic weather uses an approximate city from your public IP, or you can choose a city yourself.
- A native experience on each platform. macOS uses SwiftUI/AppKit, Windows uses Win32, and Linux uses GTK3. The workflow is shared while controls keep their native appearance.
| Platform | Edition | Notes |
|---|---|---|
| macOS 26+ | Liquid Glass + Normal | Universal Apple Silicon/Intel build |
| macOS 12–25 | Normal | Classic opaque desktop widget |
| Windows 11 x86_64 | Normal | Per-user install; no administrator rights required |
| Linux x86_64 | Normal | Prebuilt GTK3 AppImage; glibc 2.35+ |
Paste this into Terminal:
curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bashThe installer chooses the right edition, verifies downloaded builds, starts TokenClock, and installs the small tokenclock helper command.
Useful commands after installation:
tokenclock doctor
tokenclock restart
tokenclock update
tokenclock uninstallOn Linux, install libfuse2 if your desktop cannot open the AppImage (libfuse2t64 on Ubuntu 24.04+).
Paste this into PowerShell:
irm https://raw.githubusercontent.com/Neo-Isshin/TokenClock/windows-port/cli/install.ps1 | iexTokenClock installs for the current user under %LOCALAPPDATA%\Programs\TokenClock. It verifies the release checksum and does not enable autostart or create shortcuts unless you ask it to.
Windows may show a reputation warning for an unsigned first release. Check that the publisher source is this repository before continuing.
Optional Windows installer choices
# Install without starting, and add a Start Menu shortcut
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Neo-Isshin/TokenClock/windows-port/cli/install.ps1))) -NoStart -StartMenuShortcut
# Check the current installation
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Neo-Isshin/TokenClock/windows-port/cli/install.ps1))) -Action Check
# Uninstall while keeping your settings
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Neo-Isshin/TokenClock/windows-port/cli/install.ps1))) -Action Uninstall- Left-click the clock: show or hide usage details.
- Codex Quota (Normal): show remaining Codex limits and reset times.
- By Session / By Model: change how details are grouped.
- By Percent: compare which tools consumed the most.
- Click a detail row: expand its sessions or models.
- Right-click the clock: open faces, sizes, display preferences, refresh, Settings, About, and Quit.
- Drag the clock: place it anywhere on your desktop; its position is remembered.
Settings includes automatic detection, tool switches, custom data paths, rate thresholds, the local API, and custom clock faces. Available rows may differ slightly by platform.
| OpenClaw | Claude Code | Gemini CLI |
| Codex | Hermes | OpenCode |
| Qwen Code | GitHub Copilot CLI | Grok CLI |
| Aider | Antigravity | Cline |
| Continue | Cursor Agent |
Most tools need no setup. If a tool stores data somewhere unusual, open Settings → Data Source Paths and choose its folder or file.
 Usage details |
 Clock face picker |
 Normal edition |
- Token and session totals are read from files already stored by your AI tools. TokenClock does not upload those logs or totals.
- The optional local API listens only on
127.0.0.1. - Automatic weather contacts the configured weather/IP services to estimate a city. It does not request macOS Location Services permission.
- Codex Quota in Normal runs only when you open its panel. It asks the installed Codex app-server for rate-limit information and does not read or modify Codex authentication files.
- Cursor cloud usage is optional. When enabled, it contacts Cursor's service using the credentials already stored by Cursor; leave it off if you only want local data.
TokenClock can expose read-only JSON for personal scripts and dashboards:
http://127.0.0.1:9988/api/usage
http://127.0.0.1:9988/api/history?days=30
The server is loopback-only, so other computers cannot connect to it directly.
- A tool shows zero: use Re-detect in Settings, then check its Data Source Path. The tool must have created at least one local session first.
- Codex Quota is unavailable: make sure you are using Normal and Codex is installed and signed in, then retry from the quota panel.
- Weather is unavailable: choose a city manually or check whether
wttr.inis reachable from your network. - Linux AppImage does not start: install
libfuse2/libfuse2t64, then try again. - Something is using too much CPU: update and restart TokenClock. Recent builds avoid repeatedly scanning old Codex and Gemini histories.
- Still stuck: run
tokenclock doctoron macOS/Linux, or open a GitHub issue with your platform and TokenClock version.
Most people should use the installers above. For contributors:
git clone https://github.com/Neo-Isshin/TokenClock.git
cd TokenClock
swift build -c releaseThe product channels are maintained separately: main for Liquid Glass macOS, normal for classic macOS, and dedicated Linux and windows-port branches for the other platforms. Platform-specific paths and UI code stay in their own channels.
TokenClock is open-sourced under the GPL v3 License — © 2026 Neo-Isshin.
- Swift and SwiftUI/AppKit
- GTK and Cairo for the Linux normal edition
- The AI coding tools whose local data formats make this overview possible
- Everyone who reports issues, tests new platforms, and improves TokenClock