Menu Bar

Menu bar (macOS)

The extra is a small title in the macOS menu bar. Click it for a popover with usage bars. It can run the same auto-switch engine as openswap auto, show notifications, fire the 5-hour kickoff, and connect Remote tasks.

Keep it running

OpenSwap is the menu bar extra: opening OpenSwap.app starts it, and it has no Dock icon. The setup window’s Open at login step (or openswap setup) starts it at every login. Change that later in Settings › General › This Mac › Open at login. If macOS refuses to start it at login, a warning appears under the switch with Open Login Items.

Opening the app again while it runs just opens the popover. More… › Quit stops it until you open it again or log in.

From a terminal:

openswap setup                       # save the current login, start the extra now and at every login
openswap menubar --install-service   # start at login without saving an account
openswap menubar --service-status
openswap menubar --uninstall-service

openswap menubar without --install-service runs in the foreground and dies with that terminal.

The login item is ~/Library/LaunchAgents/com.opensoft.openswap.menubar.plist. Logs:

• ~/Library/Logs/com.opensoft.openswap.menubar.log
• ~/Library/Logs/com.opensoft.openswap.menubar.err

brew upgrade --cask openswap restarts it on the new version. To restart it by hand:

launchctl kickstart -k "gui/$(id -u)/com.opensoft.openswap.menubar"

Popover

Click the extra. The Claude tab and the second tab filter the cards. The second tab is Codex until you turn on ChatGPT desktop switching, then ChatGPT (ChatGPT). Each card shows 5-hour, 7-day, and per-model (Fable, …) rows: bar, percent, time until reset. The title is the alias, or the org name (personal when there is no org). The email is the subtitle, so two orgs that share an address stay distinct. Bars on the second tab are Codex usage, not ChatGPT message limits.

• Click a Claude card to switch. It asks Switch to X? first (turn that off in Settings if you prefer one click). A real switch shows a notification, plays a short swap animation on the menu bar mark, and closes the popover. Clicking the account you are already on just closes it. The restart-Claude-Code sentence appears only when Claude Code (or an IDE lock) is actually running.
• Click a Codex card to switch Codex CLI, the same way. On the ChatGPT tab a click instead starts the experimental desktop switch.
• Each card’s ··· button has Rename…, Disable / Enable, and Remove…. A name shows in the title when Account name is on and works anywhere a number or email does.
• Add account at the bottom of the Claude page runs Sign in with Claude in your browser and saves whoever signs in. On the Codex tab it is Sign in with ChatGPT. See Accounts.
• If a Claude card says Signed out, that account’s token is dead. Last-known usage bars may still show. Clicking it does not switch to the dead backup. If Claude Code is already that account (same email and org), the extra saves the new login. Otherwise it runs the Claude sign-in in your browser with that email filled in, asking first if that would sign another saved account out. Once you sign in, the card is fixed.
• An API key card shows API key (no quota) instead of usage bars. A key linked as API credit is titled API credit, and a key that stopped working says API key revoked or invalid, API key out of credit or API key at its spend limit.
• Auto-switch is the switch at the bottom right. On Claude it runs live rotation. On the Codex tab it rotates Codex CLI. On the ChatGPT tab it only suggests a replacement (Review switch); you still confirm before ChatGPT restarts. Consume-first / soonest-5h show a one-line hold reason under the header (why it is staying, or which account it would pick).
• Rotate and Best sit at the bottom left of the Claude tab. Settings (gear) opens a page in the same box. More (…) holds Add account, Refresh current credentials, Switch history, Refresh now, Uninstall, and Quit. Neither dismisses the popover.
• The popover stays while you are looking at it (pointer on the extra or the box). After the pointer leaves, it closes in about 12 seconds. A click outside closes it immediately.

If Auto-switch is on, picking a Claude card starts the usual 5-minute cooldown so the engine does not immediately switch you back (especially on consume-first). An account that is actually at its limit can still be moved off. See Auto-switch.

The popover follows System Settings → Appearance (Light, Dark, or Auto). It does not follow the menu bar’s wallpaper tint.

Settings

Settings has three sections: General, Automation and Remote.

General

The menu bar title:

Setting	Default	Effect
Show	Claude	Claude, ChatGPT, Both, or Logo only. Independent of the open popover tab.
Account name	on	Alias, org name, or email local-part
5-hour usage	on	Session window percent. Off = no 5h figure.
7-day usage	on	Weekly window percent. Off = no 7d figure.
Claude model limits	off	e.g. Fable 10%. Only shown when Claude is included.
Confirm before switching	on	Ask before a card click swaps the live login
Refresh interval	60s (service often 5 min)	How often usage is fetched

The OpenSoft mark is always in the extra. Logo only hides the account text without clearing those preferences. There is no asterisk setting.

This Mac does what setup does from a terminal:

• Open at login: the login item above.
• Claude Code status line: the status line on or off.
• The widget hint: Edit Widgets, search OpenSwap.

Setup assistant opens the setup window again.

Automation

• Auto-switch Claude accounts: run the Claude engine in the extra (no extra openswap auto terminal).
• Enable ChatGPT switching: allow experimental ChatGPT desktop restarts (off by default). The second tab becomes ChatGPT. See ChatGPT.
• Suggest ChatGPT account switches: pick a replacement from Codex quota; you still confirm every restart. Disabled until switching is on. Cannot run with live Codex CLI rotation.
• Auto-switch Codex CLI accounts: autoswitch.codexEnabled (default on). Shown when Claude auto-switch is on.
• Switch at and Choose the next account by: shared policy, only while Claude auto-switch or ChatGPT suggestions are on. Threshold is 80 / 90 / 95 / 98%. Strategy is Most quota left (best), Burn weekly first (consume-first), or Burn 5-hour first (soonest-5h).
• Start available 5-hour windows: kickoff. Only accounts that report a 5-hour limit are pinged.

Policy lives in settings.json (openswap config) and is shared with the CLI. The on/off toggles, title, and kickoff live in menubar_settings.json. See Auto-switch and Configuration.

Remote

Connect to OpenTag…, Set up Remote tasks… and Enable local worker. On a paired Mac whose key has expired, Reconnect. See Remote tasks.

Notifications

Switches, quarantines, all-accounts-exhausted, and kickoff results show as macOS notifications. Clicking the extra still opens the popover, not a menu. After an experimental ChatGPT restart, a silent ChatGPT reopened notification asks you to check the profile.

Uninstall

More… › Uninstall OpenSwap… lists what goes and asks first. Tick Also delete saved accounts, settings and logs to remove your saved accounts too. OpenSwap quits and finishes in the background, logging to ~/Library/Logs/com.opensoft.openswap.uninstall.log (opened if a step fails). See Getting started.

Place it next to Claude’s extra

macOS has no API to pin an extra next to another app. Cmd-drag the extra where you want it. The position is remembered.

Dark Mode

The popover and the widget follow System Settings → Appearance. If the extra looks light while the rest of the Mac is Dark, restart it (launchctl kickstart above) so it picks up the change.