Skip to content

Getting Started

Jump to bottom
Yohan Marshall edited this page Oct 17, 2026 · 13 revisions

Getting started

Requirements

  • macOS 14 or later (OpenSwap ships for the Mac only)
  • For Claude accounts: Claude Code installed
  • For Codex / ChatGPT accounts: Codex CLI, or the Codex tab’s browser sign-in

Install

With Homebrew:

brew install --cask mar3co/openswap/openswap

That installs OpenSwap.app: one signed and notarized app with the menu bar extra, the Desktop widget, and the openswap command. OpenSwap is not on PyPI.

No Homebrew? Download the DMG for your Mac from the latest release (arm64 for Apple silicon, x86_64 for Intel), open it, and open OpenSwap. It offers to move itself to Applications. It is the same app, with two differences:

  • There is no openswap command on your PATH. Link it yourself if you want it, for example ln -s /Applications/OpenSwap.app/Contents/MacOS/OpenSwap ~/.local/bin/openswap when ~/.local/bin is on your PATH.
  • Updates come from the releases page, not Homebrew.

Finish setting up

Open OpenSwap from Applications. A setup window walks you through it:

  1. Claude: Sign in with Claude, or Save Current Login to keep the account Claude Code is already using.
  2. Codex: the same for Codex, if you use it.
  3. Open at login: leave it on so OpenSwap is in your menu bar after every restart.
  4. Extras: the optional Claude Code status line, and how to add the widget.
  5. Open OpenSwap.

Closing the window changes nothing; it opens again next time until you finish. Settings › General › Setup assistant opens it again later.

From a terminal, openswap setup does the same: it saves the Claude account you are logged into and starts OpenSwap now and at every login.

Update

brew upgrade --cask openswap

openswap upgrade prints that command. A DMG install updates by downloading the new DMG and opening it: OpenSwap offers to replace the older copy.

Install from source

curl -fsSL https://raw.githubusercontent.com/mar3co/openswap/main/install.sh | bash

On a Mac with Homebrew this installs (or upgrades) the cask above. Without Homebrew it installs uv if needed, clones OpenSwap to ~/.openswap, and runs setup. On a brand-new Mac, macOS first asks to install its Command Line Tools; run the command again once that finishes. A source install updates with openswap upgrade (or by running the command again), and building the widget needs Xcode.

Moving from a source install to the cask: install the cask, then run $(brew --prefix)/bin/openswap setup. It moves the login item, Remote tasks and the status line over to the app. Then run uv tool uninstall openswap; ~/.openswap is yours to delete. Widgets you placed before may need adding again.

Uninstall

Choose More… › Uninstall OpenSwap… in the menu bar, or:

openswap uninstall          # or: brew uninstall --cask openswap
openswap uninstall --zap    # also delete saved accounts, settings and logs

Your saved accounts stay unless you zap. In the menu bar, Also delete saved accounts, settings and logs is the zap. brew upgrade and brew reinstall keep everything. Claude Code itself stays logged in either way.

Save your accounts

If Claude Code was logged in, setup already saved that account. To add another, click Add account on the extra’s Claude page (Sign in with Claude when it has no accounts yet) and sign in through your browser. Claude Code ends up on the new account.

From a terminal:

  1. Log into Claude Code with the next account (claude auth login). Do not run /logout first: current Claude Code may revoke the refresh token you still need.
  2. Run openswap add.
  3. Repeat for each account.

Give a slot a short name if you want:

openswap add --alias work
openswap alias 2 personal

Codex / ChatGPT accounts are a second roster:

openswap codex add

Or in the extra: the Codex tab’s Add account / Sign in with ChatGPT. See ChatGPT.

Have a Claude Console API key with bought credit? Link it as a last resort for when every subscription is out: API credit fallback.

Check what you have:

openswap list
openswap status
openswap codex list

openswap list is the dashboard: 5-hour and 7-day usage and reset times for every Claude slot.

Switch

openswap switch                 # next account
openswap switch 2               # slot number
openswap switch user@example.com
openswap switch work            # alias
openswap switch --strategy best # most quota left
openswap codex switch 2

Or click a card in the extra. You usually do not need to restart Claude Code. macOS Keychain is cached for about 30 seconds; restart Claude Code (or the VS Code extension tab) only if you want the new account instantly. ChatGPT desktop switching stays off until you enable it, then it is a confirmed restart: ChatGPT.

Auto-rotate

Turn it on from the extra: Settings → Automation → Auto-switch Claude accounts. Or from a terminal:

openswap auto

When the active account’s 5-hour or 7-day window reaches 90%, OpenSwap moves you to the account with the most quota left. See Auto-switch.

Next

mar3co/openswap · MIT · OpenSoft · descendant of claude-swap

Using OpenSwap

macOS

Reference

Clone this wiki locally