codex-account-pool

This skill exposes a tiny CLI (scripts/cap) that:

• chooses a CODEX_HOME source directory for a worker (cap pick)
• chooses an auth credential file from an AUTH_TEAM directory (cap pick-auth)

It is designed to be called by tmux-workflow/scripts/twf when twf.account_pool.enabled: true.

Configure

Edit scripts/cap_config.yaml:

• sources: comma-separated list of CODEX_HOME template directories (optional; default fallback is ~/.codex)
• authteamdir: required when using pick-auth (should contain multiple auth JSON files; names unrestricted)

pick-auth selection algorithm:

• balanced (default): pick the least-used auth file (counts persisted in state_file); if tied, pick randomly
• team_cycle: use one auth for the whole team, and keep it stable until you advance the pointer

- good for “roles have uneven load” (avoid wasting accounts) - set via CAPAUTHSTRATEGY=teamcycle (or config authstrategy: team_cycle)

Commands

• Pick a source directory (used by twf):

- bash .codex/skills/codex-account-pool/scripts/cap pick --worker <full> --base <base>

• Pick an auth file (used by twf):

- bash .codex/skills/codex-account-pool/scripts/cap pick-auth --worker <full> --base <base>

• Print/advance current team auth (team_cycle):

- bash .codex/skills/codex-account-pool/scripts/cap auth-current --team-dir /abs/path/to/AUTHTEAM - bash .codex/skills/codex-account-pool/scripts/cap auth-advance --team-dir /abs/path/to/AUTHTEAM

• Reset the pool state (auth/home counters):

- bash .codex/skills/codex-account-pool/scripts/cap reset-state

• Inspect a whole team’s usage by driving Codex /status in tmux (requires tmux + codex):

- bash .codex/skills/codex-account-pool/scripts/cap status /abs/path/to/AUTH_TEAM

• Watch usage + rotate team auth (team_cycle + ai-team registry):

- bash .codex/skills/codex-account-pool/scripts/cap watch-team /abs/path/to/AUTH_TEAM --registry /abs/path/to/registry.json

• List configured sources:

- bash .codex/skills/codex-account-pool/scripts/cap list

• Inspect resolved config:

- bash .codex/skills/codex-account-pool/scripts/cap where

tmux-workflow integration

Enable in tmux-workflow/scripts/twf_config.yaml:

• twf.account_pool.enabled: true

Optional:

• twf.account_pool.cmd: "/abs/path/to/.codex/skills/codex-account-pool/scripts/cap"
• or TWFACCOUNTPOOL_CMD=/abs/path/to/cap

When enabled, twf will:

• call cap pick to choose TWFCODEXHOMESRC (if you didn’t set TWFCODEXHOMESRC explicitly)
• call cap pick-auth and copy the chosen file into each worker home as auth.json (overriding the synced auth.json)