How-to guide · Multi-provider routing on macOS
How to switch between Claude Code, Codex and Gemini CLI before hitting a rate limit
Facts first: Most Mac developers who use more than one AI coding assistant pay for overlapping limits—Claude Pro or Max (5-hour + 7-day windows), ChatGPT Plus or Pro for Codex CLI (5-hour + weekly windows), Google’s Gemini plans (their quota now shows in the Antigravity CLI), and local Ollama models. Hitting a rate limit mid-refactor leaves a half-finished branch unless you check which plan has headroom before starting the run.
Free · Signed and notarized by Apple · macOS 14 or later, Apple silicon or Intel
Why checking each CLI by hand misses the window
Without a unified meter, checking which subscription has room means opening three terminals and translating three different formats:
Claude Code (/usage)
Shows your 5-hour session percentage and 7-day weekly percentage, but only inside an active Claude Code prompt—and does not compute whether your current burn rate will empty the weekly window before reset.
Codex CLI (/status)
Shows your 5-hour and weekly rate-limit windows inside an interactive Codex session or the latest rate_limits event in ~/.codex/sessions/.
Gemini CLI (/stats) & Ollama
Gemini CLI prints per-session request and token counts via /stats; local Ollama tokens are in the log your Ollama server writes (usually ~/.ollama/logs/server.log).
3 ways to check which plan has room on your Mac
1. Glance at the macOS menu bar before starting a task
Usage HUD sits in your Mac menu bar and summarizes all configured lanes in one verdict line—for example, Claude: running hot · Codex has room (12% used). Opening the popover shows each plan’s percentage, reset countdown, confidence label (official, measured, estimated, or unknown), and a pace badge:
GO: You have used less of the window than the time elapsed since the last reset.WATCH: You are burning through the window faster than the reset clock and will run out early if you keep this pace.STOP: The window is near or at its cap; switch to another provider or a local Ollama model until the reset bell fires.
2. Check from Terminal or shell scripts (room and status)
The Usage HUD app bundle includes a read-only command-line interface that works even when the menu-bar window is closed:
# Print one sentence naming the plan with the most room (exits 0 if room, 1 if none)
'/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' room
# Print all plans with percentages, reset times, and GO / WATCH / STOP pace verdicts
'/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' status
# Machine-readable JSON for wrapper scripts
'/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' room --json3. Let your coding agents check automatically via MCP
Usage HUD includes a built-in, read-only Model Context Protocol (MCP) server over stdio with five tools: which_plan_has_room, usage_status, lane_detail, spend_summary, and recent_activity. Connect all of your installed agent CLIs at once:
# Print the setup prompt and paste it into Claude Code, Codex, Gemini CLI or Cursor
'/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' prompt
# Or register the MCP server directly in Claude Code, Codex, and Gemini CLI
claude mcp add --scope user usage-hud -- '/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' mcp
codex mcp add usage-hud -- '/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' mcp
gemini mcp add --scope user usage-hud '/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' mcpOnce connected, an agent can call which_plan_has_room before spawning subagents or starting a multi-file refactor, and warn you when the plan it is running on enters WATCH or STOP. See the full Usage HUD for agents reference.
Fair comparison: ways to check multi-provider headroom on a Mac
| Feature | Built-in CLI commands | Usage HUD | CodexBar | ccusage |
|---|---|---|---|---|
| Price | Free | Free (optional tip) | Free (open source) | Free (open source CLI) |
| Providers in one view | 1 per CLI (/usage, /status, /stats) | Claude, Codex, Gemini, Grok, local Ollama | Claude, Codex, Gemini, Cursor, Copilot & more | Claude Code & Codex JSONL logs |
Pace verdict (GO / WATCH / STOP) | No | Yes (compares % used vs. time until reset) | No (shows raw meters) | No |
| Built-in MCP server for agents | No | Yes (which_plan_has_room + 4 tools) | No | No |
Shell exit-code check (room) | No | Yes (exits 0 when a plan has room) | CLI status output | CLI tables / JSON |
| Requirements | Each CLI installed | macOS 14 or later, Apple silicon or Intel | macOS | Node.js 18+ |
Install Usage HUD
curl -fsSL https://hud.thaliabloom.com/install.sh | shOr download the notarized .dmg and drag Usage HUD to Applications.
- Your Mac: macOS 14 or later, Apple silicon or Intel.
- Claude and Codex: Claude Code or Codex signed in. Nothing else to install for those two lanes.
- Gemini and Grok: those lanes need Node.js 18 or later. Gemini reads Google’s Antigravity CLI (agy), so sign in there.
- Local models: the local lane reads your Ollama logs.
Frequently asked questions
Can Usage HUD switch my active coding session automatically?
Usage HUD is strictly read-only: it never intercepts your network traffic, rewrites your prompts, or changes your billing configuration. Instead, it gives you (and your agents, via the which_plan_has_room MCP tool or room CLI command) a clear verdict so you can start the next task in the CLI that has room.
Does the MCP server require an API key or send usage data over the network?
No. The MCP server runs locally inside the Usage HUD app binary over stdio, reads the snapshot files already on your Mac, needs no API keys, and sends nothing over the network. Nothing leaves your Mac unless you turn on the optional public badge.
What if a provider’s usage reading is rate-limited or old?
Usage HUD labels every reading with its age and confidence (official, measured, estimated, or unknown). If a reading is stale or unknown, which_plan_has_room withholds pace advice for that provider rather than treating missing data as 0% used.
