Codex Account Pool

---
name: codex-account-pool
description: Pick a CODEX_HOME source and manage an auth/account pool for tmux-workflow workers (balanced or team_cycle), with optional usage watching + rotation.
---

# 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`)
- `auth_team_dir`: **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 `CAP_AUTH_STRATEGY=team_cycle` (or config `auth_strategy: 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/AUTH_TEAM`
  - `bash .codex/skills/codex-account-pool/scripts/cap auth-advance --team-dir /abs/path/to/AUTH_TEAM`
- 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 `TWF_ACCOUNT_POOL_CMD=/abs/path/to/cap`

When enabled, `twf` will:
- call `cap pick` to choose `TWF_CODEX_HOME_SRC` (if you didn’t set `TWF_CODEX_HOME_SRC` explicitly)
- call `cap pick-auth` and copy the chosen file into each worker home as `auth.json` (overriding the synced `auth.json`)