A tiny, fast LLM quota display for the macOS menu bar. Providers publish to it; it never calls them. https://vibewait.ing/eaSpot/
  • Swift 98.3%
  • Shell 1.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-24 14:58:56 +10:30
Resources/AppIcon.icon feat: add app icon, signed release pipeline and MIT license 2026-09-25 15:40:57 +09:30
scripts chore: bump version to 0.6.2 2026-10-24 14:58:56 +10:30
Sources fix: probe a login under either spelling of its folder variable and keep the one signed in 2026-10-24 14:58:56 +10:30
Tests/EaSpotKitTests fix: probe a login under either spelling of its folder variable and keep the one signed in 2026-10-24 14:58:56 +10:30
.gitignore feat: add app icon, signed release pipeline and MIT license 2026-09-25 15:40:57 +09:30
.swiftlint.yml feat(app): add eaSpot menu bar app and drop the statusline writer 2026-09-25 14:59:39 +09:30
LICENSE feat: add app icon, signed release pipeline and MIT license 2026-09-25 15:40:57 +09:30
Package.swift feat(app): add eaSpot menu bar app and drop the statusline writer 2026-09-25 14:59:39 +09:30
README.md fix: probe a login under either spelling of its folder variable and keep the one signed in 2026-10-24 14:58:56 +10:30

eaSpot

A tiny, fast LLM quota display for the macOS menu bar. Website: vibewait.ing/eaSpot · Source: x.vibewait.ing/x/eaSpot

This repository holds:

  • eaSpot.app (Sources/EaSpotApp): the menu bar item and menu. AppKit only for everything that stays resident; the SwiftUI Settings window is created on first use.
  • easpot (Sources/easpot): the writers that turn Claude Code and Codex events into snapshot files.
  • EaSpotKit: the shared data contract, merge rules, and the pace/tone judgements (tested).

The app never talks to a provider. Providers conform to eaSpot's data contract instead: an adapter writes a snapshot, and the app renders whatever snapshots exist.

eaSpot is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. "Claude" and "Codex" are used only to label the limits those tools report.

Requires macOS 14 or later, on Apple silicon or Intel. The layered Liquid Glass icon appears on macOS 26 and later.

Install

  1. Install with Homebrew, which puts eaSpot.app in /Applications and easpot on your PATH:

    brew tap x/tap https://x.vibewait.ing/x/homebrew-tap.git
    brew install --cask x/tap/easpot
    

    Or download eaSpot-<version>.zip from the releases page, unzip it, and move eaSpot.app to /Applications (or ~/Applications). Releases are signed with a Developer ID and notarized.

  2. Open eaSpot. It lives in the menu bar and shows "No usage yet" until a writer reports.

  3. Connect the writers. Print the hook snippets with the CLI that ships inside the app:

    APP=/Applications/eaSpot.app   # or ~/Applications/eaSpot.app, wherever you put it
    "$APP/Contents/Helpers/easpot" print-config
    

    Add the Stop group to hooks in ~/.claude/settings.json, and the Stop and PostToolUse groups to ~/.codex/hooks.json (at the end of each list). In Codex, approve the new hooks with /hooks. Optionally put the CLI on your PATH (any directory on it works):

    mkdir -p ~/.local/bin && ln -sf "$APP/Contents/Helpers/easpot" ~/.local/bin/easpot
    
  4. Use Claude Code or Codex. Numbers appear within seconds (Codex) or a few minutes (Claude).

How data arrives

Where you work Writer Latency Cost
Claude Code (terminal, desktop app, IDE) easpot hook claude-stop starts a detached claude -p "/usage" probe when data is older than 3 min or a window has reset. The probe needs that login signed in to Claude Code's CLI (claude auth status; a desktop-app session alone is not enough). Claude Code keys that sign-in on the exact CLAUDE_CONFIG_DIR value, set or unset, so the probe tries the spelling the hook registered, then the other one naming the same folder, and keeps what got in; errors.log names both when neither did ≤ 3 min + ~3 s hook ~5–8 ms; probe ~2–3 s, 0 model tokens
Codex CLI and desktop app easpot hook codex (Stop / PostToolUse) reads the newest token_count in rollout logs end of each tool call or turn ~12 ms
Codex between turns (such as an early reset) easpot refresh asks codex app-server for the live limits (account/rateLimits/read, which Codex marks experimental) once Codex has reported limits menu open with old data, or Refresh Now ~1–2 s, 0 model tokens
Tokens by model (Settings → Menu, off by default) easpot refresh --models counts new tokens per model since each weekly limit began, from that login's own Claude Code or Codex logs on this Mac, reading only what they gained since the last count menu open with an old count, or Refresh Now first count ~6 s once, then ~0.1 s
Anything else easpot publish with a provider-neutral snapshot on stdin adapter-defined —
Menu open with old or reset data the app runs its bundled easpot refresh all --if-older 120 ~3 s as above

Hooks run outside the model, so none of this uses model tokens.

A second login of the same app (another CLAUDE_CONFIG_DIR or CODEX_HOME) gets its own line in the menu: in that login's own settings.json or hooks.json, give the hook its own source and name, for example easpot hook claude-stop --as claude-personal --name 'Claude Personal'. The hook binds that source to the login it runs for, so the app refreshes each login separately, and a hook without --as from another login is refused (with the fix in state/errors.log) rather than writing over it. --name alone renames the default source. When both logins share one settings file (a symlink, say), export EASPOT_CLAUDE_SOURCE and EASPOT_CLAUDE_NAME (EASPOT_CODEX_SOURCE and EASPOT_CODEX_NAME for Codex) wherever the second login is started instead; set, they win over the hook line. They are per app on purpose: a Codex session started inside a Claude login's shell inherits that shell's variables and must not take the Claude login's source. easpot forget claude-personal drops a source again, with its data; it also removes a snapshot eaSpot's own writers left behind (such as claude after that login moved to its own source), never a published one.

Data contract (schema 1)

Root: ~/.config/easpot (override with EASPOT_HOME). Readers watch sources/ only.

sources/<source>.json   one snapshot per provider, replaced atomically (dot-prefixed temp + rename)
state/                  locks, probe stamps, hook traces (hook-*.last), errors.log — never watched
{
  "schema": 1,
  "source": "claude",
  "plan": null,
  "updated_at": 1790301234.5,
  "windows": [
    {
      "id": "seven_day",
      "label": "Weekly",
      "used_percent": 19,
      "resets_at": 1790791200,
      "resets_at_exact": false,
      "window_minutes": 10080,
      "observed_at": 1790301230.1,
      "via": "usage-probe"
    }
  ]
}

All times are Unix epoch seconds. window_minutes may be null when the length is unknown (for example a spend limit). resets_at is absent for a limit that never resets, such as a prepaid balance. A reader should treat a window whose resets_at has passed as reset, and use observed_at for "updated X ago".

A window may also carry absolute amounts, "used": 12, "limit": 200, "unit": "messages", which the menu shows as "188 of 200 messages left". used_percent is always present and drives the bar and warnings.

Window IDs: Claude five_hour, seven_day, seven_day:<model> (e.g. seven_day:fable), spend_limit; Codex <limit_id>:<window_minutes> (e.g. codex:10080, codex_bengalfox:10080 for Codex-Spark).

Merge rules

Many sessions report at once and some report stale numbers, so every writer merges under a lock:

  • A resets_at more than 30 min away from the stored one is a different window, and whichever reading was observed later wins (on a tie, the later reset). So a new window replaces the old one, a stale reading of a finished window is ignored, and a newer reading that moves the reset earlier sticks.
  • Within a window, a reading at least as new as the stored one replaces it; an older reading can only raise usage (usage never shrinks within a window), but never changes a newer live read (usage-probe, codex-probe), which can see usage fall after an early reset. Unknown via values read as published.
  • Windows missing from a reading are kept. Windows that reset more than 8 days ago are dropped.
  • The file is rewritten only when a value changes or an observation gets ≥ 60 s fresher.

Publishing from any provider

echo '{"source":"glm","plan":"pro","windows":[
  {"id":"five_hour","used_percent":12.5,"resets_at":1790330400,"window_minutes":300}]}' | easpot publish

source must match [a-z0-9][a-z0-9_-]{0,31}. name (how the menu names the source, e.g. "ChatGPT", up to 32 characters; kept until a later publish replaces it), label, window_minutes, observed_at (default now) and plan are optional; resets_at may be epoch seconds or ISO-8601.

Every source has a name this way: a publisher sends name, eaSpot's own hooks take --name, and without either the menu shows the writer's name (Claude, Codex) or the source ID capitalised.

A tool that counts instead of measuring a percentage sends used and limit (and optionally unit, up to 24 characters), and used_percent is worked out from them:

echo '{"source":"chatgpt","name":"ChatGPT","windows":[{"id":"pro_weekly","label":"Pro weekly",
  "used":12,"limit":200,"unit":"messages","resets_at":"2026-10-02T00:00:00Z","window_minutes":10080}]}' | easpot publish

A source can also choose its icon, drawn next to its number in the menu bar, in the menu and in Settings:

"icon": { "symbol": "bubble.left.fill" }
"icon": { "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\"><path d=\"M2 3h12v8H6l-3 3v-3H2z\"/></svg>" }

symbol is an SF Symbol name; svg is a small SVG (up to 16 KB, no scripts or outside references), for example one a model generated. Both are drawn as a one-colour shape so they follow the menu bar's appearance and warning colours; an SVG's own colours are ignored. Like name, the icon is kept until a later publish replaces it. Without one, eaSpot shows the first letter of the name in a rounded square. The Claude and Codex writers publish eaSpot's own drawings echoing each app's icon (a starburst and a cloud with a prompt), so the app itself knows no provider; a snapshot written by an older eaSpot shows the letter until its writer next runs.

A reading is shown as possibly out of date after an hour. A source whose numbers only change when it sends new ones (for example a counter kept by the tool itself) can say how long its readings stay trustworthy with "stale_after": <seconds> (60 seconds to 30 days); like name, it is kept until a later publish replaces it.

"featured": ["seven_day", "seven_day:fable"] suggests which limits (by window ID, up to 8) the menu bar number shows for this source. It is a suggestion: the person's choice in Settings wins, and [] clears a stored one. Like name, it is kept until a later publish replaces it.

"pull": true marks a source whose numbers are fetched only when easpot refresh runs, so opening the menu can refresh it; the Claude probe and the Codex writers set it. It is written by eaSpot's own writers, and easpot publish refuses it because easpot refresh cannot fetch a published source. A writer that omits it keeps the stored value; false clears it.

Leave out resets_at for a limit that never resets; the menu then says "does not reset" and shows no pace. used must be the running total for the window, not an increment.

Usage by model

A source can break its usage down by model, and the menu lists the heaviest three under its limits when "Tokens by model" is on in Settings. The app knows no model: names, period and unit all come from the writer.

"models": {
  "label": "this week",
  "since": 1791313200,
  "unit": "tokens",
  "items": [
    { "id": "gpt-6-astra", "label": "GPT-6 Astra", "used": 4100000 },
    { "id": "gpt-6.1-sol", "used": 1200000 }
  ]
}

Only items is required: up to 32 models with unique IDs (1–64 characters, no /), each used the running total for the period. label names the period after "Tokens by model · " (up to 24 characters), since is when it began (epoch seconds or ISO-8601, not in the future), unit defaults to tokens, and observed_at to now. A count replaces the stored one only when it is newer, and writers that send no models keep it.

eaSpot's own writers count new tokens (input that was not a cache read, plus output) since each weekly limit began: Claude Code transcripts under ~/.claude/projects (subagents included; CLAUDE_CONFIG_DIR too when easpot runs with it) against seven_day, and Codex rollouts against codex:10080. Only easpot refresh --models reads the logs, and only the bytes added since the last count; its place is kept in state/models-<source>.json. A first count is spread over runs of at most EASPOT_MODELS_BUDGET seconds and is shown only once complete. Work in Claude.ai, the Claude desktop chat or Codex cloud tasks is not in these logs and is not counted.

Commands

easpot hook claude-stop [--as <source>] [--name <text>] | hook codex [--as <source>] [--name <text>]
easpot publish < snapshot.json
easpot refresh [claude|codex|all|<source>] [--if-older <seconds>] [--models] [--detach]
easpot forget <source>
easpot status [--json]
easpot print-config

refresh all covers each writer's default source and every source a hook registered, and shares EASPOT_REFRESH_BUDGET among its probes so one that hangs cannot starve the others.

The probe fills in USER/LOGNAME when a hook's environment lacks them, since Claude Code needs them to find its Keychain login.

Environment: EASPOT_HOME, EASPOT_CLAUDE_SOURCE, EASPOT_CLAUDE_NAME, EASPOT_CODEX_SOURCE and EASPOT_CODEX_NAME (hooks only; win over --as and --name), EASPOT_CLAUDE_BIN, EASPOT_CODEX_BIN, EASPOT_CLAUDE_MIN_INTERVAL (default 180), EASPOT_PROBE_TIMEOUT (default 30, for each probe), EASPOT_MODELS_BUDGET (default 10, seconds of counting per source per run), EASPOT_REFRESH_BUDGET (default 80, seconds one refresh all may spend on its probes together), CODEX_HOME, CLAUDE_CONFIG_DIR.

The menu bar app

One symbol and number per service (or only the tightest limit): what's left of the limit that needs attention first, or what's used (Settings). A service with more than one limit can show several at once: tick them under "Menu bar shows" in Settings (up to four; nothing ticked means the tightest, and a publisher may suggest a set with featured). The icon is drawn once, then a number per ticked limit in the menu's order, and the tightest limit that is nearly out is always added beside them. Click for a native menu: each limit as a bar that measures the same thing as its number (29% used fills 29%, drawn exactly), with a mark where even use would be now, plus a line that states the gap, such as "12% under pace · resets Thu 3:30 AM" or "5% over pace · runs out ~Mon 2:50 PM · resets Wed 9:15 AM".

One colour, the same on the menu bar number, the menu number and the bar, says how a limit stands:

Colour Meaning
green more than 6 points under even pace: quota to spare
white (black in light mode) on pace, within 6 points either way; the small gap is still shown, e.g. "On pace · 3% over"
yellow ⚠ more than 6 points ahead of even pace: at this rate it runs out before the reset
red ⚠ 10% or less left, or the limit reached

Red wins over yellow, yellow over green. A limit without a known window length has no mark and stays white until it is nearly out. Light mode uses darker green and amber so small text stays readable.

  • Updates within ~0.1 s of a writer changing sources/ (directory watch, debounced), once a minute for countdowns, exactly at each reset, and after wake. No polling, no network.
  • Opening the menu when any shown limit is older than the Settings value (default 2 min), or has reset, runs the bundled easpot refresh all --if-older <age>. "Refreshing…" lasts until it exits, and a failure is shown with a pointer to state/errors.log.
  • "Tokens by model" (Settings → Menu, off by default) lists each service's three heaviest models this week under its limits, with their share. While it is on, the refresh also gets --models, and a count older than the Settings value is reason enough to refresh, for counting only (~0.1 s): the probes then run only for a limit that has reset. While it is off, no log is read.
  • Warnings use colour plus a triangle and words; light-mode warning text uses darker tones for contrast.
  • Settings opens in front of whatever you were using. For that, eaSpot shows a Dock icon while the window is open (a menu bar app cannot take the foreground otherwise on recent macOS); it goes when the window closes.

eaSpot --snapshot <folder> renders the menu bar item, the menu and Settings (light and dark) from the real data into PNGs, and prints how long building the menu takes.

Build from source

Requires Xcode 26 or later (for actool to compile the Icon Composer icon).

swift test
scripts/bundle.sh             # build/eaSpot.app, ad-hoc signed
scripts/bundle.sh --install   # also replace the installed app (~/Applications by default) and relaunch it

The icon source is Resources/AppIcon.icon; open it in Icon Composer to edit. bundle.sh compiles it into Assets.car (layered icon on macOS 26+) and AppIcon.icns (older macOS).

bundle.sh builds a universal app (Apple silicon and Intel), so its binaries land in the folder swift build -c release --arch arm64 --arch x86_64 --show-bin-path prints, not .build/release.

bundle.sh warns when ~/.local/bin/easpot runs something other than this build. If it is a symlink to the app's helper (as in Install above), --install updates both. If it is a separate copy, the warning prints the install command that refreshes it.

Hooks that go through the symlink fail briefly while --install replaces the app; they recover on the next event.

Releasing

Signed with a Developer ID, notarized and stapled, so Gatekeeper opens it without warnings:

xcrun notarytool store-credentials <profile> --team-id <TEAMID>   # once; prompts for credentials
EASPOT_SIGN_IDENTITY="Developer ID Application: <Name> (<TEAMID>)" \
EASPOT_NOTARY_PROFILE=<profile> scripts/release.sh                # dist/eaSpot-<version>.zip + SHA-256

Both the app and its helper are signed inside-out with the hardened runtime and a secure timestamp.

Then tag the release and attach the zip and its SHA-256 to a release at x.vibewait.ing/x/eaSpot/releases.

License

MIT. See LICENSE.