Use several Claude Code, Codex and other coding-agent accounts side by side. Switch in one command, or run a single session on another account without touching your default login, and see every account's remaining usage at a glance.
brew install open330/tap/aas- Isolated sessions:
aas exec workruns the agent under another account for one session and leaves your default login as it was. - Instant switching: each account's credential lives in its own
0600file / OS keychain entry, andaas switchmakes it the active login. - Usage at a glance:
aas usagefetches every account's quota in parallel through a shared success cache; use--freshfor an explicit live request. - Cross-provider execution: run one agent's UI against another provider's backend (aas proxy).
- One static binary, no dependencies. Supports Claude Code, Codex, Grok/xAI, Z.AI, Kimi/Moonshot, Cursor and Pi.
- Coming from
asx? aas moves its state directory (…/asx→…/aas) on first run, so existing logins appear without re-login. Agents already running keep working;aas migrateshows when the old path can go.
Paste this into your coding agent (Claude Code, Codex, …) to install and set up aas:
Install the aas CLI (Agent Account Switcher) from https://github.com/Open330/aas
1. Install. If Homebrew is available: brew install open330/tap/aas
Otherwise, macOS/Linux (needs the GitHub CLI `gh` to verify the release):
curl -fsSL https://raw.githubusercontent.com/open330/aas/main/install.sh | sh
Windows PowerShell: irm https://raw.githubusercontent.com/open330/aas/main/install.ps1 | iex
2. Verify it works: aas --version
3. Show my accounts and live usage: aas list && aas usage
Homebrew (macOS Apple Silicon/Intel, Linux x86_64/arm64) from the
Open330 tap:
brew install open330/tap/aasmacOS / Linux (the installed aas binary is static; the secure installer also requires the
GitHub CLI to verify release provenance):
curl -fsSL https://raw.githubusercontent.com/open330/aas/main/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/open330/aas/main/install.ps1 | iexThe installers fetch the latest published GitHub Release, verify its SHA-256 checksum and GitHub
build-provenance attestation against this repository's release workflow, then run the downloaded
binary before replacing an existing installation. Constrained/offline hosts may explicitly set
AAS_SKIP_ATTESTATION=1, which gives up publisher authentication and retains checksum-only
integrity verification.
From source:
git clone https://github.com/Open330/aas.git
cd aas
cargo install --path crates/aas-cli --locked # -> ~/.cargo/bin/aas# Add accounts (each stored as its own isolated profile)
aas login claude work
aas login codex personal # opens a browser
aas login codex server --headless # CLI-only box: device-code flow (no browser)
# Pi authenticates in its TUI; snapshot its complete auth.json afterwards
pi # run /login
aas load pi personal
# See what you have, and live quota for every account (parallel fetch)
aas list
aas usage
# Make a stored account the active one (writes the provider's native login)
aas switch codex personal
# Run the native agent under a profile, without changing your default login
aas exec work -- --version
aas exec codex # a provider name auto-picks its best-paced account
aas exec codex --pick active # …or runs its active account
# Cross-provider: run Claude's UI on the codex backend (via the local proxy)
aas exec personal.codex claude
aas exec personal.codex pi -- -p "run Pi on the Codex backend"
# Use a profile in the *current shell* without switching your default
eval "$(aas export personal.codex)" # POSIX (bash/zsh)
aas export zai work # prints: export ZAI_API_KEY="…"
aas export codex work --shell fish | source # fish
aas export codex work --shell powershell | iex # PowerShell
# Move ALL accounts + credentials to another host
aas export --all | ssh other-host aas import - # over ssh — nothing touches disk
aas export --all -o creds.json # …or a file (0600); scp it, then: aas import creds.json
# Password-encrypted vault (age/scrypt); import auto-detects it
aas export --all --vault -o aas-vault.age
scp aas-vault.age jiun-mbp:
scp aas-vault.age jiun-mini:
ssh -t jiun-mbp 'aas import ~/aas-vault.age'
ssh -t jiun-mini 'aas import ~/aas-vault.age'switch vs exec vs export:
switch <name>writes the stored credential to the provider's native location (~/.codex/auth.json, Claude keychain, …) so runningcodex/claudedirectly uses it. A Claude long-lived token is the exception — Claude Code only accepts one throughCLAUDE_CODE_OAUTH_TOKEN, never from its credential store, soswitchcannot materialize it and the bare CLI keeps whatever it was already using. Install shims for that case. (A long-lived token also has inference scope only, sousagereads its quota from the rate-limit headers on a minimal completion request rather than the usage endpoint, which answers 403 for it.)shim installputs a wrapper for each agent CLI in<config>/shims, so a bareclaudeorcodexre-enters throughaas exec <active>and followsswitchfor every credential shape. Prepend the directory it prints toPATH. Because the active account is resolved per invocation, it also cannot drift away from a written-once native file. The executable path is pinned at install time. If multiple copies are installed (for example, standalone and npm Codex), updating another copy does not update the pinned one.aas shim statusshows the pinned path and other installations on PATH. Select a copy explicitly withaas shim install codex --bin "$(npm prefix -g)/bin/codex", or pass another executable path.--binrequires exactly one provider; launcher symlinks are preserved across upgrades.exec <name>runs the agent under a profile-scoped home without touching your default.<name>is a stored account name, or a provider name —aas exec codexruns whateveraas statuslists as active for Codex.export <name>prints the env (CODEX_HOME=…,ZAI_API_KEY=…, …) to activate a profile in the current shell only.
load is different: it snapshots the currently logged-in native credential into a profile
(aas load codex), rather than activating a stored one.
The bundled aas skill teaches agents to discover registered
accounts, inspect quota, and retry unfinished work with an authorized alternate.
From a checkout, install it into your agent's skill directory (for example,
~/.codex/skills/aas/SKILL.md or ~/.claude/skills/aas/SKILL.md). Shared aas profiles
inherit their provider's skills unless skill sharing has been disabled. A Codex profile links each
skill individually and keeps skills/.system (the skills bundled into the Codex binary) to
itself, so Codex builds of different versions never rewrite each other's bundle.
# Rank quota candidates; omit --provider to inspect all providers.
aas candidates --provider codex --exclude primary.codex --json
# Explicit HTTP 429 fallback; repeat --fallback for more accounts.
aas exec primary.codex --fallback backup.codex -- <agent arguments>candidates returns { "schemaVersion": 1, "accounts": [...] }. Entries contain
id, name (the exec argument), provider, active, eligible, reason,
cached, fetchedAtMs, remainingPct, paceScore, usageCooldownUntilMs, and meters.
Eligible entries sort first, then by pace (below) descending, remaining quota descending, the
active account, and ID ascending.
Reasons are quota_available, excluded, usage_rate_limited, usage_error,
usage_unknown, or quota_exhausted. Eligibility is quota evidence, not a model
compatibility or inference-auth guarantee. --fresh bypasses success and failure caches;
usage endpoint cooldowns remain authoritative. Empty results are an empty array.
Naming a provider instead of an account (aas exec codex, aas claude) runs the account that
candidates ranks first. Each usage window gets a pace: the share of quota left divided by the
share of the window left. 1.0 means even spending exhausts it exactly at reset; above 1.0
quota would expire unused, so that account is spent first; below 1.0 it would hit its limit
early. An account scores its tightest window, and any window under 5% left that is not resetting
within 10 minutes sinks it below the rest. So 40% of a week that resets tomorrow (pace 2.8) beats
70% with six days to go (0.82). Windowless meters such as credits score their remaining share.
The choice and its reason go to stderr (aas: → codex/work 7d 40% left · resets 1d 0h · pace 2.80× (3 candidates, cached 2m)), and aas candidates --provider <provider> previews it. Usage
comes from the same 10-minute cache as usage; if it is not available within 4 seconds, or no
account has usable quota, the provider's active account runs instead. A system profile is only
picked while it is the live system credential, and accounts named with --fallback are never
picked as the primary. The active account is never changed.
--pick active (consumed only for provider targets) restores the active-account behavior.
--fallback must precede --; every named account must match the primary's provider
and endpoint. It opts into the local translating proxy, including same-provider
runs, so the proxy's model catalog and protocol support apply. Supported backends
are Claude, Codex, Grok, Z.AI, and Kimi; Z.AI/Kimi require a frontend such as claude.
Only upstream HTTP 429 before streaming advances the pool. Each limited account
is retired for that proxy session (including future requests), and exhaustion
returns HTTP 429. Start a new session after quota recovers. Already in-flight
requests may finish; errors inside streams and non-429 failures do not switch
accounts. The CLI and completed tool calls are never restarted or replayed.
No account is automatically added to the explicit fallback pool.
A skill can handle errors from a child CLI, but cannot run when its own model
request is blocked. Start with --fallback to handle that case at the proxy layer.
| Command | Description |
|---|---|
list [provider|account] (alias ls) -u,-d, --sort name|added|stored |
List all accounts or filter by provider/account. The default is provider-registry order then account name; stored preserves the accounts.json array order. -u shows live usage; -d dumps stored credentials. |
usage [provider|account] (alias u) --json, --fresh, --sort name|added|stored |
Usage for all accounts or one provider/account (shorthand for list -u), using a shared 10-minute success cache, 60-second failure cache, and deterministic order. --fresh bypasses both caches but still honors rate-limit backoff. --json is the integration contract used by aas-bar and BarShelf. |
candidates --provider <provider>, --exclude <name>, --json, --fresh |
Rank quota candidates with explicit eligibility reasons, excluding attempted accounts. |
status [provider] |
Show the active account per provider. |
active <provider> |
Print just the active account name on stdout, exiting 1 when none is set — the machine-readable half of status, used by the shims. |
update [provider…] --dry-run, --no-prune |
Update the agent CLIs exec launches (the shim-pinned CLI, else the first on PATH): npm/pnpm/bun global packages, Homebrew formulae and casks, or the CLI's own update for Claude native, Codex standalone and Grok installs. Runs with agent home variables such as CODEX_HOME cleared, so an update from inside aas exec cannot unpack into one profile. Afterwards it removes standalone releases the launcher no longer points to (Codex releases/, Claude versions/), keeping any a running process still executes from. |
shim install|uninstall [provider…], shim status |
Install wrappers in <config>/shims so the bare claude/codex follows switch. Required for Claude long-lived tokens, which cannot be written to the native store. Prepend the printed directory to PATH; status reports whether it actually precedes the real CLIs. |
login [provider] [name] --long-lived, --device-auth/--headless, --endpoint <id>, share flags |
Login and store a new isolated profile. --long-lived uses Claude's setup-token; --device-auth uses a browserless device-code flow; --endpoint picks the API host for providers that run several (kimi). |
load [provider] [name] |
Snapshot the currently logged-in credential as a system profile (auto-scans providers if none given). |
switch <provider> <name> or switch <account> (alias s) |
Make a stored account the active credential. The one-argument form resolves a globally unique stored account name. |
exec <name> [target] [args…] (alias e) |
Run the native CLI under a profile. <name> is a stored account, or a provider to auto-pick from (aas exec codex; --pick active runs its active account instead). If target ≠ the profile's provider, requests route through the local aas proxy (cross-provider). -b full-access bypass; cross-run share flags -s/-i/--share/--isolate/--keep-context; -- passes the rest to the agent. |
export [name] or export <provider> <name> --all, --vault, -o <file>, --shell posix|fish|powershell |
Print shell env to use a profile in the current shell (eval "$(aas export <name>)"), or --all for a portable bundle of every account + credential. --vault encrypts it with an age/scrypt passphrase. |
sharing <name> share flags |
Show or change which state (sessions/skills/agents/hooks/settings) an isolated profile shares from the provider's home. |
rename <from> <to> |
Rename an account, moving its profile home + markers. Codex rollout index paths follow the move; close its sessions and daemon first. |
remove [provider] <name> (alias rm) |
Remove a stored account. |
refresh <provider> <name> or refresh <account> --no-login |
Request credential renewal (falls back to login when required unless --no-login). Codex verifies the resulting token expiration and reports an unchanged credential separately. |
proxy <name> <frontend> |
Start a standalone aas proxy for <name>'s backend and print env to point a <frontend> agent at it. |
import <file> |
Restore a bundle from export --all on another host (a file, or - for stdin). |
migrate [--finish] |
Show what is left of the old asx state directory after aas moved it to aas; --finish removes the old path's link and Keychain items once no agent runs from it. |
On macOS, AAS_NO_KEYCHAIN=1 stores Claude credentials in the profile's owner-only
.credentials.json rather than the login Keychain. A non-interactive SSH session cannot reach that
Keychain, so on a Mac you administer over SSH a credential written while it was unlocked reads back
as missing once it relocks. Set it in ~/.zshenv (not ~/.zshrc, which ssh host '<cmd>' never
reads). The trade is Keychain encryption for a 0600 file in a 0700 directory.
Vault passphrases are read from the terminal without echo. For non-interactive automation, set
AAS_VAULT_PASSPHRASE only for the lifetime of the command. Imports merge by provider/account:
existing matching accounts are updated, while a name already owned by another provider is skipped.
The bundle contains AAS-managed account metadata and provider credentials, not browser cookies,
agent conversation history, or machine-specific active-account markers.
Account names and email addresses are separate metadata. Claude long-lived token credentials do not expose an email through the OAuth profile API, so newly registered token-only accounts may show only their name. Previously saved email metadata is retained and included in bundles.
Codex refresh uses the native CLI under the account's profile home. A successful native command
alone does not confirm renewal: a token that remains expired, or whose expiration cannot be
verified, makes refresh fail. An unchanged, unexpired token is reported as unchanged; this does
not verify server acceptance or revocation. CLI availability/access errors do not automatically
start a new login. exec and proxy stop if their pre-launch refresh fails and show the reason.
After a successful Codex refresh, AAS restarts an existing profile daemon using the native
codex app-server daemon restart command with that profile's CODEX_HOME. This also happens
when the token is unchanged, so an explicit aas refresh <account> --no-login can repair a
daemon left with stale credentials by an earlier external token update. Restarting can interrupt
work attached to that daemon. AAS does not signal raw PIDs or start a daemon when its metadata
is absent. If the refreshed credential is also mirrored into the native/system home, its
existing daemon is restarted too; other accounts are left alone. Restart failure makes refresh
fail without rolling back the new credential or requesting a new login.
This is a refresh-time repair, not a background watcher: token writes by processes outside AAS
can still leave an already-running daemon stale until refresh is requested again. Native
--no-daemon sessions do not keep a separate daemon's credential cache.
Claude usage displays the windows actually returned by the server. Verified Ultra accounts may have only a weekly meter; a reported five-hour meter is still shown for temporary or other plan limits. Legacy Max 20x metadata is displayed as Ultra, without inferring verification from the plan name. Long-lived tokens do not establish a subscription plan and remain unlabeled.
Codex usage is observational: it never launches codex doctor or rotates credentials. Expired
tokens are reported locally with refresh/login instructions; unexpired tokens make one usage
request, without a second native refresh on HTTP 401/403. Failures are reused for 60 seconds
across CLI/UI processes, bypassed by --fresh, and invalidated immediately when the credential
changes. Authentication failures do not display quota from an earlier successful observation.
Share flags (for login / sharing, and per-run on cross-provider exec): --shared
(default), --isolated, --share <a,b,…>, --isolate <a,b,…> over the categories
sessions, skills, agents, hooks, settings.
Providers: claude, codex, grok (alias xai), zai, kimi (alias moonshot),
cursor, pi.
Kimi / Moonshot. Kimi serves an Anthropic-compatible API, so Claude Code runs on it directly:
aas login kimi work --endpoint moonshot-ai # paste the API key; validated before it is stored
aas exec work claude # Claude Code, Kimi backendKimi runs several platforms whose API keys are not interchangeable — a key from one returns
401 on the others — so --endpoint picks the one that issued the key and it is recorded on the
account: moonshot-ai (platform.kimi.ai, per-token billing, the default), kimi-code
(Kimi Code Console, subscription), moonshot-cn (mainland China). Only these hosts are accepted,
so a tampered accounts.json cannot redirect a credential elsewhere.
Because Kimi speaks the same wire as the agent, these requests are relayed rather than
translated: the proxy rewrites only the model id and the credential, leaving cache_control,
thinking blocks and image parts intact. Prompt caching therefore keeps working, which matters on a
per-token-billed backend.
Colors respect NO_COLOR and only apply on a TTY.
aas-bar is a native macOS menubar app that shows every account's remaining quota as a ring gauge. For now, build it from a clone of this repo (macOS 14+, Swift toolchain):
cd apps/aas-bar && ./build-app.sh --install && open /Applications/AasBar.appSee apps/aas-bar/ for details.
Already using BarShelf, a scriptable menubar widget
platform? This repo also ships an aas usage widget for it:
mbk install https://github.com/Open330/aasSee widgets/barshelf-aas-usage/ for details
(deep link, requirements, permissions).
The Rust rewrite covers the original asx P1–P5 surface plus the current post-v0.3.0 proxy/provider updates:
Pi, GPT-5.6 Sol/Terra/Luna, live Grok/Z.AI/Kimi model discovery, Claude tier aliases,
Anthropic count_tokens, strict tool-argument normalization, and Grok OIDC refresh. It includes
storage/keychain/import, provider adapters,
parallel usage, account management, same- and cross-provider exec, the translating proxy,
and staged static-binary releases. Rust and Swift tests, strict lint/docs checks, installer
parsing, and portable app-bundle verification run in CI. See
docs/DESIGN.md and docs/PARITY_SPEC.md.
cargo build
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
# Regenerate the README CLI demo (requires VHS). --mode intro|changes, --channel readme|social|square
docs/demo/render.shSee CONTRIBUTING.md for the complete development workflow, SECURITY.md for private vulnerability reporting, SUPPORT.md for support channels, CODE_OF_CONDUCT.md for community expectations, and CHANGELOG.md for release history.
MIT. Bundled provider logos are trademarks of their respective owners and are used only for identification.
Part of Open330 · open source tools for AI-agent workflows · open330.github.io

