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.

What you get

• 15+ AI coding tools in one place. TokenClock finds their local usage data automatically and lets you correct a path in Settings when needed.
• A clearer usage total. Reused prompt-cache reads stay out of the main number, while new input, cache creation, output, and reasoning still count.
• 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.
• API-equivalent cost. Today's token usage converted to USD at current public API rates (LiteLLM catalog with official-provider overrides, refreshed weekly). This is not a subscription bill; custom proxy models can be priced manually in Settings.
• Subscription quotas in one panel. View Codex, Claude Code, Antigravity, Cursor, and Zhipu GLM limits and reset times when those local accounts are available. Cursor Models and Other Models are shown separately; signed-out services stay hidden.
• 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.
• Hide the widget in one click. On macOS, use the menu-bar gauge to hide or restore TokenClock. On Windows, choose Hide TokenClock from the clock's right-click menu and click the tray icon to bring it back.

Platform support

Install

macOS and Linux

Paste this into Terminal:

curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bash

The 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 uninstall

On Linux, the installer automatically uses extraction mode when FUSE 2 is unavailable; no sudo dependency install is required.

Windows

Paste this into PowerShell:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Neo-Isshin/TokenClock/windows-port/cli/install.ps1)))

TokenClock 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.

# 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

Everyday use

• Left-click the clock: show or hide usage details.
• Hide or restore the widget: use the menu-bar gauge on macOS; on Windows, choose Hide TokenClock and restore it from the system tray.
• Subscription Quota: show Codex, Claude Code, Antigravity, Cursor, and Zhipu GLM limits and reset times.
• API-equivalent column: estimated USD value at public API rates, not the amount charged by a subscription (customize proxy prices in Settings).
• 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.

Supported tools

Most tools need no setup. If a tool stores data somewhere unusual, open Settings → Data Source Paths and choose its folder or file.

Windows also offers optional Kiro session-contract detection and experimental CodeBuddy current-session statistics.

Screenshots

Usage details

Clock face picker

Normal edition

Privacy

• 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.
• Subscription Quota runs only when you open its panel. It uses each installed tool's local signed-in service or saved credentials when available; TokenClock does not ask you to paste account secrets.
• 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.

Local API (optional)

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. Cost-bearing responses include "costBasis": "api_equivalent_public_list" so clients do not mistake estimates for subscription billing.

Troubleshooting

• 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.
• A subscription quota is unavailable: make sure the corresponding tool is installed and signed in, then retry from the quota panel. Some providers may not expose quota data on every plan or platform.
• Weather is unavailable: choose a city manually or check whether wttr.in is reachable from your network.
• Linux AppImage does not start: run tokenclock doctor, then reinstall. On systems without FUSE 2, the launcher automatically uses extraction mode and does not require sudo.
• Something is using too much CPU: update and restart TokenClock. Recent builds avoid repeatedly scanning old Codex and Gemini histories.
• Still stuck: run tokenclock doctor on macOS/Linux, or open a GitHub issue with your platform and TokenClock version.

Build from source

Most people should use the installers above. For contributors:

git clone https://github.com/Neo-Isshin/TokenClock.git
cd TokenClock
swift build -c release

The Normal edition shares its features across macOS, Windows, and Linux while keeping native controls and platform-specific data paths. Liquid Glass remains a separate macOS presentation built on the same usage core.

License

TokenClock is open-sourced under the MIT License — © 2026 Neo-Isshin.

Acknowledgments

• 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