Codex Profiles

codex-profiles manages multiple Codex accounts from one WSL user by giving each account its own CODEX_HOME while selectively sharing local continuity state.

This avoids brittle auth.json swapping while keeping local history, sessions, and resume behavior usable across accounts.

Why It Exists

Using one ~/.codex for multiple accounts is awkward because:

• refresh tokens rotate, so copying auth.json back and forth is fragile
• resume depends on local state, not just remote auth
• account switching should not destroy local continuity

codex-profiles solves that by splitting state into:

• per-profile auth and account-local files
• a shared local continuity area for history, sessions, and thread index state

Docs

• Quickstart
• Command Reference
• Troubleshooting
• Design Notes

Example Profiles

The public example config is profiles.toml.example.

Example setup:

• default profile: main
• known profiles: main, work, research, personal2
• aliases:
  • p1 -> main
  • p2 -> work
  • p3 -> research
  • p4 -> personal2

Discover aliases directly:

codex-profiles aliases
codex-profiles aliases --json

Discover names and aliases together:

codex-profiles list --names

Install

Install directly from GitHub with pipx:

pipx install git+https://github.com/ecochran76/codex-profiles.git
codex-profiles --help

Upgrade later with:

pipx upgrade codex-profiles

For a repo checkout, install local helper artifacts:

codex-profiles install --shell zsh

Daily Use

Check the active profile:

codex-profiles which

Switch to another profile:

codex-profiles use p2

Start Codex using the current profile:

codex-profile
codex-profile resume --last

Start Codex using a specific profile:

codex-profile p4

Check overall health:

codex-profiles status
codex-profiles doctor

Important Behavior

Selection precedence:

1. explicit CLI profile argument
2. CODEX_PROFILE
3. persisted current profile from codex-profiles use ...
4. default_profile from profiles.toml

Concurrency:

• multiple simultaneous Codex sessions are allowed when they use the same profile
• different active profiles are blocked from running at the same time

Completion:

• codex-profiles completes command names
• codex-profile and several subcommands complete aliases and profile names

Safer launcher behavior:

• codex-profile p2 treats p2 as a profile because it is a known alias
• codex-profile work treats work as a profile because it is a known profile
• codex-profile resume --last treats resume as a Codex argument, not a new profile
• accidental junk profiles like codex-resume or codex-which should no longer be created by normal launcher use

Managed Layout

~/.codex/
  shared/
    config.toml
    skills/
    rules/
    sessions/
    history.jsonl
    state_5.sqlite
    state_5.sqlite-wal
    state_5.sqlite-shm
  codex-main/
    auth.json
    memories/
    config.toml -> ../shared/config.toml
    skills -> ../shared/skills
    rules -> ../shared/rules
    sessions -> ../shared/sessions
    history.jsonl -> ../shared/history.jsonl
    state_5.sqlite -> ../shared/state_5.sqlite
    state_5.sqlite-wal -> ../shared/state_5.sqlite-wal
    state_5.sqlite-shm -> ../shared/state_5.sqlite-shm