codexacc

codexacc is a small CLI for managing multiple Codex CLI accounts.

It creates one isolated CODEX_HOME per account, so each account keeps its own Codex login state, config, sessions, and cached limit information.

Quick Start

Install from npm:

npm install -g @ascenx/codexacc
codexacc help

Or install from this repo:

pnpm install
pnpm build
npm link

Then add accounts:

codexacc add personal
codexacc add work

codexacc add <name> prompts you to choose either ChatGPT login or third-party API key setup. ChatGPT login runs the normal codex login flow. Third-party API key setup asks for a server URL and API key, then writes the provider config into that account's config.toml.

Run Codex with a specific account:

codexacc run work
codexacc run work exec "fix tests"

If you omit the account name, codexacc prompts you to choose one:

codexacc run
# Select account for codexacc run:
#   1) personal  5h 25%      weekly 58%      Plus
#   2) work      5h unknown  weekly unknown

Install the shell hook once, then switch the default account:

codexacc install-shell
source ~/.zshrc
codexacc use work
codex

The shell hook runs codex through the selected account, including third-party API key accounts created by codexacc add.

You can also run codexacc use and choose from the saved account list with cached 5h and weekly limits.

Commands

codexacc add work
codexacc remove work
codexacc run work
codexacc run
codexacc run work exec "fix tests"
codexacc run-current exec "fix tests"
codexacc use work
codexacc use
codexacc current-home
codexacc install-shell
codexacc list
codexacc limits
codexacc limits --refresh

For the full usage guide, see docs/usage.md.

Storage

Accounts live under:

~/.codexacc/accounts/<name>/home

Each account home can contain Codex auth files such as auth.json. Treat the account directory like a secret.

Third-party API key accounts store their provider settings in:

~/.codexacc/accounts/<name>/home/config.toml

The API key is stored in ~/.codexacc/accounts/<name>/home/codexacc-secrets.json. codexacc run and the shell hook read that file and inject the environment variable named by env_key before starting Codex.

The generated config looks like:

model_provider = "<name>"

[model_providers.<name>]
name = "<name>"
base_url = "<server url>"
wire_api = "responses"
requires_openai_auth = false
env_key = "CODEXACC_<NAME>_API_KEY"

Limits

codexacc limits reads last-known rate_limits data from local Codex session logs. It is cached and experimental. It is not an official real-time quota API and cannot provide exact remaining message counts.

Use codexacc limits --refresh to run a tiny Codex prompt for each account before reading the cached limits. This consumes a small amount of quota per account, prints progress while refreshing, and times out each account after 120 seconds by default.

Override the per-account refresh timeout with CODEXACC_REFRESH_TIMEOUT_MS:

CODEXACC_REFRESH_TIMEOUT_MS=30000 codexacc limits --refresh