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.
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.
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, 1 the release could not be
checked or the install failed (offline is a failure, not "up to date"), 2 neither
uv nor pipx is on PATH (the manual command is printed).
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) |
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)
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"
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:
| 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_countin the usage response gives the count. Only when that is above 0,list/usagemakes one moreGET(5 s timeout) to…/wham/rate-limit-reset-creditsfor 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 runslist --jsonon 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 acedar_emberblock to the same response — no extra request. Its grants'resets_leftare summed and each grant'sends_atis the expiry; grants that are notusable_nowor already ended are skipped.eligible: falsecounts as0only 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: truein--json. save,syncandrefreshare explanatory no-ops (opencode stores and refreshes its own logins);login-switchrunsopencode auth login;removerunsopencode 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. A0expires(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 onPATH - 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 onPATH— distinct from the binary check above: a newly declared[project.scripts]entry point stays invisible until the nextuv 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 — auv tool install --editable <repo> --forceyou 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 onedoctoris 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_tokenmarker 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
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.
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.
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. Re-run it after reinstalling the package if hook commands or
the installed Python path changed.
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
agyprocess) — 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.jsonis for; a reading holds until its window's reset time passes. A candidate nothing at all is known about still needs theagy_blind_switchopt-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. 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:
┌─ 🔑 ai-accounts: 3 profiles need re-login — codex, agy ─┐
│ 🔐 codex · 2 profiles
│ • work — HTTP 400 from token endpoint
│ ↳ codex-accounts login-switch work
│ • spare — refresh token missing or rejected
│ ↳ codex-accounts login-switch spare
│ 🔐 agy · 1 profile
│ • personal — revoked: refresh token rejected (invalid_grant)
│ ↳ agy-accounts login-switch personal
└─────────────────────────────────────────────────────────┘
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 windowscopilot— the monthly windowgrok— weekly SuperGrok credits and the Grok Build slice (1W USED/BUILD USEDingrok-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 listactivates 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 realagy-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 windowsopencode— not supported: its OpenAI, Anthropic and Copilot logins are already covered bycodex,claudeandcopilot, so it would only duplicate those notificationsvibe— 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
Saved Codex profiles (2)
┌──────────┬───────────────────┬──────┬────────────────┬──────────────┬─────────────────┬─────────┬───────┬────────┐
│ PROFILE │ ACCOUNT │ PLAN │ ID │ 5H USED │ 1W USED │ UPDATED │ AUTH │ STATE │
├──────────┼───────────────────┼──────┼────────────────┼──────────────┼─────────────────┼─────────┼───────┼────────┤
│ work │ user@example.com │ Plus │ acct_ab12cd345 │ 42% · 3h 12m │ 68% · 2d 4h 15m │ 14:32 │ 18:00 │ ACTIVE │
│ personal │ user2@example.com │ Free │ acct_9f8…5b4a │ 10% · 4h 50m │ 15% · 6d 2h 45m │ 09:02 │ 20:15 │ — │
└──────────┴───────────────────┴──────┴────────────────┴──────────────┴─────────────────┴─────────┴───────┴────────┘
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
Saved Codex profiles (2)
work ACTIVE
ACCOUNT user@example.com
PLAN Plus
ID acct_ab12cd345
5H USED 42% · 3h 12m
1W USED 68% · 2d 4h 15m
UPDATED 14:32
AUTH 18:00
────────────────────────────────────────
personal —
ACCOUNT user2@example.com
PLAN Free
ID acct_9f8…5b4a
5H USED 10% · 4h 50m
1W USED 15% · 6d 2h 45m
UPDATED 09:02
AUTH 20:15
(the box-drawing corners above are the classic table_style; see below — the
default modern style rounds them instead.)
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
Saved Codex profiles (2)
╭──────────┬───────────────────┬──────┬────────┐
│ PROFILE │ ACCOUNT │ PLAN │ STATE │
├──────────┼───────────────────┼──────┼────────┤
│ work │ user@example.com │ Plus │ ACTIVE │
│ personal │ user2@example.com │ Free │ — │
╰──────────┴───────────────────┴──────┴────────╯
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
Metadata
Release files for ai-accounts 0.28.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_accounts-0.28.5.tar.gz | 1.0 MB | Without provenance | Details for ai_accounts-0.28.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_accounts-0.28.5-py3-none-any.whl | Python 3 | none | any | Details for ai_accounts-0.28.5-py3-none-any.whl |
Total release size: 1.3 MB
Release files / ai_accounts-0.28.5.tar.gz
| Download URL | ai_accounts-0.28.5.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
61c482e4bcc4f4677adc603aa40708c35c209c4f62ac3240ba36ce4922ea1c7a
|
|
BLAKE2b-256 checksum How to use checksums |
c392803ae7f14f96a08305d0f06e4583d6f1ba07f94d7becab14b64ced3058a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","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.28.5-py3-none-any.whl
| Download URL | ai_accounts-0.28.5-py3-none-any.whl |
|---|---|
| Size | 295.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b36481153e04a550537c77798c31b5a8a89d3b66fcfc4a209b5f8cf02f40322f
|
|
BLAKE2b-256 checksum How to use checksums |
a9b3531f250439aed604f526a125b089c9e53c459ae0ae6b339471cf56c9e412
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","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.28.5
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.