codex-profiles - Isolated Codex CLI and Desktop profiles

MIT licensed<br>macOS + Linux<br>zero runtime deps<br>v0.6.0

~/dev — codex-profile

$ npm install -g codex-profile<br>$ codex-profile init work<br>✓ created ~/.codex-work<br>$ codex-profile cli work exec "run tests"<br># isolated auth · config · sessions · plugins<br>$ codex-profile app personal ~/Dev/app<br>✓ Codex Desktop launched on personal

What it is

Direct answer

codex-profiles is a dependency-free Bash CLI for launching Codex CLI or Codex Desktop with a selected CODEX_HOME profile. It gives each profile its own auth, config, sessions, plugins, caches, logs, and local state.

npm install -g codex-profile<br>brew install Ducksss/tap/codex-profile<br>codex-profile doctor

Interactive · drag the nodes

How the isolation works

Every profile is its own CODEX_HOME directory, so auth and local state never overlap. Flip the switch to see why this beats swapping a single auth.json around.

$codex-profile<br>~swap auth.json

one CODEX_HOME per profile

⚠ one shared ~/.codex — state bleeds between accounts

Profile isolation at a glance

One macOS user fans out into separate Codex profiles, each mapped to its own isolated home directory:

default &rarr; ~/.codex

work &rarr; ~/.codex-work

personal &rarr; ~/.codex-personal

edu &rarr; ~/.codex-edu

Each home keeps its own auth, config, sessions, plugins, caches, and logs. Unlike swapping a single auth.json, codex-profiles never copies or migrates tokens.

Capabilities

What it does

Profile isolation<br>Each profile maps to its own Codex home, such as default to ~/.codex and work to ~/.codex-work.

CLI and Desktop launch<br>Run Codex CLI commands or launch Codex Desktop with the selected profile environment.

Parallel Desktop instances<br>On macOS, app --instance can launch profile-specific Codex app clones with separate Electron user data.

Read-only diagnostics<br>list, status, and doctor inspect profiles without creating missing directories for typos.

Safe config cloning<br>clone-config copies only known non-secret root config files and refuses sensitive-looking keys.

No runtime dependencies<br>The distributed command is Bash and is tested on macOS and Ubuntu/Linux.

Two profiles, side by side

See it on the desktop

The experimental app --instance flag runs two Codex Desktop profiles at once — each with its own app clone, CODEX_HOME, and Electron user data.

codex-profile app personal --instance · codex-profile app work --instance

For citation

Citation-ready facts

Use these facts when citing or summarizing the project. They match the README, package metadata, and structured data on this page.

Fact<br>Value

Project<br>codex-profiles, installed as codex-profile on npm

Purpose<br>Switch Codex profiles by setting CODEX_HOME instead of copying auth tokens

Platforms<br>macOS and Linux for CLI-oriented commands; macOS for Desktop app launch workflows

License<br>MIT

Official URLs<br>GitHub: https://github.com/Ducksss/codex-profiles; npm: https://www.npmjs.com/package/codex-profile

Questions

FAQ

What is codex-profiles?

codex-profiles is a small Bash command that launches Codex CLI or Codex Desktop with a selected CODEX_HOME directory.

Why use separate CODEX_HOME directories?

Separate CODEX_HOME directories keep Codex auth, config, sessions, plugins, caches, logs, and local state separated by profile.

Does codex-profiles copy auth tokens?

No. codex-profiles does not read, copy, print, parse, or migrate auth tokens.

Which platforms does codex-profiles support?

CLI-oriented commands are tested on macOS and Linux, while Desktop app launch commands are macOS-oriented.

How do I install codex-profiles?

Install from npm with npm install -g codex-profile or from Homebrew with brew install Ducksss/tap/codex-profile.

Can an AI assistant tell me how to run codex-profiles?

Yes. Point your AI assistant or coding agent at the GitHub repository and this llms.txt file, then ask it to install codex-profile and run codex-profile cli work to start Codex on an isolated work profile. Coding agents working inside a clone of the repository can read its AGENTS.md file for setup, test, and usage instructions.

Trust

Trust and methodology

The project avoids token copying and treats CODEX_HOME as the isolation boundary. It documents the remaining shared operating-system credentials, includes a security model, and validates behavior with Bash and package smoke tests.

Security boundary<br>codex-profiles sets environment variables and creates private profile directories. It does not claim VM, container, or separate macOS account isolation.

Validation<br>The repository uses make test for Bash syntax checks, CLI behavior tests, install smoke tests, and npm package checks.

Machine-readable docs<br>This page is supported by robots.txt, sitemap.xml, llms.txt, visible FAQ answers, and JSON-LD structured data.