Home

OpenSwap user guide

How to use OpenSwap: switch Claude Code and Codex CLI accounts, read usage, auto-rotate, and run the menu bar app and widget.

This wiki is the user guide for OpenSwap, an OpenSoft app for macOS. It is a standalone MIT descendant of claude-swap. One signed and notarized app holds the menu bar extra, the Desktop widget, and the openswap command.

What changed in each release: CHANGELOG. Hacking on the code (layout, tests, signing) lives in docs/ in the repo, not here.

Start here

I want to…	Go to
See every feature	Features
Install and save my first accounts	Getting started
Switch, alias, disable, or remove accounts	Accounts
Fall back to an API key when my subscriptions run out	Accounts
Rotate before I hit a rate limit	Auto-switch
Use the menu bar app	Menu bar
Run Claude Code or Codex tasks on this Mac from Slack	Remote tasks
Switch ChatGPT desktop (experimental)	ChatGPT
Put usage on the Desktop	Desktop widget
Open idle 5-hour windows on a schedule	5-hour kickoff
Show the account name in Claude Code	Status line
Change threshold, strategy, theme	Configuration
Move accounts between machines	Backup
Fix a stuck extra, token, or widget	Troubleshooting
Look up a command	CLI reference

How the pieces fit

Claude Code  ←  default login (~/.claude)
                 │
                 ├── openswap switch / auto     change the default login
                 ├── menu bar extra             popover + notifications + auto
                 └── Desktop widget             reads a snapshot the extra writes

Codex CLI    ←  live auth.json (~/.codex)
                 │
                 ├── openswap codex switch / auto
                 └── extra Codex tab            same accounts and usage

Claude and Codex are separate rotations: they never pool. ChatGPT desktop switching is experimental and off until you turn on Enable ChatGPT switching; the second tab is then called ChatGPT. You confirm, then ChatGPT quits and relaunches. It does not prove which profile ChatGPT loaded. ChatGPT.

Usage numbers come from each provider’s 5-hour session window and 7-day weekly window (plus per-model weekly limits such as Fable, when present). Auto-switch and the extra share the same autoswitch.* settings.

Install (short)

brew install --cask mar3co/openswap/openswap

Then open OpenSwap from Applications and follow the setup window. No Homebrew? Download the DMG from the latest release. Details, updates and uninstalling: Getting started. OpenSwap needs macOS 14 or later.