Metadata-Version: 2.5
Name: ai-accounts
Version: 0.31.0
Summary: Manage and switch profiles across AI coding CLIs
Project-URL: Repository, https://github.com/weskao/ai-accounts
Project-URL: Issues, https://github.com/weskao/ai-accounts/issues
Author: Wes Kao
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: telegram-kit<0.3,>=0.2.2
Requires-Dist: update-kit<0.3,>=0.2.2
Description-Content-Type: text/markdown

# 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](#install) · [Commands](#commands) · [Auto-switch](#auto-switch) ·
[Platform notes](#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](ai-accounts-list%20demo.jpeg)

### 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](#auto-switch) for setup and activation commands.

![Interactive ai-accounts config menu for auto-switch, notifications, and display settings](ai-accounts%20config%20demo.gif)

### 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. The "account switched" message arrives as a photo (a bundled card,
`src/ai_accounts/assets/account_switch.jpeg`) with the text as its caption, falling
back to plain text if the photo cannot be sent. All nine message types are in
[Telegram notification examples](docs/telegram-notifications/README.md); a few of them:

<img src="docs/telegram-notifications/01-switched-restarted.png" alt="Telegram photo message: Codex switched from alice to bob and the session restarted" width="460">

<img src="docs/telegram-notifications/02-switched-restart-needed.png" alt="Telegram photo message: Claude switched from henry to ivy, restart your session to use it" width="380">

<img src="docs/telegram-notifications/05-relogin-grouped.png" alt="Telegram message: two profiles need re-login, grouped by provider with the fix command" width="460">

<img src="docs/telegram-notifications/07-quota-reset-grouped.png" alt="Telegram message: three quota windows reset" width="560">

## Requirements

- Python 3.10 or newer
- [`uv`](https://docs.astral.sh/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:

```sh
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`:

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

Update, or uninstall:

```sh
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`.

```sh
ai-accounts migrate status      # schema, last migration (its warnings re-checked on disk), 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:

```sh
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:

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

Every provider command supports the common profile workflow:

```sh
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:

```sh
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](#fast-antigravity-lists); `usage` checks only the active account; `api-schema` prints agy's reply fields for [change watching](#watching-agys-api-for-changes) |
| `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](#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](#opencode-logins). Codex and Claude profiles also carry a
`reset_vouchers` object (see [Reset vouchers](#reset-vouchers-codex-and-claude)),
and Claude profiles a `credits` object (see [Claude credits](#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:

```json
"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 `GET`s — 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](#reset-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 a notification when an unused
voucher will expire within `reset_expiry_notify_hours` (default `72`, range
1–720), e.g. `⏳ codex: work has 2 reset voucher(s) expiring in 5h 12m`, and
once more in its final 6 hours (fixed, not configurable). Each stage fires once
per voucher: with the defaults that is about 3 days ahead and again at 6 hours.
A voucher first seen already inside the final 6 hours is reminded once, not
twice, and a window of 6 hours or less has just the one stage. Several vouchers
due on the same tick share one grouped notification. It uses the configured `notify` channel, like every other
notification; with `notify` set to `none` the reminder (and its Codex expiry
`GET`) is skipped entirely. Both keys are in the "Notifications" group of
`ai-accounts config`, `codex-accounts config` and `claude-accounts config`.

On the `telegram` channel the reminder arrives as one photo message: the text is
the caption of a fixed, provider-neutral hourglass-and-ticket card bundled in the
package (`src/ai_accounts/assets/voucher_expiry.jpeg`). If the photo cannot be
sent, the same text goes out as a plain message instead. `desktop` notifications
stay text-only.

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:

```text
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:

```json
"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)

```sh
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:

```sh
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):

```sh
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:

```sh
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.

```sh
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:

```sh
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:

```sh
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`:

```text
~/.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 <store label>"; 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](docs/telegram-notifications/README.md) 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.

```sh
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. On macOS and Linux the Claude
hook writes an interpreter under your home directory as `"$HOME/..."`, so a
`settings.json` synced across machines stays portable; Codex and Antigravity
hooks keep the absolute path.

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:

```sh
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](docs/cli-screenshots/relogin-report.jpeg)

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](#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:

```sh
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:

```sh
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:

```sh
COLUMNS=200 codex-accounts list
```

![codex-accounts list in the wide layout: a box-drawing table with one row per profile](docs/cli-screenshots/layout-wide.jpeg)

`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`.

```sh
COLUMNS=40 codex-accounts list
```

![codex-accounts list in the narrow layout: one stacked card per profile](docs/cli-screenshots/layout-narrow.jpeg)

(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:

```sh
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](docs/cli-screenshots/style-modern.jpeg)

![The classic table style: the plain full-brightness grid](docs/cli-screenshots/style-classic.jpeg)

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

```sh
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:

```sh
uv tool install --editable .
```

## License

[MIT](LICENSE)
