發布日期：2026-05-25
這次更新讓選單列上的數字更新變得瞬間到位。以前系統是靠一個呆呆的計時器，每隔一分鐘才去查一次你的用量有沒有變，所以常常會慢半拍；現在它學會了直接監聽作業系統的檔案變動事件（FSEvents），你一燒掉額度，畫面在幾毫秒內就會立刻跳動。不僅反應變快，背後讀資料也變得更省力：現在它只會去解析真正有變動的歷史紀錄，不再每次都把沒變的舊檔案重讀一遍，大幅減輕你硬碟的負擔。另外，如果你同時開了好幾個終端機視窗在跑 Claude，現在存檔時會自動排隊鎖上檔案（檔案鎖），不會再發生兩邊同時寫入把用量互相覆蓋的慘劇。這就像是餐廳的出菜系統，以前服務生每隔一分鐘才慢吞吞地進廚房看菜好了沒，現在廚房一出菜就會按鈴，服務生馬上把菜端走，而且大家端菜時絕不會再撞在一起把盤子摔碎了。
The numbers on your menu bar will now update instantaneously. Previously, the system relied on a dumb timer that polled your usage once a minute, often lagging far behind reality. Now, it directly listens to your operating system's file events (FSEvents), so the moment you burn through some quota, the on-screen numbers twitch in milliseconds. Not only is it faster, but reading data behind the scenes is much lighter too: it now incrementally parses only the history files that have actually changed, saving your hard drive from redundantly reading identical old files over and over. Additionally, if you run multiple Claude Code sessions in different terminal windows, the system now uses file locks to make them line up politely when saving data, completely preventing them from clobbering each other's usage totals. It's like a restaurant's kitchen flow: waiters used to slowly poke their heads into the kitchen every minute to check for food, but now the kitchen rings a bell the millisecond a dish is ready — and the waiters no longer crash into each other dropping plates on their way out.
**`usage_cli.py` crashed on every first run** (thanks @will30-blockchain — [#7](https://github.com/aqua5230/usage/pull/7)): `setup(auto=True)` passed a non-existent keyword argument to `setup_hook.setup()`, causing a `TypeError` on any fresh install or after `unsetup`. Users who already had the hook installed were unaffected. Fix: drop the stale `auto=True` kwarg.
**Incremental JSONL parsing**: `history_loader` and `codex_loader` now maintain module-level mtime+size caches and skip re-parsing files whose content hasn't changed, significantly reducing per-refresh disk I/O.
**Parallel hook forwarding**: `usage_statusline_forwarder` now dispatches all hooks concurrently via `ThreadPoolExecutor`; a single slow or timing-out hook no longer stalls the others. Worst-case latency drops from `n × 5s` to `5s`.
**Multi-session write protection**: `usage_statusline.py`'s `save()` now acquires `fcntl.LOCK_EX` before writing, preventing concurrent Claude Code sessions from clobbering each other's data.
**Python path resolution**: `setup_hook` now uses `_find_system_python()` when building hook commands — preferring the bundled `.app` Python, then `/usr/bin/python3`, avoiding the broken Xcode stub that `shutil.which("python3")` can resolve to after an Xcode update.
**FSEvents-driven UI refresh**: `menubar` now uses a CoreServices `FSEventStream` (via ctypes) to watch `~/.claude/`. Changes to `usage-status.json` trigger `_refresh()` immediately, cutting update latency from up to 60 seconds to milliseconds. `NSTimer` is demoted to a 300-second fallback; silently degrades to timer-only mode if CoreServices is unavailable.