codex-profiles

Run Codex with separate accounts, settings, sessions, connectors, logs, and local state without copying token files around.

codex-profiles is a small Bash wrapper around Codex's CODEX_HOME support. Each profile maps to its own Codex home directory, then the wrapper launches the Codex CLI or Codex Desktop with that profile selected.

codex-profile cli personal
codex-profile cli work exec "review this repo"
codex-profile app edu

Why It Exists

Codex already supports custom state directories through CODEX_HOME:

CODEX_HOME="$HOME/.codex-personal" codex
CODEX_HOME="$HOME/.codex-work" codex exec "review this repo"
CODEX_HOME="$HOME/.codex-edu" /Applications/Codex.app/Contents/MacOS/Codex

That is the right boundary, but it is awkward to type and easy to forget. Copying auth.json is worse: it moves tokens while leaving sessions, config, connector state, plugins, caches, and logs shared.

codex-profile gives the clean boundary a short command.

Demo

Watch the short reveal video

Highlights

• Isolated Codex homes per profile.
• CLI and Codex Desktop launch support.
• No token copying, parsing, printing, or migration.
• Read-only list, status, and doctor commands for diagnostics.
• JSON output for automation.
• Profile lifecycle commands: init and confirmed remove.
• Profile-local desktop logs with private permissions.
• Safe config cloning for known non-secret config files.
• Bash, Zsh, and Fish completion generators.
• Source-style self-upgrade with dry-run preview.
• No third-party runtime dependencies.
• Tested on macOS and Ubuntu.

Install

With Homebrew:

brew install Ducksss/tap/codex-profile

From source:

git clone https://github.com/Ducksss/codex-profiles.git
cd codex-profiles
make install

Source installs copy bin/codex-profile to ~/.local/bin/codex-profile. Make sure ~/.local/bin is on your PATH.

Verify the install:

codex-profile doctor

Quick Start

Create and log in to each profile once:

codex-profile init personal
codex-profile init work
codex-profile login personal
codex-profile login work

Run Codex CLI with a profile:

codex-profile cli personal
codex-profile cli work exec "run tests and summarize failures"

Run Codex Desktop with a profile on macOS:

codex-profile app personal ~/Dev/my-project
codex-profile app work

Check what exists and what is logged in:

codex-profile list
codex-profile status
codex-profile doctor

How Profiles Map To Disk

Only default is special:

default     -> ~/.codex
<profile>   -> ~/.codex-<profile>

Examples:

personal -> ~/.codex-personal
work     -> ~/.codex-work
dev      -> ~/.codex-dev
main     -> ~/.codex-main
edu      -> ~/.codex-edu

Profile names must start with a letter or number, then may contain letters, numbers, dots, dashes, or underscores. You can inspect a path without launching Codex:

codex-profile path personal

Common Workflows

Manage Profiles

Create a profile home without launching Codex:

codex-profile init client-a

Remove a profile home interactively:

codex-profile remove client-a

Use --yes for scripts:

codex-profile remove client-a --yes

Use default explicitly if you intend to remove ~/.codex. Every other valid name removes only its own .codex-<profile> directory.

Inspect Status

Human-readable output:

codex-profile status
codex-profile status personal
codex-profile doctor

Machine-readable output:

codex-profile status --json
codex-profile doctor --json

status and list are read-only. They report missing profiles instead of creating directories for typos.

Read Desktop Logs

Desktop logs live inside the selected profile home:

codex-profile logs personal --path
codex-profile logs personal
codex-profile logs personal --tail 100

Clone Safe Config

Copy known non-secret config files from one profile to another:

codex-profile clone-config personal work
codex-profile clone-config personal work --force

Only these root-level files are considered:

config.toml
AGENTS.md
instructions.md
custom-instructions.md

clone-config never copies auth.json, sessions, plugins, logs, caches, or directories. It also refuses files with sensitive-looking key names such as token, secret, password, credential, or api_key.

Upgrade Source Installs

Preview the upgrade:

codex-profile upgrade --dry-run

Install from the default project repo and branch:

codex-profile upgrade

By default, upgrade fetches main from https://github.com/Ducksss/codex-profiles.git into ~/.cache/codex-profile/source, then runs make install with PREFIX=~/.local.

Use a different install prefix or source ref:

codex-profile upgrade --prefix /usr/local
codex-profile upgrade --ref v0.1.3
codex-profile upgrade --ref <commit-sha>

Upgrade refuses to install a candidate with no declared version, or a candidate whose declared version is older than the running codex-profile.

If you installed with Homebrew and do not want a source-style ~/.local/bin/codex-profile, use Homebrew instead:

brew upgrade Ducksss/tap/codex-profile

Shell Completions

Generate completions for Bash, Zsh, or Fish:

codex-profile completions bash
codex-profile completions zsh
codex-profile completions fish

Bash example:

mkdir -p ~/.local/share/bash-completion/completions
codex-profile completions bash > ~/.local/share/bash-completion/completions/codex-profile

Zsh example:

mkdir -p ~/.zfunc
codex-profile completions zsh > ~/.zfunc/_codex-profile

Add the directory to fpath in ~/.zshrc before compinit:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

Aliases

Aliases are optional, but useful for accounts you use every day:

alias codex-personal='codex-profile cli personal'
alias codex-work='codex-profile cli work'
alias codex-app-work='codex-profile app work'

Command Reference

codex-profile app <profile> [workspace]
codex-profile cli <profile> [codex-args...]
codex-profile login <profile> [codex-login-args...]
codex-profile init <profile>
codex-profile remove <profile> [--yes]
codex-profile status [profile]
codex-profile status --json [profile]
codex-profile path <profile>
codex-profile logs <profile> [--path|--tail [lines]]
codex-profile clone-config <source-profile> <target-profile> [--force]
codex-profile list
codex-profile doctor [--json]
codex-profile completions <bash|zsh|fish>
codex-profile upgrade [--dry-run] [--prefix <path>] [--ref <git-ref>]
codex-profile version
codex-profile --version

Environment Overrides

CODEX_APP                      Override Codex.app path
CODEX_APP_BIN                  Override Codex Desktop binary path
CODEX_CLI                      Override Codex CLI binary path
CODEX_PROFILE_UPGRADE_REPO     Override upgrade repository
CODEX_PROFILE_UPGRADE_REF      Override upgrade git ref
CODEX_PROFILE_UPGRADE_CACHE    Override upgrade cache checkout
CODEX_PROFILE_UPGRADE_PREFIX   Override upgrade install prefix

Examples:

CODEX_CLI=/path/to/codex codex-profile cli personal
CODEX_PROFILE_UPGRADE_REF=v0.1.3 codex-profile upgrade --dry-run

Platform Support

CLI-oriented commands are Bash-based and tested on macOS and Ubuntu/Linux:

cli login init remove status path logs clone-config list doctor completions upgrade

The app command is macOS-only because it launches Codex.app and uses macOS app-control tooling to quit the running desktop app before relaunching it with a different CODEX_HOME.

Desktop App Notes

Codex Desktop should run one profile at a time. codex-profile app <profile> asks the running Codex app to quit, waits for it to close, then launches the app with the selected CODEX_HOME.

For predictable account switching, launch Codex Desktop through codex-profile instead of Dock or Spotlight.

Security Model

codex-profile does one security-sensitive thing: it sets CODEX_HOME before running Codex. It does not read, copy, print, parse, or migrate auth tokens.

clone-config uses a small allowlist and refuses sensitive-looking config files. It does not inspect or rewrite Codex auth files.

upgrade fetches and installs code from the configured git repository. The default repository is this project. --dry-run prints the source ref, cache path, and install prefix before anything changes. Do not point upgrade at a repository you do not trust.

Separate Codex homes are cleaner than swapping auth.json, but they are not full OS-level isolation. Your operating system user still shares SSH keys, GitHub CLI auth, browser cookies, cloud CLI credentials, npm state, and other external credentials.

For strict work/personal separation, use separate OS users.

FAQ

Is this an official OpenAI project?

No. This project is community-maintained and is not affiliated with OpenAI.

Is this the same as Codex's built-in config profiles?

No. Codex config profiles switch settings inside one CODEX_HOME, such as model, approval policy, sandboxing, and hooks.

codex-profiles switches CODEX_HOME itself, so each account can have separate auth, config, sessions, plugins, logs, caches, and local Codex state.

Does it copy my tokens?

No. It does not read or copy auth.json. Codex itself creates and uses auth inside the selected CODEX_HOME.

Why not just swap auth.json?

Swapping only auth.json leaves other Codex state shared: sessions, config, plugins, logs, connector/app caches, and more. Separate CODEX_HOME directories are a cleaner boundary.

Can I run two desktop profiles at once?

Not safely. Codex Desktop is treated as one active profile at a time. The app command quits the current Codex app before launching the selected profile.

Does this isolate external tools too?

No. Your OS user still shares SSH keys, GitHub CLI auth, cloud CLIs, browser state, and other non-Codex credentials.

Development

Run the test suite:

make test

Run ShellCheck:

make lint

The test suite covers Bash syntax, profile path mapping, install smoke tests, CLI/login pass-through, list/version output, source upgrades, fresh-profile status checks, hardened status discovery, private desktop log placement, and missing-CLI doctor output.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for local setup, testing, and contribution guidelines.

Questions, workflow ideas, and launch feedback are welcome in the Codex profile workflows discussion.

License

MIT