简体中文 · English

🕰️ TokenClock

A native Liquid Glass desktop clock for your AI coding usage

Track Claude Code, Codex, Gemini CLI, OpenCode, and 10 more tools on one living glass dial — entirely on your Mac.

Native Liquid Glass on macOS 26+ · wallpaper-aware refraction · ambient tint · adaptive contrast · always-on-top

🧊 Liquid Glass is the interface, not a skin

TokenClock turns macOS 26's native Liquid Glass into a useful, glanceable instrument. The clock disc refracts the desktop behind it, picks up a subtle theme tint, and automatically switches its ink contrast to stay readable as the wallpaper changes. An adjustable frosted backing lets you move from clean, transparent glass to a denser dial without losing the native material.

The result is not a dashboard hidden in another window. It is an always-on-top glass object that belongs on the desktop: draggable, position-aware, and calm enough to live beside your work all day.

7 glass faces · adjustable translucency · full theme editor · macOS-native rendering

⚡ Install in one line

The installer automatically selects the native Liquid Glass build on macOS 26+ and the classic compatible build on macOS 12–15.

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

TokenClock overlays live data on the dial: today's token consumption, message count, active AI tools, usage rate, and weather. Click it to drill down from tool → session / agent and see exactly where the tokens went.

It reads the logs your AI coding tools already keep on your Mac. Nothing is uploaded.

[!NOTE] Liquid Glass build has supported macOS 27 beta 3, but may break with beta version updates.

📑 Contents

• 🌟 Core advantages
• ✨ Features
• 📸 Screenshots
• 🤖 Supported AI tools
• 🚀 Quick start — One-line install · tokenclock CLI
• 🎨 Themes
• 🧊 Liquid Glass
• 🔌 Local API server
• 🔒 Privacy
• 🛣 Roadmap
• 📦 Tech stack
• 📄 License
• 🙏 Acknowledgments

🌟 Core advantages

✨ Features

🤖 Unified multi-AI-tool detection

• Auto-detects and reads the local token / message usage logs written by 14 AI coding tools and aggregates them.
• The dial overlays today's totals, active-tool labels, and a rate emoji (🔥 burst / 🌊 calm thresholds).
• Click to expand the dropdown panel for the breakdown (tool → session / agent; see Core advantages).

🧊 Liquid Glass

• On macOS 26 the disc renders with the native Liquid Glass material — it adapts to your wallpaper and carries a subtle theme tint.
• Adaptive high-contrast ink: lighter-tinted themes automatically switch to near-black ticks / numerals for legibility.
• Ships in two variants — main (macOS 26) and normal (macOS 12) — and the tokenclock CLI picks the right one for your OS automatically.

📦 One-line install & CLI

• The normal build runs on macOS 12+, the Liquid Glass build on macOS 26+. The one-liner picks the right variant for your OS automatically, and the lightweight tokenclock CLI handles start / stop / switch / diagnose. See the install guide.

🎨 Multiple faces & thoughtful design

• 7 built-in faces (Classic / Glacier / Midnight / Luxe / Gu Feng / Railgun / Sky), each with its own personality.
• 4 hand styles (round / tapered / lance / sword); numerals in Arabic or Chinese.
• Fully custom themes: dial color, glass tint, all three hands, ticks, numerals, borders, and fonts are all adjustable.

⚙️ More

• Live clock (1s), usage refresh (30s), weather (5min).
• Weather + 12-hour forecast (auto-located by IP or pick a city); 8 time zones.
• Internationalization: Simplified Chinese / Traditional Chinese / English.
• Always-on-top · draggable · position remembered across relaunch; launch-at-login via SMAppService.
• Local API server (:9988) for integration / scripting.
• Privacy-first: all data read locally, zero upload.

📸 Screenshots

🧊 Liquid Glass build preview (macOS 26+)

⬜ Normal build preview (macOS 12+)

⚙️ Settings preview

🤖 Supported AI tools

TokenClock reads the JSONL / SQLite usage files that each tool writes locally (path priority: custom path > env var > default path; auto-detected on first launch). Defaults and env vars below.