Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ This file is the project's committed home for project-intrinsic agent knowledge:
- Default stdout is compact TOON.
- `--json` emits the normalized model, and `--full` is required before account identity or per-source attempts are shown.
- JSON provider reports include `provider`, `label`, `source`, `windows`, and `state`; `state.retryAfter` can appear for provider rate limits, and `state.reason: keychain_access_required` plus `state.remedyCommand` can appear when a stale or unavailable Claude result is blocked by a skipped macOS Keychain prompt.
- macOS Claude Keychain value reads are skipped on plain calls until a successful value read records the non-secret access marker under the quota-axi cache directory; after that, plain calls may reuse the existing grant and read live Claude quota.
- Managed-profile, Claude identity, and Codex executable-override contracts are documented in [README Security Posture](README.md#security-posture).
- Claude Keychain selection, managed-profile, Claude identity, and Codex executable-override contracts are documented in [README Security Posture](README.md#security-posture).
- `--allow-keychain-prompt` is the first-time opt-in that permits the Claude Keychain value read which can prompt, and agents should relay the one-time "Always Allow" grant when `keychain_access_required` advice appears.
- Codex uses `$CODEX_HOME/auth.json` or `~/.codex/auth.json` OAuth before the CLI fallback.
- Codex `auth.json` support is OAuth-token only; never treat `OPENAI_API_KEY` as valid quota auth or send API keys to ChatGPT quota endpoints.
Expand Down
43 changes: 23 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,14 +107,14 @@ $ quota-axi --provider claude --json
$ quota-axi auth
bin: ~/.npm/_npx/.../quota-axi
description: Inspect local quota auth sources without printing secret values
auth[7]{provider,source,path,status,error}:
claude,oauth-file,~/.claude/.credentials.json,available,none
claude,keychain,none,skipped,keychain_prompt_required
codex,auth-json,~/.codex/auth.json,available,none
codex,cli-rpc,~/.local/bin/codex,available,none
cursor,state-vscdb,~/Library/Application Support/Cursor/User/globalStorage/state.vscdb,available,none
copilot,apps-json,~/.config/github-copilot/apps.json,available,none
grok,auth-json,~/.grok/auth.json,available,none
auth[7]{provider,source,path,status,error,account}:
claude,oauth-file,~/.claude/.credentials.json,available,none,none
claude,keychain,none,skipped,keychain_prompt_required,current-user
codex,auth-json,~/.codex/auth.json,available,none,none
codex,cli-rpc,~/.local/bin/codex,available,none,none
cursor,state-vscdb,~/Library/Application Support/Cursor/User/globalStorage/state.vscdb,available,none,none
copilot,apps-json,~/.config/github-copilot/apps.json,available,none,none
grok,auth-json,~/.grok/auth.json,available,none,none
help[1]:
Run `quota-axi --allow-keychain-prompt auth` to permit macOS Keychain access
```
Expand Down Expand Up @@ -219,12 +219,13 @@ It is generated from `src/skill.ts`; update it with `pnpm run build:skill` and v

### Quota report shape

| Object | Fields |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| Quota report | `providers` |
| Provider report | `provider`, `label`, `source`, `windows`, `state`, optional `plan`, and optional `credits` |
| Provider report with `--full` | Optional `account` identity and per-source `attempts` |
| Account identity (`--full`) | Optional `email`, `organization`, `accountId`, and `identityStatus` |
| Object | Fields |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Quota report | `providers` |
| Provider report | `provider`, `label`, `source`, `windows`, `state`, optional `plan`, and optional `credits` |
| Provider report with `--full` | Optional `account` identity and per-source `attempts` |
| Account identity (`--full`) | Optional `email`, `organization`, `accountId`, and `identityStatus` |
| Source attempt (`--full`) | `source`, `status`, optional `error` or `credentialPresent`, and `account` only for Claude Keychain attempts |

Account identity and per-source `attempts` are omitted unless `--full` is passed.
Claude `identityStatus` is `verified` only when Anthropic returns an authoritative account identifier; `email` and `organization` are display-only and must not be used for duplicate detection.
Expand Down Expand Up @@ -262,7 +263,7 @@ Default TOON output includes the same condition in an `advice` block with `provi
| Window kinds | `session`, `weekly`, `monthly`, `model`, `credits`, or `unknown` |
| Source attempt statuses | `success`, `failed`, or `skipped` |

Source attempts can include `credentialPresent` when a non-secret probe confirms a credential item exists.
Claude Keychain attempts in TOON or JSON include the exact passwd-derived macOS `account` used for the lookup; non-Keychain attempts, including `oauth-file`, omit `account`. If the OS account cannot be resolved, the Keychain attempt reports `keychain_account_unavailable` without an account. Managed consumers should require exactly one matching Keychain-account record and fail closed on missing, wrong, or duplicate records. Attempts can also include `credentialPresent` when a non-secret probe confirms a credential item exists.

### Provider windows

Expand All @@ -278,13 +279,14 @@ Source attempts can include `credentialPresent` when a non-secret probe confirms

### `auth --json` shape

| Object | Fields |
| -------------------- | --------------------------------------------------------- |
| Auth report | `generatedAt`, `schemaVersion: 1`, and `auth` |
| Provider auth report | `provider` and `sources` |
| Auth source entry | `source`, optional `path`, `status`, and optional `error` |
| Object | Fields |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Auth report | `generatedAt`, `schemaVersion: 1`, and `auth` |
| Provider auth report | `provider` and `sources` |
| Auth source entry | `source`, optional `path`, `status`, optional `error`, and exact non-secret `account` for Claude Keychain entries |

Auth source entries can include `credentialPresent` when a non-secret probe confirms a credential item exists.
Claude Keychain entries in TOON or JSON auth reports include the passwd-derived macOS `account` used with the Keychain service; non-Keychain entries omit it, and `keychain_account_unavailable` is reported without one. The same fail-closed account-matching rule applies as for full quota attempts.

| Name | Values |
| -------------------- | -------------------------------------------------------------------------------------------- |
Expand All @@ -310,6 +312,7 @@ Auth source entries can include `credentialPresent` when a non-secret probe conf
- quota-axi records the non-secret access marker after any successful Keychain value read.
- When that marker exists, plain calls read the Keychain value again so an already-approved "Always Allow" grant keeps live Claude quota fresh.
- Without the flag or marker, quota-axi may perform a non-secret Keychain item presence check so it only suggests Keychain access when a Claude credential item exists.
- Presence and value reads invoke fixed `/usr/bin/security` with both the profile-derived service and the passwd-derived macOS account, so `PATH`, `USER`, and `LOGNAME` cannot redirect selection to another binary or account. If the OS account is unavailable, Keychain is skipped with `keychain_account_unavailable` while the OAuth-file and stale-cache fallbacks remain available.
- After a successful usage read, quota-axi queries Anthropic's first-party OAuth profile endpoint with the same credential. Its authoritative root `account.uuid` is exposed as `account.accountId` only in `--full` output; if that field is absent, `identityStatus` is `unverified` instead of deriving an identity from email, organization data, or cached account metadata.

**Codex**
Expand Down
5 changes: 5 additions & 0 deletions skills/quota-axi/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,11 @@ examples:
- Claude `--full` output exposes the authoritative OAuth profile `account.uuid` as
`account.accountId` when Anthropic returns one; otherwise the account identity is explicitly
marked unverified rather than inferred.
- Claude Keychain entries in TOON or JSON auth output and full attempts include the exact
passwd-derived macOS `account` used for the Keychain lookup; non-Keychain records, including
OAuth-file attempts, omit it. If the OS account cannot be resolved,
`keychain_account_unavailable` is emitted without an account. Managed consumers should require
exactly one matching record and fail closed on missing, wrong, or duplicate account data.
- The quota cache at `~/.cache/quota-axi/quotas.json` only ever holds normalized
non-secret snapshots.
Fresh provider reports with no windows clear stale provider snapshots instead of caching
Expand Down
Loading
Loading