Altero

Altero for Claude Code. Keep several Claude Code accounts on one machine and switch between them without logging out. Altero watches every account's usage and switches for you before the active one hits its limit.

Not affiliated with Anthropic.

• Switch accounts from the CLI, a terminal dashboard (TUI), the macOS menu bar or a macOS widget.
• Auto-switch before the 5-hour or 7-day window runs out, onto the account with the most quota left.
• Run two accounts side by side, one per terminal (session mode).
• Works with the Claude Code CLI and the VS Code extension.

Platform support

On macOS the auto-switch engine runs as a per-user LaunchAgent that the TUI and menu bar start on their own and that stops once no surface or widget is open. On Windows and Linux there is no system service. The engine runs only while altero auto or the TUI is open in a terminal. altero menubar and altero service refuse to run off macOS. For unattended use there, run altero auto --once from cron or a systemd timer.

Install

macOS: Altero.app

One app with everything: the CLI, the TUI, the menu bar, the background engine and the widget. Apple silicon, macOS 14 or later.

1. Download Altero-<version>.dmg from Releases.
2. Open it and drag Altero into Applications.
3. Open Altero from Applications. The menu bar icon appears, and macOS notes that Altero added background items (the menu bar and the auto-switch engine, which start at login).
4. For the altero command in a terminal, choose Install Command Line Tool… from the menu bar. It links ~/.local/bin/altero to the app; if another altero (a uv or pip install) is already there, it is left alone and the menu shows the alternative.
5. For the widget: right-click the desktop, Edit Widgets, and look for Altero.

Altero refuses to start from the disk image or the Downloads folder, because its login services would point at a path that is gone at the next login. Move it to Applications first.

To upgrade, quit Altero from its menu bar, replace the app in Applications with the new one, and open it again. A Homebrew cask is coming.

If you also have a uv or pip install, the app's engine owns the background services and the other altero uses them instead of replacing them. altero config unset service.program hands them back until the app is opened again.

CLI with uv or pipx (macOS, Windows, Linux)

Install with uv (Python 3.12+):

uv tool install altero
# macOS, with the menu bar:
uv tool install 'altero[menubar]'

pipx install altero works the same way. altero upgrade upgrades a uv or pipx install.

From GitHub, for an unreleased commit:

uv tool install 'git+https://github.com/FullContextLabs/Altero'

From source:

git clone https://github.com/FullContextLabs/Altero.git
cd Altero
uv sync --all-extras
uv run altero help

To build the widget from source, see widget/README.md. To build Altero.app, see RELEASING.md.

Quick start

# Log in to Claude Code with your first account, then:
altero add
# Log in with the next account (no /logout first; it can revoke the stored token), then:
altero add

altero list              # every account's 5h / 7d usage and reset times
altero switch            # rotate to the next account
altero switch 2          # or a specific one: number, email or alias
altero                   # the TUI dashboard
altero auto              # auto-switch in the foreground
altero menubar           # macOS: menu bar app, starts at login
altero run 2             # run Claude Code as account 2 in this terminal only

Usually no restart is needed after a switch. On Linux and Windows, Claude Code re-reads the credentials file on its next message. On macOS the Keychain value is cached for about 30 seconds. Restart Claude Code, or reopen the VS Code tab, to apply a switch immediately.

altero help lists every command. altero config shows and changes settings.

How auto-switch works

• The engine polls usage for your accounts. When the active account's 5-hour or 7-day window reaches the threshold (default 90%), it switches to the account with the most quota left. --model Fable also counts that model's weekly limit.
• A cooldown (default 5 minutes) and a hysteresis margin stop it flip-flopping near the threshold. A manual switch from any surface starts the same cooldown.
• A switch holds Claude Code's own credential locks, so it never collides with a token refresh, and is safe while Claude Code is working.
• Polling is adaptive and paced per account. Opening more dashboards does not fetch more often.
• It fails safe. On a failed usage check it keeps the last known numbers. An account whose refresh token has died is quarantined until you re-add it.
• altero disable N holds an account out of rotation. --strategy consume-first spends the account whose weekly window resets soonest first.
• It is on by default. Turn it off with altero config set autoswitch.enabled false, and the engine keeps polling and reporting without switching.

altero auto --threshold 80     # switch earlier
altero auto --once --json      # one check, for cron/systemd; exit code 0 switched, 2 nothing to do
altero service status          # macOS: is the background engine running
altero service logs -f         # macOS: follow its events

Data

altero purge removes Altero's data and stored credentials. It does not touch your Claude Code login.

Documentation

• ARCHITECTURE.md: the backend, the surfaces and the snapshot contract
• TESTING.md: the test runbook
• widget/README.md: building and installing the widget
• RELEASING.md: building, signing and notarizing Altero.app
• SECURITY.md: reporting a vulnerability
• CHANGELOG.md

License

MIT. See LICENSE.

Altero is not affiliated with, endorsed by or sponsored by Anthropic. Claude and Claude Code are trademarks of Anthropic.