Release notes

PERF

Lightning-fast menu bar updates with drastically reduced disk work

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.

Original changelog

Original changelogLightning-fast menu bar updates with drastically reduced disk work
**`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.