Skip to main content

ai-accounts

Manage, inspect, refresh, and switch saved profiles across AI coding CLIs from one dependency-free Python package.

ai-accounts is the all-provider command. The package also installs focused commands for Codex, Claude Code, Antigravity, Grok Build, Mistral Vibe, GitHub Copilot, Devin, and opencode.

Install · Commands · Auto-switch · Platform notes

See it in action

View saved profiles across providers

ai-accounts list brings saved profiles into one provider-by-provider view, marks the active profile, and shows usage where the provider supports it.

ai-accounts list showing saved profiles grouped by provider and active profile markers

Configure switching and notifications

ai-accounts config opens an interactive settings menu. Adjust auto-switch behavior, notifications, and display options; changes save as you make them. See Auto-switch for setup and activation commands.

Interactive ai-accounts config menu for auto-switch, notifications, and display settings

Get notified on Telegram

With notify set to telegram, auto-switch and the timer message you when an account is switched, when no account is left to switch to, when a token needs a re-login, or when a quota window resets. Every message ends with the source device. All nine message types are in Telegram notification examples; a few of them:

Telegram message: Codex switched from alice to bob and the session restarted Telegram message: two profiles need re-login, grouped by provider with the fix command Telegram message: three quota windows reset

Requirements

  • Python 3.10 or newer
  • uv
  • The provider CLI for each account manager you use

The Python package has no runtime dependencies.

Supported operating systems

ai-accounts is tested on and supports macOS, Windows, and Linux. Profile management, the umbrella command, and auto-switch timers work on all three.

Operating system Native integration Caveat
macOS Keychain and launchd None
Windows Credential Manager and Task Scheduler agy-accounts usage is unavailable because Antigravity usage inspection requires POSIX pseudo-terminals.
Linux Secret Service (secret-tool) and systemd user timers (or cron fallback) Install libsecret-tools before using agy-accounts.

Credential-store integration follows the native platform. The provider CLI for each account manager must also support your operating system.

Install

Install the latest release:

uv tool install --from git+https://github.com/weskao/ai-accounts.git@vX.Y.Z ai-accounts

Replace X.Y.Z with the release version you want to install.

Or install the latest main:

uv tool install --from git+https://github.com/weskao/ai-accounts.git ai-accounts

Update, or uninstall:

ai-accounts update          # install the newest release tag (no prompts)
uv tool uninstall ai-accounts

Every tool has the same command — ai-accounts update, codex-accounts update, claude-accounts update, agy-accounts update, grok-accounts update, vibe-accounts update, copilot-accounts update, devin-accounts update, opencode-accounts update — and, like every command, accepts the -- form (ai-accounts --update). Each one updates the same single install, using uv tool install --force --no-sources git+https://github.com/weskao/ai-accounts.git@vX.Y.Z (or the pipx equivalent), and the messages follow the configured language (English or Traditional Chinese). It never prompts and takes no arguments (update --help is refused with exit 2, never an install). It always lands on the newest release tag: a local checkout (uv tool install --editable . or a uv run from a clone), an install from main or another commit, or a build newer than the tag is replaced by it, whatever version it reports. Already on that tag, it says so with your version, e.g. ✅ ai-accounts 0.25.0 is already the latest version (v0.25.0). Exit code: 0 updated or already on the newest tag and the migration and integration checks passed, 1 the update, the migration or the post-update repair failed, 2 neither uv nor pipx is on PATH (the manual command is printed). The package install and the migration are reported as separate outcomes: a migration or repair failure does not undo a successfully installed package, says so, and prints the recovery command ai-accounts migrate.

After a successful <provider>-accounts update (or ai-accounts update, or the interactive Update now), the updater launches the newly installed ai-accounts migrate, which migrates local data and then repairs and verifies the hooks and OS timer — see "Upgrades and data migration" below. No separate manual step is required, also when you skip several releases.

Upgrades and data migration

Every upgrade runs the same lifecycle, in the new version's own runtime:

  1. Take an exclusive migration lock (~/.ai-accounts/migrations/lock), so two terminals, the timer and an update never migrate at the same time.
  2. Read the local data schema (~/.ai-accounts/migrations/state.json). It is separate from the app version and only changes when a migration lands. No state file means schema 0: every release before this one.
  3. Plan every pending migration from what is actually on disk.
  4. Check write permission and free disk space; stop before changing anything if either is missing.
  5. Back up each affected ai-accounts-owned directory into a private ~/.ai-accounts/migrations/backups/<time>-v<N>/ (mode 0700, file modes kept).
  6. Apply the migration, recording each step in a journal that survives a crash.
  7. Validate: every moved file must match the original (size and SHA-256), including the .current-profile active-profile marker and each profile's _secrets credential reference.
  8. Mark the schema version done and delete the backup.
  9. Re-install and verify whichever hooks and timer are already installed, using the new interpreter path and your current timer_interval_min.
  10. Release the lock and print a short report.

Migrations run in order, one checkpoint each, so upgrading straight from any older release applies every step in between. An interrupted run (crash, power loss, Ctrl-C) is rolled back first on the next run, then retried. Running it again is always safe: a completed migration is never applied twice.

Migration Schema What it does
relocate-legacy-profile-stores 1 Moves ~/.codex/accounts, ~/.claude/accounts, ~/.grok/accounts, ~/.vibe/accounts, ~/.copilot/accounts and ~/.codexbar/antigravity into ~/.ai-accounts/

What each provider gets:

Provider Migrated now Left alone, and why
Claude Code, Codex, Grok Build, Mistral Vibe, GitHub Copilot Old profile store moved into ~/.ai-accounts/<provider>/accounts, profile names and active profile kept Keychain/keyring items, vendor auth.json / .credentials.json, refresh tokens
Antigravity ~/.codexbar/antigravity moved to ~/.ai-accounts/antigravity OS keyring session, token expiry fields
Devin, OpenCode Nothing: they never had another store location Their own credential files

A store is never merged or guessed at. It stays where it is, with a warning, when its *_ACCOUNT_DIR / *_HOME override is set, when it is not a directory, or when the new location already holds data (merge those by hand). Profile files that are not valid JSON are moved byte for byte and named in the report. Saved-profile tokens still inline from an older version, and a plaintext telegram_bot_token in config.json, keep moving into the OS credential store lazily, the next time that profile is read or the config is saved, as before. Migration never writes a credential store, never refreshes a token and never touches vendor CLI files.

First run after an external install. uv tool install, uv tool upgrade, uv tool install --force, pipx and editable installs bypass update, so every command checks the schema first, before it reads any data. When it is current this costs one small file read. Otherwise the command migrates first, in any context, including the timer and vendor-CLI hooks. Hooks and timer are repaired automatically only from an interactive terminal, once per new version, and only by the installation that owns them: a uv run from a checkout never re-points your installed timer at its own virtualenv. Background runs migrate data only, because re-registering the timer from inside its own tick would stop it. The same ownership rule applies to an explicit ai-accounts migrate: run from another installation (a checkout's uv run, a scratch virtualenv), it migrates data but leaves the hooks and timer alone and names their owner; that installation's ai-accounts autoswitch setup takes them over on purpose. Diagnostic commands (migrate, doctor, --version, help) skip the check. AI_ACCOUNTS_NO_AUTO_MIGRATE=1 turns it off.

Repair never enables anything you did not set up. Hooks are re-installed only if at least one ai-accounts Stop hook exists, and the timer only if it is registered: after ai-accounts uninstall-timer it stays off. Existing unrelated hooks, every config flag and the timer interval are preserved. The hook installer manages Codex, Claude and Antigravity Stop hooks; the timer covers the rest. A missing vendor CLI (claude, codex, grok, …) is reported, never installed: its hook starts working once you install that CLI. On macOS, an editable install from ~/Documents, ~/Desktop or ~/Downloads is reported as a failure, because launchd cannot run it.

Failure and recovery. A failed step stops the chain, moves every directory this run already moved back from its current location (so a token rotated meanwhile is kept, never replaced by an older snapshot), keeps the schema where it was and exits 1. A store some other process moved in the meantime is left where that process put it. Ctrl-C rolls back the same way and still cancels the command. If something cannot be put back, the report names it and the backup is kept at the printed path; migrate status and doctor keep pointing at it until you delete it, and nothing in it is printed or logged. A data schema newer than the running version is refused without any change: run ai-accounts update.

ai-accounts migrate status      # schema, last migration, last failure, integration state; exit 1 = needs action
ai-accounts migrate --dry-run   # planned moves and repairs; writes nothing
ai-accounts migrate             # migrate now and repair/verify hooks and timer

Troubleshooting: migrate prints Another ai-accounts migration is running while another terminal or the timer holds the lock; wait a moment and retry. A lock left by a crashed process is released by the OS automatically. After a failure, migrate status shows what was not restored and where the backup is. ai-accounts doctor adds a Migrations line. Windows' uv/pipx launchers are copies rather than links, so there the first-run repair waits for ai-accounts update or ai-accounts migrate; data migration still runs first.

Supported platforms: macOS (LaunchAgent), Linux (systemd user timer or cron) and Windows (Task Scheduler), all covered by CI. CI uses mocks for every OS integration and credential store; a migration of real accounts on a real machine is a separate manual check.

When a newer GitHub release exists, any command run in a real terminal (both stdin and stdout are a TTY) ends by asking — ❯ Update now / Skip / Skip until next version — instead of just hinting. Choosing Update now runs the uv tool install --force --from git+…@vX.Y.Z ai-accounts install for you; pressing q or Ctrl+C skips the prompt. Its labels follow the configured language (English or Traditional Chinese). Skip until next version is remembered (in ~/.ai-accounts/update-check.json) so the prompt stays quiet until a release past that one shows up. A command whose output is piped, or run from the scheduled timer or a vendor-CLI hook, falls back to the old two-line stderr hint instead — never an interactive prompt with no keyboard behind it. The prompt box also shows a "Release notes:" link to the new version's GitHub release page. The release check (a git ls-remote via update-kit) runs in the background while the command works, at most once every 10 minutes (cached in ~/.update-kit/state.json; the command waits at most 0.8 s); offline stays silent, and the exit code never changes. Turn it off with ai-accounts config set update_check false; update itself always works.

Commands

Command Purpose
ai-accounts Run one operation across every provider
ai-accounts --version / ai-accounts version Print the current ai-accounts version
<command> update / <command> --update Update ai-accounts to the latest release (same for every command below; no prompts)
ai-accounts migrate [status | --dry-run] Migrate local data and repair hooks/timer (runs automatically after an upgrade)
codex-accounts Manage Codex CLI profiles and ChatGPT OAuth usage
claude-accounts Manage Claude Code profiles and quota usage
agy-accounts Manage Antigravity profiles and quota usage
grok-accounts Manage Grok Build OAuth profiles
vibe-accounts Manage Mistral Vibe API-key profiles
copilot-accounts Manage GitHub Copilot CLI profiles, identity and monthly credit balance
devin-accounts Manage Devin CLI login profiles and daily/weekly quota
opencode-accounts Switch between opencode's own stored logins, with quota for OpenAI, Anthropic and Copilot

Every command also accepts a -- prefix: ai-accounts --config is the same as ai-accounts config, codex-accounts --list is the same as codex-accounts list, and so on for every provider tool.

A mistyped command is rejected with a hint, the same in every tool: devin-accounts login-swtich work prints Did you mean: login-switch?. login-switch with no name prints its usage line.

Use the umbrella command to run the same action for all providers:

ai-accounts list                              # List saved profiles for every provider
ai-accounts who                               # Show the active account for every provider
ai-accounts usage                             # Show usage for every active account
ai-accounts refresh --all                     # Refresh every saved profile's tokens
ai-accounts sync                              # Sync active auth back to matching profiles
ai-accounts login-switch <profile_name>       # Log in again and save each login under this name
ai-accounts doctor                            # Run offline health checks for every provider
ai-accounts help                              # Show available commands
ai-accounts --version                         # Print the current ai-accounts version
ai-accounts update                            # Update to the latest release (`--update` works too)
ai-accounts migrate status                    # Show data schema and hook/timer repair state

Replace <profile_name> with a name you choose for the saved profile.

list fetches providers concurrently. Interactive actions run providers one at a time so their prompts remain usable.

list and usage also accept --json. In that mode every provider runs concurrently with its output captured (not printed live), and each provider's own --json document is merged into one object printed once, keyed by provider (codex-accounts, claude-accounts, agy-accounts, grok-accounts, vibe-accounts, copilot-accounts, devin-accounts, opencode-accounts). A provider that exits non-zero or prints unparseable output gets {"error": "..."} in its place instead of crashing the merge:

ai-accounts list --json | python3 -m json.tool
ai-accounts usage --json

Every provider command supports the common profile workflow:

codex-accounts who                            # Show the current Codex account
codex-accounts save <profile_name>            # Save the current login as a reusable profile
codex-accounts list                           # List saved profiles and their usage
codex-accounts list --json                    # Print saved profiles and usage as JSON
codex-accounts switch <profile_name>          # Switch to a saved profile
codex-accounts refresh --all                  # Refresh tokens for every saved profile
codex-accounts login-switch <profile_name>    # Log in again and save it as a profile
codex-accounts remove <profile_name>          # Delete a saved profile
codex-accounts help                           # Show available commands

codex-accounts switch (including the picker) restarts an existing local shared Codex daemon after installing the selected credentials. This makes connected Codex clients load the new account; running work may be interrupted while clients reconnect. A daemon restart failure returns a nonzero exit code with a recovery command instead of reporting a successful switch. No daemon is started when none exists; older Codex and standalone sessions must be reopened to use the account. CODEX_AUTH_JSON must point to $CODEX_HOME/auth.json when using a shared daemon. Background autoswitch keeps its existing restart policy and never restarts the shared daemon. save stores the current login; use switch <profile_name> to apply it to a running shared daemon.

The other provider tools use the same commands — swap codex-accounts for the tool you need. For example:

claude-accounts login-switch work             # Log in to Claude Code and save it as "work"
claude-accounts switch work                   # Preflight near-expiry tokens before activation
agy-accounts switch                           # Pick a saved Antigravity profile from a menu
copilot-accounts usage                        # Show the active Copilot account's credit balance
devin-accounts login-switch personal         # Log out, run `devin auth login`, save as "personal" (a cancelled login restores the old one)
opencode-accounts switch openai:work          # Make opencode's "work" OpenAI login the active one

switch and remove without a name open an interactive picker, and save without a name picks one from the active account's email or login. What differs per tool:

For OAuth-based tools, switch now renews a saved account before replacing the active credentials when its access token is near expiry:

Provider Switch safety Token upkeep
Codex Refresh target first; do not write auth.json when the macOS Keychain update fails; preserve outgoing rotated tokens OAuth refresh and existing scheduled refresh --all
Claude Code Refresh target first; keep the current login if refresh or Keychain update fails OAuth refresh and existing scheduled refresh --all
Antigravity (agy) Refresh target first; reject a failed refresh without replacing the shared keyring Google OAuth refresh, with the existing CLI fallback in refresh
Grok Build Refresh target first; reject a failed refresh without replacing auth.json Direct OIDC refresh and existing CLI fallback in refresh
Mistral Vibe Keep API-key switching; no OAuth token to rotate Static key; no refresh needed
GitHub Copilot Keep token/keyring switching and existing credential checks Token validity check; invalid tokens need login
Devin Keep API-key switching and existing verification API key validity check; no renewable OAuth token
OpenCode Delegate switching to opencode auth switch, without rewriting its credential database Managed by OpenCode itself

If the current CLI changed its credential during a network refresh, the switch aborts rather than overwriting a newer session. Automatic upkeep cannot prevent server-side revocation or refresh-token expiry. Running CLI sessions may still need a restart/resume to pick up a new login.

For Claude Code, claude-accounts switch <name> checks whether the saved account's access token expires within 24 hours. If so, it attempts to renew that destination token before touching the currently active login. A transient refresh failure or revoked credential cancels the switch and leaves the current account selected; use claude-accounts login-switch <name> for a revoked account. Switching to the already-active profile uses Claude Code's latest live credentials rather than an older saved snapshot. On macOS, if the existing Keychain login cannot be updated, switching fails rather than claiming success while Keychain and the credentials file disagree. The existing configuration and unrelated MCP credentials remain intact.

A global switch changes the default credentials. A running Claude Code session can still have older credentials cached; if a session continues with the previous account, reopen or resume it. For multiple truly independent concurrent sessions, use separate CLAUDE_CONFIG_DIR directories and the official claude auth login in each.

Command Worth knowing
claude-accounts Same workflow as Codex; login-switch runs claude auth login
agy-accounts list is slow (one account at a time) — see Fast Antigravity lists; usage checks only the active account; api-schema prints agy's reply fields for change watching
grok-accounts list shows SuperGrok plan and weekly usage; auto-switches on the weekly window
vibe-accounts API-key profiles with no quota data; refresh is not needed for static keys; no auto-switch
copilot-accounts list shows the monthly AI-credit balance; refresh only checks the token is still valid; auto-switches on the monthly window
devin-accounts list shows daily and weekly quota; refresh only checks the API key is still accepted; auto-switches on the weekly window
opencode-accounts Lists and switches opencode's own logins (it never copies tokens); save, sync and refresh are explanatory no-ops; auto-switches per integration — see opencode logins

Run <tool> help for the full command list of any tool.

Every per-provider tool's list/usage also accepts --json, printing one JSON array of {"name", "active", "usage", "no_quota_api"} objects instead of the table (usage is null and no_quota_api is true for Vibe, which has no quota API). Grok, Copilot and Devin attempt a real quota lookup and only degrade to the same no_quota_api: true shape when that lookup fails. opencode is different: no_quota_api is true only for logins with no quota API (Go, Zen and API-key logins, always switch-only); a failed OpenAI/Anthropic/Copilot lookup keeps no_quota_api: false and shows a null window — see opencode logins. Codex and Claude profiles also carry a reset_vouchers object (see Reset vouchers), and Claude profiles a credits object (see Claude credits).

Reset vouchers (Codex and Claude)

A reset voucher (重置券) refills a used-up quota window early. codex-accounts and claude-accounts list / usage (and ai-accounts list / usage, which relay them) add two columns after 1W USED:

Column Meaning
RESETS LEFT Vouchers left on the account, right-aligned
RESETS EXPIRE Time until each unexpired voucher runs out, soonest first, one per line, e.g. 11d 4h ×2 then 18d 2h below it (×2 = two vouchers expire then)

Both columns disappear when no row knows its count, and appear as labelled fields on the narrow card layout. A dim — means unknown (the provider did not say, the lookup failed, or this client is not eligible to be told) and is different from 0, which means the account really has none. RESETS EXPIRE is — whenever there is no future expiry to show.

--json adds a reset_vouchers object to each Codex and Claude profile:

"reset_vouchers": {
  "count": 3,
  "expires_soonest": "2026-10-22T19:43:18Z",
  "vouchers": [
    {"expires_at": "2026-10-22T19:43:18Z", "expires_at_unix": 1792698198, "expires_in_sec": 950000}
  ]
}

count is null when unknown; vouchers lists the unexpired ones soonest first, one entry per voucher (Claude vouchers from the same grant share its end time), and can be empty even when count is positive.

Where the numbers come from (both read-only GETs — a voucher is never consumed, and nothing here calls the redeem endpoint):

  • Codex: rate_limit_reset_credits.available_count in the usage response gives the count. Only when that is above 0, list/usage makes one more GET (5 s timeout) to …/wham/rate-limit-reset-credits for the per-voucher expiries, in parallel with the other profiles but after that profile's usage request. The auto-switch probe never makes it. Quota-reset detection runs list --json on every timer tick but sets an internal opt-out (AI_ACCOUNTS_SKIP_RESET_EXPIRY), so it skips the request and keeps only the count — except on the 30-minute full tick while voucher-expiry reminders are on, which need the expiries.
  • Claude: the usage request carries ?cedar_ember=1, which adds a cedar_ember block to the same response — no extra request. Its grants' resets_left are summed and each grant's ends_at is the expiry; grants that are not usable_now or already ended are skipped. eligible: false counts as 0 only for account-level reasons (tier, tenure, no_weekly_limit, weekly_limit, not_at_wall, extra_usage, other_experiment, mobile); a client-level (surface, cli_version) or unrecognised reason stays unknown. If the server rejects the parameter (HTTP 400/404), the usage request is retried once without it, so the 5h/7d windows and auto-switch never depend on voucher support (vouchers then show —).

The server only reports Claude vouchers to a client that looks like Claude Code, so the request sends User-Agent: claude-cli/2.1.296 (external, cli). If vouchers turn — after a Claude Code upgrade, set CLAUDE_USAGE_USER_AGENT to a current value (for example claude-cli/<your claude --version> (external, cli)).

Reset-voucher expiry reminders

reset_expiry_notify (default true) sends one notification when an unused voucher will expire within reset_expiry_notify_hours (default 24, range 1–720), e.g. ⏳ codex: work has 2 reset voucher(s) expiring in 5h 12m. Each voucher is reminded about once; several due on the same tick share one grouped notification. It uses the configured notify channel, like every other notification. Both keys are in the "Notifications" group of ai-accounts config, codex-accounts config and claude-accounts config.

It runs on the scheduled timer's 30-minute full tick (ai-accounts install-timer), reusing the quota-reset scan's list --json call, so it costs no extra subprocess — only the Codex expiry GET above, for accounts that have vouchers. Any provider whose list --json rows carry reset_vouchers is covered automatically.

Claude credits

Claude's paid extra usage ("credits", spent once the plan limits run out) shows in claude-accounts list / usage (and ai-accounts list / usage) as a CREDITS column, on two lines:

66% · $66.26 / $100.00
resets 20d 7h

That is the share of the monthly limit used, spent / limit, and the time left until the month rolls over (counted like RESETS EXPIRE). --json keeps the date as resets_on. The percent is colored like the usage columns (green, yellow from 50%, red from 80%). The column disappears when no account has extra usage turned on. save, switch and login-switch end with the same table, so they show it too.

--json adds a credits object to each Claude profile, in major units:

"credits": {"used": 66.26, "limit": 100.0, "currency": "USD", "percent": 66, "resets_on": "2026-11-01"}

It is null when extra usage is off or the server did not report it. limit and percent are null when there is no monthly cap.

It comes from the extra_usage block of the same read-only usage response — no extra request. Amounts arrive in minor units (used_credits: 6626 with decimal_places: 2 is $66.26). The response has no reset date, so resets is the first of next month (calendar-month billing, as Claude Code shows it). Other currencies print as EUR 12.34.

Antigravity profile names

agy-accounts save [<profile_name>] uses the active email when available. If Antigravity cannot report an email, it still saves the account under a stable agy-<token-digest> label; pass a name to choose your own label.

who also answers to current. login-switch <name> runs a fresh provider login and saves the result as <name> — it is what the re-login report below tells you to run.

Grok plan and usage

grok-accounts list shows PROFILE, ACCOUNT, PLAN, ID, 1W USED, BUILD USED, UPDATED, and STATE. Access-token expiry stays on who (Session is refreshable or browser login; Expires is the access token's own remaining time, about 1 hour). A saved profile's access token is normally past that hour, and switch renews it. switch also copies the live auth file back into the account being left before it overwrites that file, because x.ai revokes a refresh token when it issues the next one. PLAN is the consumer subscription (SuperGrok, SuperGrok Plus, SuperGrok Heavy, or Free) from the Grok Build CLI billing proxy — not the OIDC principal_type, which is User for every personal login. A successful /user reply with a null subscriptionTier is Free. 1W USED is the weekly SuperGrok credit pool; BUILD USED is the Grok Build slice of that same week. Both come from GET https://cli-chat-proxy.grok.com/v1/billing?format=credits plus GET …/v1/user?include=subscription, authenticated with the profile's OAuth access token. A failed lookup degrades to the no-quota JSON shape rather than failing list.

Copilot account details and balance

copilot-accounts list shows PROFILE, ACCOUNT, PLAN, ID, MONTH USED, REMAINING, UPDATED, AUTH, and STATE. copilot-accounts usage shows the same details for the active saved profile. Account details are fetched from GitHub on each listing, with saved details as a fallback, without rewriting profiles. Listings identify the active profile from Copilot's config.json without reading the OS credential store on macOS, Windows, or Linux. ACCOUNT displays Name <email> when available, otherwise the name, GitHub login, or email. A private primary email is included only when GitHub allows the token to read it and reports it as verified.

For AI-credit billing, the monthly balance comes from GitHub's chat quota, matching the plan allowance used by Copilot /usage. A quota marked has_quota: false with an entitlement of 0 — such as the obsolete premium bucket on a credit plan — is unavailable, not 100% used; the same flag on an entitled bucket means the quota is spent, so an exhausted account reads 100% · 200/200 AIC with 0 AIC remaining instead of —. Legacy billing still shows premium requests. For example, 2% · 22d 4h 35m · 12/500 AIC shows percent used, time until reset, and used/total credits; 487.5 AIC in REMAINING preserves GitHub's fractional balance. GitHub's percentage and credit counters can have different rounding. Unlimited quotas say unlimited. Copilot does not supply 5-hour/weekly windows or token expiry through these lookups, so those columns are omitted. UPDATED is the successful fetch time; AUTH is valid, rejected (HTTP 401), missing, or unknown.

--json adds account, login, email, id, and auth to each profile. The usage object includes monthly, unit (AIC or requests), used, entitlement, remaining, and unlimited, alongside the existing premium, chat, completions, plan, refreshed_at, and error fields. Unavailable values are null; existing no-quota behavior is retained.

Devin plan and usage

devin-accounts keeps several Devin CLI logins. The live login is credentials.toml in the Devin data directory (${XDG_DATA_HOME:-~/.local/share}/devin; %APPDATA%\devin on Windows; override with DEVIN_DATA_DIR). Profiles are saved under ~/.ai-accounts/devin/accounts (override with DEVIN_ACCOUNT_DIR); each profile's API key is kept in the OS credential store when one is available. login-switch backs up the live login before running devin auth login, keeping the previous live login as a one-deep backup (the next switch overwrites it).

list and usage show the plan plus daily and weekly quota, read from the Windsurf GetUserStatus call the Devin CLI itself makes. That endpoint is undocumented, so if it changes a failed lookup degrades to the no-quota JSON shape (usage: null, no_quota_api: true) rather than failing list. Devin API keys do not expire by default, so refresh only verifies each key is still accepted and never modifies a login.

opencode logins

opencode-accounts is a view and switcher over opencode's own login store — opencode v2 already keeps several logins per integration. It lists them from opencode's database read-only, switches with opencode auth switch, and never writes opencode's files. Logins are named <integration>:<label> (for example openai:work). MCP server logins (integration mcp_…, such as Notion) live in the same table but are not AI logins, so they are hidden. It never refreshes tokens: opencode does that itself, and refreshing elsewhere would log out codex-accounts / claude-accounts, which share the same single-use OpenAI refresh token.

  • OpenAI, Anthropic, GitHub Copilot logins show usage (reusing the Codex, Claude and Copilot quota lookups) and take part in auto-switch.
  • opencode Go/Zen and API-key logins are switch-only: no usage, no_quota_api: true in --json.
  • save, sync and refresh are explanatory no-ops (opencode stores and refreshes its own logins); login-switch runs opencode auth login; remove runs opencode auth logout.
  • Expired spare logins: opencode only refreshes a token when it uses that login, so an idle spare's token may have expired. Auto-switch skips it without a network call and prints which spares are expired; open opencode with one once (opencode-accounts switch <name>) and it can be considered again. An expired active login is not probed either: its usage reads as unknown, nothing is switched, and the output says to open opencode with it once. A 0 expires (Copilot device-flow logins) means "never expires".

opencode's data directory is ${XDG_DATA_HOME:-~/.local/share}/opencode on every OS (override with OPENCODE_DATA_DIR). The Windows location is an assumption — not verified on Windows.

Doctor

ai-accounts doctor runs one offline health check per provider — no live quota/HTTP calls — and never fails the process just because a provider isn't set up; it reports the gap instead:

  • the provider's CLI binary (codex, claude, agy, grok, vibe, copilot, devin, opencode) is on PATH
  • the provider's own account-tool console script (codex-accounts, claude-accounts, agy-accounts, grok-accounts, vibe-accounts, copilot-accounts, devin-accounts, opencode-accounts) is on PATH — distinct from the binary check above: a newly declared [project.scripts] entry point stays invisible until the next uv tool install/uv sync, so a stale install can have the vendor CLI present while its own account tool is a bare shell "command not found" with no other clue. The table cell for a failing row just names the missing tool, matching every other cell's length; the fix — a uv tool install --editable <repo> --force you can run as-is, plus, best-effort, a note when the currently installed tool is an editable install pointing at a different checkout than the one doctor is running from — is printed once below the table, not repeated per provider
  • the OS credential store is reachable (macOS/Windows Keychain/Credential Manager, or Linux secret-tool)
  • every saved profile's JSON is well-formed and, if it carries a recognizable expiry field, not already expired with nothing left to refresh it (a stale access token backed by a live refresh token is normal, not a failure) — this reads a migrated profile's _secrets.has_refresh_token marker the same way it reads an unmigrated profile's inline refresh token, never the credential store itself
  • the auto-switch timer's install state — plus a note when a timer-only setting (enabled, token_refresh, reset_notify) is on but the timer is not installed
  • where saved-profile secrets currently live (see "Where your secrets live" below) — the OS credential store's label, or a plaintext-fallback reason — printed once for the whole run, not per provider
  • the migration state: data schema current, pending, interrupted or newer than this version, and whether the last hook/timer repair failed (doctor never migrates; ai-accounts migrate does)
ai-accounts doctor

This is the real output — one wide table plus a short footer — from a fresh install where none of the vendor CLIs or account tools are on PATH yet, and no profiles have been saved for any provider (every existing user's first run after upgrading to this version). Captured by pointing each provider's *_ACCOUNT_DIR override (see "Profile storage" below) at an empty directory, so the table reflects a true empty store rather than hand-edited numbers:

CODEX_ACCOUNT_DIR=<empty-dir> CLAUDE_ACCOUNT_DIR=<empty-dir> \
ANTIGRAVITY_ACCOUNT_DIR=<empty-dir> GROK_ACCOUNT_DIR=<empty-dir> \
VIBE_ACCOUNT_DIR=<empty-dir> COPILOT_ACCOUNT_DIR=<empty-dir> \
DEVIN_ACCOUNT_DIR=<empty-dir> OPENCODE_ACCOUNT_DIR=<empty-dir> \
PATH=/usr/bin:/bin ai-accounts doctor
╭───────────────────┬───────────────────────────────────┬────────────────────────────────────────────┬──────────────────┬────────────────────────┬───────────────────╮
│ Provider          │ Binary                            │ Account tool                               │ Credential store │ Profiles               │ STATE             │
├───────────────────┼───────────────────────────────────┼────────────────────────────────────────────┼──────────────────┼────────────────────────┼───────────────────┤
│ codex-accounts    │ FAIL `codex` not found on PATH    │ FAIL `codex-accounts` not found on PATH    │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ claude-accounts   │ FAIL `claude` not found on PATH   │ FAIL `claude-accounts` not found on PATH   │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ agy-accounts      │ FAIL `agy` not found on PATH      │ FAIL `agy-accounts` not found on PATH      │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ grok-accounts     │ FAIL `grok` not found on PATH     │ FAIL `grok-accounts` not found on PATH     │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ vibe-accounts     │ FAIL `vibe` not found on PATH     │ FAIL `vibe-accounts` not found on PATH     │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ copilot-accounts  │ FAIL `copilot` not found on PATH  │ FAIL `copilot-accounts` not found on PATH  │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ devin-accounts    │ FAIL `devin` not found on PATH    │ FAIL `devin-accounts` not found on PATH    │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
│ opencode-accounts │ FAIL `opencode` not found on PATH │ FAIL `opencode-accounts` not found on PATH │ PASS reachable   │ PASS no saved profiles │ FAIL issues found │
╰───────────────────┴───────────────────────────────────┴────────────────────────────────────────────┴──────────────────┴────────────────────────┴───────────────────╯

Autoswitch timer: PASS installed
Token storage: PASS macOS Keychain
Account tool not on PATH for: codex-accounts, claude-accounts, agy-accounts, grok-accounts, vibe-accounts, copilot-accounts, devin-accounts, opencode-accounts
This can mean the tool was never installed, a newly declared entry point needs a reinstall, or its install directory isn't on PATH.
Run uv tool install --editable <repo> --force

Once a provider's CLI and account tool are actually on PATH, its "Binary" and "Account tool" cells read PASS instead — an "Account tool" cell never carries the fix, only the fact; the fix is the "Run ..." line below the table, printed once for however many providers are missing theirs, not repeated per row. (STATE, not "Status" — matches the header every other accounts_table caller in this repo uses.) When doctor can also tell that the currently installed tool is an editable install pointing at a different checkout than the one it's running from, it appends one more line noting that under the "Run ..." line.

--json prints one JSON document (never one per provider — same merge shape as list --json/usage --json above), keyed by provider label. A failing account_tool check carries a remediation field with the same install command shown in the footer above (kept in full — only the table cell got shorter), the top-level account_tool_note key mirrors the optional "different checkout" note (null when it doesn't apply), and the top-level token_storage key mirrors the "Token storage" line ({"ok": true, "detail": "macOS Keychain"}, or {"ok": true, "detail": "plaintext fallback (<reason>)"} with no OS credential store):

ai-accounts doctor --json | python3 -m json.tool

List performance

ai-accounts list runs providers concurrently and displays each provider's table as it finishes. Codex, Claude, Grok, Copilot, Devin, and opencode also fetch usage concurrently across profiles. Vibe lists local profile data without quota network requests. Copilot additionally fetches GitHub identity per profile (plus the primary email when permitted). Failed quota requests retain the same no-quota result shape as Vibe.

Antigravity queries different credentials sequentially: each query switches the shared OS keyring session, launches agy, waits for authentication and quota data, then closes it. The original session is restored after listing. Within each launch, quota and account-status RPCs run concurrently. agy is launched with a freshly generated --csrf_token and every RPC carries it as x-codeium-csrf-token; the language server answers 401 missing CSRF token without it, which would surface as ERR agy in the UPDATED column. Its replies are proto3 JSON, which omits default values, so a fully spent bucket carries no remainingFraction at all — an identifiable bucket (one with a bucketId, window, or resetTime) that is missing the fraction reads as 100% used, while a bucket with none of those markers stays blank rather than claiming exhaustion from a malformed payload. Profiles with identical credential file contents reuse a successful result within that invocation; different credentials and failed lookups are not reused.

Measured on 2026-09-07 (Asia/Taipei), on a local macOS machine:

Provider command Saved profiles Total list time Time per profile (total ÷ count) Work performed
codex-accounts list 5 0.944 s 0.189 s Concurrent usage requests
claude-accounts list 1 0.739 s 0.739 s Concurrent usage requests when multiple profiles exist
agy-accounts list 6 24.484 s 4.081 s Sequential credential sessions; concurrent RPCs within each session
grok-accounts list 7 0.003 s <0.001 s Concurrent SuperGrok billing requests (was local-only before quota lookup)
vibe-accounts list 1 0.028 s 0.028 s Local profile and credential-store reads
copilot-accounts list 7 1.173 s 0.168 s Concurrent usage requests plus per-profile GitHub identity lookups

These are single-run measurements of each provider's cmd_list(), with the five providers running concurrently in separate processes and output captured. They include list rendering and, for Antigravity, agy startup and cleanup, but exclude Python interpreter startup and module imports. Counts refer to saved profiles, which are not necessarily distinct accounts.

Reset-voucher columns: Claude's vouchers ride the usage request it already makes, so they cost nothing. Codex adds one 5 s-capped GET per profile that has vouchers. It runs after that profile's usage GET (it needs the count first), so it is sequential within the profile; profiles still run in parallel, so the cost is roughly one extra request round-trip, not one per profile. An A/B of in-process cmd_list() with one voucher-bearing profile measured a median of 0.72 s without the lookup and 1.10 s with it (about +0.4 s). End-to-end uv run codex-accounts list with that profile measured 1.12, 1.17 and 1.37 s in three runs (median 1.17 s, including uv startup and imports).

The Copilot row was added later (measured on 2026-10-11): the median of five sequential in-process cmd_list() runs (1.152–1.553 s), with output captured.

Time per profile is an amortized value, not individual request latency. In particular, dividing a concurrent provider's total time by its profile count does not measure how long one account would take on its own. Authentication, network conditions, and machine load affect these results. Parallel RPCs do not remove Antigravity's per-account startup cost, so it can still dominate the total time of ai-accounts list.

Ctrl-C stops list for any provider, including ai-accounts list. The command exits with status 130 and does not print a traceback.

To query only the selected Antigravity account, use:

agy-accounts usage

Watching agy's API for changes

agy's local API has no public spec. api-schema prints the closest thing: the field names and JSON types of the two replies quota reading depends on (RetrieveUserQuotaSummary and GetUserStatus), as one JSON object. It never prints a value, so no email, name, or quota number appears.

agy-accounts api-schema

The object holds:

Key Meaning
agy_version Output of agy --version
methods Per reply, every field path mapped to its JSON types. [] marks list items. A map keyed by non-identifiers, such as supportedMimeTypes, collapses to {*}
watched The field paths the quota and plan parsers read
parsed Whether each parsed value (weekly and 5-hour windows, email, plan) was found
buckets Each quota bucket as group · bucketId · window, without numbers
error null, or why agy could not be read (the exit status is then 1)

It reads only the live session, so no saved profile is ever made live for it. agy omits fields that hold a default value, so a spent bucket's remainingFraction can be missing without any API change. Quota periods use the bucket's window field, falling back to its ID/name when that field is missing or blank; unknown explicit periods remain unavailable. The 5-hour period is accepted as five-hour or 5h (agy 1.4.10 sends 5h). If agy returns only weekly buckets, the 5-hour readings remain unavailable; they are not inferred from weekly quota. Optional tier fields such as upgradeButtonText and availableCredits, and top-level ones like disableTelemetry, do not affect email or PLAN parsing.

agy can answer GetUserStatus before its keyring session has loaded. That early reply carries only an error message and no email or tier. Quota reading ignores it and keeps polling, so the PLAN column no longer goes blank for a healthy account.

Fast Antigravity lists

Antigravity can only report quota for the live credential session, so a live agy-accounts list must check profiles one at a time. Cached-list mode (agy_list_cached_usage, on by default) queries the current account live and uses saved readings for other accounts instead:

agy-accounts list --refresh  # populate or update the saved readings
agy-accounts list            # current account live; other accounts from cache

A live probe makes each profile the keyring session for a moment and, when agy rotated its access token, folds the fresh token back into the profile. That fold-back only happens while the keyring still holds the profile's own refresh token: a running agy session or the Antigravity IDE can rewrite the shared slot in between, and saving that blob would hand the profile another account's tokens (the row then shows RELOGIN until fixed). refresh, switch, sync and login-switch apply the same check.

Cached readings can be stale. The list labels this mode and repeats the refresh command; turn the setting off when every listing must fetch live quota:

ai-accounts config set agy_list_cached_usage false

The current account is always queried live, so listing still waits for that one query. If it fails, UPDATED shows the error instead of stale quota.

Profile storage

Saved profiles and shared settings live under ~/.ai-accounts:

~/.ai-accounts/
├── config.json
├── autoswitch-state.json
├── dpapi/                    # Windows only: DPAPI-encrypted secret files
├── codex/accounts/
├── codex/backups/
├── claude/accounts/
├── antigravity/accounts/
├── antigravity/usage-cache.json
├── grok/accounts/
├── vibe/accounts/
├── copilot/accounts/
├── devin/accounts/
└── opencode/accounts/        # unused: opencode keeps its own logins

Newly saved telegram_bot_token values go to the OS credential store instead — macOS Keychain, the Secret Service (secret-tool) on Linux, Credential Manager on Windows — under the service name ai-accounts. On a machine with no credential store, saving a token is refused rather than written as plaintext or scrambled with something reversible; export AI_ACCOUNTS_TELEGRAM_BOT_TOKEN there instead. That variable also overrides the stored value whenever it is set, so the read order is environment → credential store → config file.

That last rung exists only for upgrades: a token already sitting in an older config.json keeps working, and the next save moves it into the credential store and drops it from the file. If the store is unavailable, the legacy plaintext value remains to avoid losing the only copy; existing backups are not scrubbed by migration.

Platform Bot token location Chat ID location / protection
macOS Keychain generic password: service ai-accounts, account telegram_bot_token ~/.ai-accounts/config.json, plaintext, owner-only mode 0600 on writes
Linux Secret Service default collection via secret-tool: service=ai-accounts, username=telegram_bot_token ~/.ai-accounts/config.json, plaintext, owner-only mode 0600 on writes
Windows Credential Manager generic credential: ai-accounts:telegram_bot_token %USERPROFILE%\.ai-accounts\config.json, plaintext; access depends on inherited Windows ACLs, not POSIX mode 0600

AI_ACCOUNTS_CONFIG_JSON overrides the JSON path on every platform. The credential-store slot belongs to the OS user and is shared across config paths. Linux needs both secret-tool and a running, unlocked Secret Service; a headless session may not have one. Credential stores protect storage, but do not guarantee protection from malware running as the same user or an administrator.

The bot token authenticates the bot; keep it private. The chat ID only selects the recipient, but can identify a user/group: it remains visible in --config and config export, so redact it before sharing exports. Token entry in --config is hidden, including the numbered fallback (which refuses input if echo cannot be disabled). Prefer that over config set telegram_bot_token …, whose argument can appear in shell history and process listings. Environment overrides are also plaintext process data; do not commit them to shell files. If a token was exposed, revoke/regenerate it with BotFather and save the replacement.

Saved-profile secrets follow the same pattern. When an OS credential store is available, a saved profile's <name>.json holds metadata only — expiry fields, account identity, and a small _secrets marker block (store, key, has_refresh_token, a non-secret fingerprint) — while the actual access/refresh/id tokens live under the credential store's service name ai-accounts, keyed <tool>--<profile> (e.g. codex--work). See "Where your secrets live" below for what this protects against, per OS, in plain terms. Switching an account keeps one latest pre-switch backup per tool (not one per switch): also in the credential store when available, and printed as "backed up to "; otherwise a single plaintext <tool>/backups/latest file, printed as "backed up to backups/latest".

An existing profile written by an older version of this tool still has its tokens inline; the next time it's read, they're moved into the credential store and the file is rewritten without them — a one-time, automatic migration with a short printed line (→ Moved secrets of <file> into the <store label>). A store write that fails, or a machine with no credential store at all (e.g. headless Linux without secret-tool), falls back to the full plaintext file exactly as before, plus one yellow warning per process — this is a fallback, not a refusal, so existing headless setups keep working.

antigravity/usage-cache.json holds the last quota reading seen for each agy profile — quota windows, plan and timestamp, but no credentials (see below for why it is kept). A plaintext-fallback profile JSON file does contain live credentials: do not commit, publish, or share this directory. Writes use owner-only permissions and atomic replacement where the provider format allows it. Windows has no POSIX permission bits, so there the protection comes from the parent directory's inherited ACL: the default location under your user profile is already owner-only, but an override pointing outside it inherits whatever that directory allows.

Provider-native legacy stores such as ~/.codex/accounts and ~/.claude/accounts are moved into the central directory on first use. Override paths with CODEX_ACCOUNT_DIR, CLAUDE_ACCOUNT_DIR, ANTIGRAVITY_ACCOUNT_DIR, GROK_ACCOUNT_DIR, VIBE_ACCOUNT_DIR, COPILOT_ACCOUNT_DIR, or DEVIN_ACCOUNT_DIR. Override the shared config with AI_ACCOUNTS_CONFIG_JSON.

Where your secrets live

No setup needed — this happens automatically the first time each tool saves or reads a profile. On macOS, the very first access may show a one-time Keychain "Allow" prompt for the process asking; approving it is normal and only needs to happen once per binary.

OS Where tokens go Fallback if unavailable
macOS Keychain (security), service ai-accounts plaintext profile file
Windows DPAPI-encrypted files under ~/.ai-accounts/dpapi plaintext profile file
Linux Secret Service via secret-tool (GNOME Keyring, KWallet, ...) plaintext profile file

What this protects against: a file-system backup, a cloud-sync folder, or a Time Machine copy landing on an unencrypted disk no longer hands over a live token with it; an accidental cat ~/.ai-accounts/**/*.json, screenshot, or git add -A no longer leaks a token, only account metadata; and another account on the same machine reading your files directly (without also being able to unlock your keychain/session) gets nothing usable.

What it does not protect against: malware or a script running as your own user can still ask the credential store for the secret, the same way this tool does — an OS credential store stops a file being read, not your own account being compromised. It also doesn't touch each vendor CLI's own files (~/.codex/auth.json, ~/.claude/.credentials.json, and similar) — those stay exactly as that vendor's own CLI writes them; this tool's credential-store protection covers its own saved profile copies, not the live session file the vendor CLI itself manages.

Auto-switch

Auto-switch can refresh quota data, select another saved profile when the active profile crosses a configured threshold, notify you, and restart supported interactive sessions. Every notification ai-accounts sends — a switch, a dead end with no account left to switch to, the re-login report, a quota reset — ends with the source device (for example, 💻 MacBook Pro · d011******** or 🖥️ Mac mini · d011********), over desktop and Telegram alike. See Telegram notification examples for each message type as it arrives.

The device code uses the hardware serial on macOS (ioreg), and an application-specific HMAC-SHA256 digest of Windows MachineGuid or Linux /etc/machine-id (falling back to /var/lib/dbus/machine-id). Only the first four characters are shown; the rest are masked. These IDs do not depend on network interfaces. Windows/Linux IDs identify the OS installation and may change after reinstalling or be duplicated by cloning an image. If no valid ID is readable, the label shows unknown and notifications still work.

ai-accounts config
ai-accounts config get
ai-accounts config set enabled true
ai-accounts config set layout narrow
ai-accounts config export settings.json
ai-accounts config import settings.json
ai-accounts autoswitch
ai-accounts autoswitch setup
ai-accounts install-timer
ai-accounts timer-status

ai-accounts config opens the interactive menu for configuring auto-switch behavior and notifications. Arrow keys select and change values, d resets the highlighted field to its default after a y confirmation naming that field, D resets every setting to its default after a y confirmation, and each change is saved as you make it — there is no separate save step. When stdin is not a TTY the menu falls back to a numbered prompt. On/off settings read as On / Off there (green / dim, translated with the menu); config get and config set keep the scriptable true / false spelling.

config export [file] writes the current settings as JSON — to the given file (owner-only, mode 600), or to standard output when no file is given so config export | … pipes cleanly. Secrets are never exported: telegram_bot_token is left out of the file entirely, and the command says so every time, because a restored backup with no token is why notifications would otherwise go quiet. Export is a full backup and is not filtered per CLI — the Antigravity keys are included even when it runs from codex-accounts.

config import <file> applies those settings back, all or nothing, and reports what it did:

  • A secret in the file is skipped, never written — a hand-written or mask-shaped (********WXYZ) value would destroy the real token stored on this machine.
  • An unknown key (from a newer ai-accounts) is left alone rather than written back unvalidated.
  • One invalid value aborts the whole import before the first write, so a half-applied config is never the outcome. The exit code is 1 and the config on disk is untouched.

Both directions work from every CLI (codex-accounts config export, …) and print their notice on stderr.

The Antigravity blind-switch and inactive-account cache options appear only in ai-accounts config and agy-accounts config (including their config get listings). Other provider menus omit them, and resetting those menus preserves the hidden settings. Explicit config get <key> and config set <key> <value> remain shared across all CLIs.

ai-accounts autoswitch setup installs provider event hooks plus a low-frequency OS timer fallback. After an upgrade, ai-accounts update (or, for a manual uv tool install / pipx upgrade, the next command you run in a terminal) re-installs and verifies whichever of them are installed, using the upgraded installation's interpreter (see "Upgrades and data migration"). To restart or re-register the timer on any supported OS, re-run ai-accounts install-timer (it uses the timer_interval_min setting). This unloads and loads the LaunchAgent on macOS, reloads and restarts the systemd user timer on Linux (or replaces the cron entry), and replaces the Task Scheduler task on Windows. ai-accounts config changes are read on the next timer tick; they do not require a restart. Telegram notifications from timer runs include the scheduler and job label: launchd: com.ai_accounts.autoswitch on macOS, systemd: com.ai_accounts.autoswitch.timer or cron: ai-accounts-autoswitch on Linux, and Task Scheduler: com.ai_accounts.autoswitch on Windows. The timer has no dedicated log file. On macOS, launchd cannot read ~/Documents, ~/Desktop or ~/Downloads, so a uv tool install --editable from one of those folders makes every timer tick fail at start-up (exit code 1, nothing logged) and neither autoswitch nor token refresh ever runs. install-timer warns about this; fix it with a normal install: uv tool install --reinstall <path-to-repo>. copilot-accounts autoswitch switches off the active profile once its monthly quota reaches switch_when_used_pct; Copilot has no Stop hook, so the timer is its only trigger, and the new account applies on Copilot CLI's next launch. grok-accounts autoswitch does the same on the weekly SuperGrok window, also from the timer only; run from a terminal, it then resumes with grok --continue. devin-accounts autoswitch reads the weekly window by default (the switch_window setting), also runs from the timer only, and from a terminal resumes with devin --continue. opencode-accounts autoswitch runs once per integration (OpenAI, Anthropic, GitHub Copilot; Go/Zen and API-key logins are never auto-switched); from a terminal it resumes once with opencode --continue after every integration has switched, so the switch notifications say a restart is needed. A spare login whose access token has expired is not probed (it is never refreshed): autoswitch names it so you can open opencode with it once; an expired active login is likewise not probed, so nothing is switched. When the same OpenAI, Anthropic or Copilot account is also managed by codex-accounts, claude-accounts or copilot-accounts, each tool switches its own store and sends its own notification, so you may get two.

Status checks are read-only: enabled reads the shared config, autoswitch_setup.is_installed() checks both timer registration and relevant hooks, and ai-accounts timer-status checks the platform's timer registration. macOS checks the LaunchAgent file; Linux checks the systemd timer file or reads crontab; Windows queries Task Scheduler with schtasks /Query. An installed result confirms registration, not successful execution or quota availability. Windows hook commands quote interpreter paths containing spaces; re-run setup to update hooks installed by an older version.

When CI fails after a push, GitHub Actions sends a formatted Telegram alert with the repository, branch, short commit ID, and a clickable workflow URL. Repository secrets TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be configured before the alert can be delivered.

ai-accounts install-timer registers only the OS timer, without the provider hooks, and takes --interval <seconds> (default: the timer_interval_min setting, 5 minutes). Most ticks are cheap: the provider probes and token refresh run at most every 30 minutes; a 5-minute tick runs only the reset scan (one list --json per watched provider). Upgrading from the old 1800-second default? Re-run install-timer once. timer_interval_min (ai-accounts config, "Reset check interval" under Notifications) sets how often the timer wakes: numbers only, default 5, minimum 1, maximum 60. Changing it re-registers an already-installed timer by itself; with no timer installed it only saves the value. A passed --interval overrides the setting for that install only. The first tick runs at login/boot, not one interval later — RunAtLoad on macOS, OnBootSec=60 on systemd, an @reboot line on cron — so a quota window that reset while the machine was off is reported as soon as you are back, provided reset_notify is on. (Windows' scheduled task has no logon trigger; its first tick lands within one interval of boot instead.) Remove it with:

ai-accounts uninstall-timer

The target is the saved profile with the lowest usage still under the threshold, ties broken by profile name. When activating it fails — a deleted profile, a credential the CLI refuses — the next candidate in that order is tried, so one dead profile cannot strand you on an exhausted account.

Antigravity is the exception: agy reports quota only for the session that is live, so reading a candidate's quota means writing its credential into the single slot a running agy reads. That is safe only while nothing else holds that slot, which gives agy-accounts autoswitch two modes:

  • Nothing running (no Antigravity IDE, no agy process) — every candidate is measured for real, the slot restored after each reading, and the switch goes to the account with the lowest verified usage. No opt-in needed: nothing here is a guess.
  • Something running — nothing is swapped. Candidates are ranked by the last reading taken for each of them, which is what antigravity/usage-cache.json is for; a reading holds until its window's reset time passes. A candidate nothing at all is known about still needs the agy_blind_switch opt-in, which switches without any usage data for the target.

Note the Stop hook always takes the second path: the agy session whose exit fired the hook is still up, and is itself a reader. Measuring is the background timer's job.

Either way it passes over a profile that could not take over: a malformed or foreign credential blob, a token that can no longer be refreshed, or a second profile of the same Google account as the exhausted one.

The interactive config menu documents each setting. CLI config reads mask the Telegram bot token.

Scheduled token refresh and the re-login report

token_refresh is an independent switch from enabled: each timer tick runs refresh --all on every provider even when auto-switching is off. A routine rotation is silent. Claude Code refreshes its own active session tokens, while the timer also renews saved inactive profiles. If Claude Code changes the live login during an in-flight refresh, the scheduled refresh discards that stale result instead of overwriting the CLI's newer token; the next tick can retry. A refresh token can still be revoked or reach its absolute expiry, so periodic refresh reduces unexpected expiration but cannot guarantee a permanent login. When a refresh token can only be fixed by a fresh login, the tick prints a report and sends the same content over the configured notify channel — grouped by provider, one row per profile with the reason it failed and the command that fixes it:

Re-login report panel grouped by provider, one row per profile with the reason and the fix command

Each provider gets its own color, on the heading and on every profile name under it. The alert is de-duplicated by the exact set of profiles it names: the same set stays quiet for an hour, while a newly revoked profile alerts on the next tick instead of waiting out the previous alert's cooldown. Transient failures (a 5xx, a timeout, an unreachable token endpoint) are retried on the next tick and never reported here. Copilot has no refresh token: its refresh checks the saved token against GitHub, and only a 401 lands in this report. Like every notification, it ends with the source device (see Auto-switch).

Quota-reset notifications

reset_notify (default true) sends a notification when a provider's quota window resets and full usage is available again. reset_notify_min_used_pct (default 90) gates it: only a window that was at least that heavily used just before it reset triggers a notification, so a window that reset while barely touched stays quiet. Both are ai-accounts config keys (group "Notifications"), also available from every per-provider config (the config is shared), e.g. devin-accounts config or opencode-accounts config.

A reset is recognised two ways, so one that happens off schedule still notifies. Normally the window's recorded reset time arrives and the provider reports a later one. But a provider can also hand out quota early — a holiday top-up, a goodwill credit — and then that deadline never arrives, so only the fall in usage reveals it. A fall counts as a reset when the reset time jumped with it — moved further into the future than the time that passed since the previous scan. A freshly issued window lands hours further out; a window merely ageing out has a reset time that advances only as fast as the clock, which is the signature that keeps gradual decay from reading as a reset. Without such a jump, a fall of at least 50 points still counts if the reset time stayed put, any fall beyond a 10-point noise floor counts — a fixed window cannot fall at all without having been cleared. Providers differ here and both shapes are handled: codex zeroes its 5h and weekly windows and restarts the weekly count from the reset moment (its deadline jumps), while claude zeroes both but leaves the weekly deadline where it was. A reset time that moved but did not jump is the sliding-decay shape, and needs a fall of at least 50 points. All routes share the reset_notify_min_used_pct gate.

An account plan change is not a reset, and is excluded before either route runs. Moving from a 1x to a 5x account (or 5x to 20x) leaves the same absolute usage against a larger allowance, so the reported percentage drops sharply while the window and its deadline carry on untouched — the exact shape of a cleared counter. codex-accounts list --json and claude-accounts list --json therefore also report each profile's plan (claude's includes the rate multiplier, e.g. Max · 5x, so a 5x-to-20x move on one plan is visible), and a window whose plan changed since the previous tick is re-baselined silently. A downgrade raises the percentage instead, which never looked like a reset. Real resets on the new plan notify as usual from the next tick on; agy reports no plan, so nothing changes there.

Because detection is a periodic scan, neither route needs the window to still read 0% when the tick lands — you may well have started using the fresh quota already. The scheduled route ignores the fresh percentage entirely, and the off-schedule route asks what the window's end did, not how low the reading landed, so an early reset caught at 5%, 15%, 40% or 60% used still notifies. The one gap left: with the deadline unmoved, a reset is missed if the fresh window was re-consumed to within 10 points of the old reading inside a single tick (95% down to 86%, say) — at that point the fall is indistinguishable from reporting jitter.

Every notification also says how long ago each window reset, e.g. • codex · work · weekly (reset 2d 9h ago, was 100%) — the units follow the notification language (zh-TW: 2 天 9 小時前已重置). A reset can be noticed late — the timer was not running, a provider's list --json kept failing, or agy's cache was stale — and it is still reported then, but the age makes it read as old news instead of quota that just came back. A scheduled reset is dated by the deadline it passed; an off-schedule one only by the previous scan, so it reads reset within the last 30m. The age is left out when unknown (a state entry from an older version) and when under a minute, so a reset that fresh keeps the plain wording (was 95%).

Detection runs across every saved profile for a covered provider, not just the currently active one, so an account benched by auto-switch still gets its "usable again" notification. Each timer tick sends at most one grouped notification over the configured notify channel, covering every window that reset since the previous tick. The title counts the windows per provider (codex ×1, claude ×2, agy ×1).

docs/quota-reset-cases.md is the full case table — every scenario the detection rule was verified against, with the number of notifications each one produces, including the ones that deliberately produce none.

Provider coverage:

  • codex / claude — hourly and weekly windows
  • copilot — the monthly window
  • grok — weekly SuperGrok credits and the Grok Build slice (1W USED / BUILD USED in grok-accounts list)
  • agy — all four windows (Gemini 5h/weekly, Claude/GPT 5h/weekly), but read from its local usage cache rather than probed live: agy-accounts list activates each profile through the shared credential slot to query it, which is not something a background timer should do. So agy readings are only as fresh as the last real agy-accounts list, list --refresh, or auto-switch probe. A profile that has never been probed is silently skipped, and a stale cache means a late notification, never a wrong one. Because the next reset time is then computed rather than reported by the provider, agy notifications say the reading came from the cache instead of quoting a next reset time.
  • devin — the daily and weekly windows
  • opencode — not supported: its OpenAI, Anthropic and Copilot logins are already covered by codex, claude and copilot, so it would only duplicate those notifications
  • vibe — not supported: no quota API to watch.

Detection only happens on a timer tick, so a reset — scheduled, or an off-schedule one such as Codex handing quota back early — is noticed on the next tick (the timer_interval_min setting, default 5 minutes); it is not instantaneous or event-driven.

The scheduled timer (ai-accounts install-timer) must be installed, or this feature does nothing: with no timer running, reset_notify makes no extra list --json calls and sends no notifications. Two in-product signals cover this. Turning reset_notify (or enabled / token_refresh, the other timer-only settings) on in the interactive ai-accounts config menu offers "Install it now?" when auto-switch setup (the timer and the hooks) isn't installed — for a key you switched on in that session, or one that is on although it defaults to off (enabled, an explicit opt-in). Default-on keys (reset_notify, token_refresh) already being on never prompt, so leaving the menu with the defaults untouched is quiet. (config set and the non-interactive menu never prompt.) And ai-accounts doctor prints a note under the timer line whenever one of those settings is on but the timer is not installed, naming the settings and the install command.

Because reset_notify defaults to on, anyone who already has the timer installed starts getting these notifications the next time a covered window resets, with no action taken on their part — this is a behavior change on upgrade, not just a new opt-in setting. Volume is bounded: at most one notification per window per reset, so a single provider/profile sitting above the threshold sees at most ~5 notifications a day from its hourly window plus at most one more from its weekly/monthly window in the same period.

Language

Notifications, the interactive config menu, the version update prompt and the update messages, agy-accounts list's usage-freshness footer notes, and every tool's help/-h/--help output are localized. English (en) and Traditional Chinese (zh-TW) are available; the default follows the OS locale and falls back to English for a locale with no translation:

ai-accounts config set language zh-TW
ai-accounts config set language en

The setting only affects display text. Config keys, values, and command names stay in English so scripts keep working across languages.

Output layout

Every table and panel — list, who, the save/switch/refresh success panels, the re-login report, and the interactive ai-accounts config menu itself — adapts to how wide the terminal is. The layout setting controls it:

ai-accounts config set layout auto     # default: follow terminal width
ai-accounts config set layout wide     # always the desktop table
ai-accounts config set layout narrow   # always the stacked, phone-width layout

In wide, the config menu grows its box to fit the longest label, value and help text, but never past the terminal — long help lines wrap inside the box instead of pushing it off-screen.

auto renders the wide box-drawing table at 60 columns or wider — as long as the whole table fits the terminal. A table that is too wide first stacks each cell's · parts (and an account's <email>, and the header words) on their own lines; only if that still does not fit does it switch to stacked narrow cards — one per profile, no column dropped — as it also does below 60 columns (a wrapped table breaks its borders), which is the layout a phone-width SSH session or a narrow split pane needs. COLUMNS overrides the detected width, so either mode can be previewed from a full-size terminal:

COLUMNS=200 codex-accounts list

codex-accounts list in the wide layout: a box-drawing table with one row per profile

STATE reads the same in every tool's list: ACTIVE for the live login, SAME ACCT for another saved profile of an account that already has a row (the active row, else the first, stays ACTIVE/—), and — otherwise. The account is the provider's account id or email — per integration for opencode; Vibe reports none, so it never shows SAME ACCT.

COLUMNS=40 codex-accounts list

codex-accounts list in the narrow layout: one stacked card per profile

(both layouts above are drawn in the default modern table_style; see below for classic.)

Table style

Every table and panel is also painted by the table_style setting, independent of layout above — layout decides table vs. stacked cards, table_style decides how either one is drawn:

ai-accounts config set table_style modern   # default: rounded, dimmed frame,
                                             # banded header, zebra-striped rows
ai-accounts config set table_style classic  # the plain full-brightness grid —
                                             # also the safer pick on a light
                                             # terminal, where a 256-color band
                                             # can wash out

The modern table style: rounded dimmed frame, banded header, zebra-striped rows

The classic table style: the plain full-brightness grid

In the interactive menu (ai-accounts config) the Table style row previews itself: while it is selected, a three-row sample table is drawn in the empty gutter to the right of the settings list, in whatever style is currently cycled onto the row — and the menu's own frame re-rounds with it — so the choice is made by looking at it rather than by saving, quitting and running a listing. The demo fills space the box already had, so nothing moves as you arrow onto that row; at phone width, where there is no gutter, it stacks under the rows instead.

table_style also stripes every --help output's USAGE/EXAMPLES command list under modern — every other command entry (its wrapped description lines included) gets the same zebra-stripe background as an odd table row, so a long command list stays easy to scan line by line; classic leaves it plain, same as it leaves tables unbanded.

Platform notes

Provider Credential source Notes
Codex ~/.codex/auth.json and the native credential store codex is required for login flows
Claude Code ~/.claude/.credentials.json and macOS Keychain when used claude is required for login flows
Antigravity macOS Keychain, Windows Credential Manager, or Linux Secret Service Linux needs secret-tool from libsecret
Grok Build $GROK_HOME/auth.json SuperGrok plan and weekly/Grok Build usage come from the CLI billing proxy. Autoswitch reads the weekly window
Devin credentials.toml in ${XDG_DATA_HOME:-~/.local/share}/devin (%APPDATA%\devin on Windows; $DEVIN_DATA_DIR overrides); saved API keys in the OS credential store devin is required for login flows. Daily/weekly usage comes from the undocumented Windsurf GetUserStatus call and degrades to "no quota API" if it changes. Autoswitch reads the weekly window. switch writes the saved profile's top-level string keys (non-string values and [tables] are not carried over); switch and login-switch first keep a one-deep backup of the raw live file
opencode opencode.db (SQLite, read-only) in ${XDG_DATA_HOME:-~/.local/share}/opencode ($OPENCODE_DATA_DIR overrides); legacy auth.json as fallback (one login per integration, so no switching) opencode is required; changes go through opencode auth switch|logout|login. The Windows data-dir path is an assumption — not verified on Windows
Mistral Vibe macOS Keychain or $VIBE_HOME/.env On Windows and Linux, $VIBE_HOME/.env is used; vibe is required for login flows
GitHub Copilot OS credential store item copilot-cli / <host>:<login> (macOS Keychain; Linux Secret Service via secret-tool; Windows Credential Manager target <host>:<login>.copilot-cli, UTF-16), with the signed-in login read from ~/.copilot/config.json (JSONC); that file's plaintext authTokens when the CLI has no store (or storeTokenPlaintext is set); $COPILOT_GITHUB_TOKEN/$GH_TOKEN/$GITHUB_TOKEN as last resort (the CLI itself prefers the first non-empty of these, in that order, over the stored login, so an exported one shadows switch and who warns) copilot is required for login flows. Store layout and monthly AI-credit quota verified on macOS; plaintext layout verified with copilot login --with-token. Linux/Windows naming follows the keyring-core store crates the CLI ships but is not yet observed on a live login; Linux needs secret-tool (libsecret). switch writes the plaintext entry only when the CLI already uses it.

Run a provider command with --help for its exact files, environment overrides, and authentication behavior.

Development

git clone https://github.com/weskao/ai-accounts.git
cd ai-accounts
uv sync --locked
uv run pytest
uv run ruff check .
uv build

Install the checkout globally while developing:

uv tool install --editable .

License

MIT

Metadata

Release files for ai-accounts 0.29.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-accounts 0.29.0
File Size Uploaded Provenance Actions
ai_accounts-0.29.0.tar.gz 1.5 MB Without provenance Details for ai_accounts-0.29.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-accounts 0.29.0
File Interpreter ABI Platform Actions
ai_accounts-0.29.0-py3-none-any.whl Python 3 none any Details for ai_accounts-0.29.0-py3-none-any.whl

Total release size: 1.8 MB

Release files / ai_accounts-0.29.0.tar.gz

Download URL ai_accounts-0.29.0.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
41888e0c16f4a73b140675c7b224918aef34ee2be08ca82a894055d0f6ba8b21
BLAKE2b-256 checksum
How to use checksums
fe699e2bbda0e57753fb8673090358bf57ebee81e24364f187e5a14cde57955f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ai_accounts-0.29.0-py3-none-any.whl

Download URL ai_accounts-0.29.0-py3-none-any.whl
Size 314.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62118b5901c232c1f36f6f6b6b89801520ffe0748014cf45d858ba5e413b4f1a
BLAKE2b-256 checksum
How to use checksums
bbfe0a6a77e6d0cd106833045ab1db2a0b1abab126331695e8c92f0ab2f673fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ai-accounts 0.29.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page