merly

Merly

A native macOS menu bar app that tracks how much of your AI coding agent quota you've burned — across Claude (multiple accounts), Codex, Kimi, and any future provider you point at a config folder.

Each provider gets a cute 8-bit pixel critter whose mood tracks your usage: CHILL → OK → BUSY → FRIED. They idle-bob, blink, and hop when you poke them.

Unofficial project. Merly is a third-party tool and is not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, or Moonshot AI. "Claude", "Codex", "Kimi", and related names and mascots are trademarks of their respective owners, used here only to identify the services whose usage Merly displays. Merly only reads usage data these tools already store on your Mac — see Privacy & security.

Demo

https://github.com/user-attachments/assets/4faece85-b8f7-4ae7-88ff-edef795120a4

What it looks like

• Menu bar: the busiest provider's mascot + its session percentage. Click to reveal.
• Dock panel: a frosted-glass column that slides in from the right screen edge. One card per provider: session ring (58% used · resets in 57m), mood tag, and a tap-to-expand section with weekly bars and the source folder.
• Rail: click anywhere outside the panel and it collapses to a slim strip of peeking mascots with their gauges; click the strip to bring the panel back. The chevron handle dismisses it outright.
• Follows the system light/dark appearance. It's a menu bar app — there's no Dock icon; look up top.

Install

Merly is distributed as source you build yourself. There are no prebuilt downloads — see why below.

Requires macOS 14 (Sonoma) or newer and a Swift 5.9+ toolchain (Xcode 15+, or just the Command Line Tools: xcode-select --install). No other dependencies.

git clone https://github.com/mickyngub/merly.git
cd merly
scripts/install.sh

install.sh checks your macOS and Swift versions, builds (~40s), quits any running copy, installs to /Applications, and launches. Re-run it any time to reinstall; scripts/install.sh --update pulls first. To do it by hand instead: scripts/bundle.sh, then cp -R build/Merly.app /Applications/.

That's it — no Gatekeeper warning, because an app you compiled locally is never quarantined. Merly is a menu bar app with no Dock icon, so look up top.

Using an AI coding agent? This repo ships an install-merly agent skill. Install it into Claude Code, Codex, or any agent the skills CLI supports:

npx skills add mickyngub/merly

Then just ask your agent to install, update, or troubleshoot Merly — it'll know the flags, config paths, and the usual failure modes.

On first launch it asks for Keychain access to read the Claude Code credentials — click Always Allow.

Expect that Keychain prompt again after you rebuild. macOS ties the grant to the app's exact code signature, and a locally built app is ad-hoc signed — every build is a new identity, so the prompt returns after scripts/install.sh --update. It's the cost of unsigned local builds, not a sign anything is wrong — docs/specs/distribution.md has a self-signed-certificate fix if it bothers you.

Why no download

A signed, notarized app needs an Apple Developer Program membership ($99/yr). Without one, any DMG would land quarantined and every user would have to click past "macOS cannot verify this app is free of malware" — for a tool that reads your credential tokens, that is exactly the wrong thing to train people to do. Building from source is both friction-free and the honest option: you can read what you're running. If that changes, this section changes with it.

Development

swift build
.build/debug/Merly --print     # headless snapshot of all readers (no UI)
.build/debug/Merly --open      # run with the panel open
.build/debug/Merly --mascot    # jump to the mascot editor

See CONTRIBUTING.md for the dev loop and docs/specs/distribution.md for how the app bundle is assembled and signed.

Where the numbers come from

All providers show real, provider-reported rate limits — the same numbers as Claude's /usage screen, Codex Analytics, and the Kimi Console:

Merly never sends tokens anywhere except the provider's own API.

Fallback: if an API is unreachable or a login is stale, the card falls back to local analysis (Codex: last rate_limits event in rollout files; Claude/Kimi: token counts from transcripts relative to your busiest period) and marks the ring with ≈. Pin sessionTokenLimit / weeklyTokenLimit in the config to make fallback bars absolute.

Usage details

Expand a provider card and choose Usage details. Activity shows local session totals, model and subagent token shares, uncached input, output, cache reads/writes, and recorded active time where available. Choose a recent session or the last 24 hours, 7 days, or 30 days. Stats load on demand without delaying quota refreshes; prompts and responses are never copied into a stats database.

API value estimates tokens at standard base rates from Claude pricing and OpenAI pricing, verified September 27, 2026. It is not a subscription bill or a reconstruction of historical charges, discounts, or premium tiers. Unknown models, including unverified Kimi aliases, remain unpriced; partial estimates are labeled. Contributor percentages describe recorded tokens, not exact quota attribution. Line changes and cloud credits are not exposed by the connected readers.

History charts provider-reported quota over 24 hours, 7 days, or 30 days, separately for each account and limit window. Collection begins while Merly is running, excludes stale readings and offline estimates, and keeps the latest reading in each five-minute interval for 30 days in ~/Library/Application Support/Merly/usage-history.json. Charts break at resets and long gaps. Session analytics can read existing local logs; quota history is not backfilled.

Adding a provider

Click Add a provider in the panel (or edit ~/Library/Application Support/Merly/providers.json):

{
  "id": "claude-client",
  "name": "Claude",
  "account": "Client X",
  "kind": "claude",
  "dir": "~/.claude-clientx",
  "style": "cat",
  "palette": "gold"
}

• kind: claude | codex | kimi — picks the reader (any Claude-Code-compatible CLI works with claude).
• style: cat, catTie, robot, round — the critter's silhouette.
• palette: coral, steel, green, purple, gold, pink.

By default, Merly refreshes every 5 minutes in the rail or while hidden, and every 2 minutes with the panel expanded. Opening the panel immediately requests a refresh while respecting provider cooldowns. refreshSeconds customizes the expanded interval; background polling never runs faster than every 5 minutes. Config changes take effect on the next refresh. For a genuinely new backend, see docs/provider-integration.md.

Privacy & security

Merly is a read-only usage viewer with no telemetry. It reads tokens that your existing CLIs already store locally, uses each for a single request to that provider's official API, and discards it — nothing is logged or sent anywhere else. It never refreshes Claude/Codex tokens; the one credential file it writes is Kimi's own (required by the CLI's rotation protocol). Full details and vulnerability reporting: SECURITY.md.

Contributing

Contributions welcome — see CONTRIBUTING.md and the Code of Conduct.

Support

Merly is free, MIT-licensed, and has no telemetry or paid tier — it's a weekend tool that got out of hand. If it saves you from one more /usage check, there are two ways to say thanks — both entirely optional; the app never asks.

• GitHub Sponsors — recurring or one-off, billed with your GitHub account.
• Buy Me a Coffee — a one-off tip, no account needed.

License

MIT © 2026 Pichaya Puttekulangkura.

Notes

• First launch scans recent history once (~20s in the background); afterwards refreshes are incremental and take milliseconds. The parse cache lives at ~/Library/Application Support/Merly/usage-cache.json and is safe to delete.
• Right-click the menu bar item for Refresh / Edit Providers / Quit.