codex-profiles - Isolated Codex CLI and Desktop profiles

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
brew install Ducksss/tap/codex-profile
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.

⚠ 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 → ~/.codex
work → ~/.codex-work
personal → ~/.codex-personal
edu → ~/.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

Each profile maps to its own Codex home, such as default to ~/.codex and work to ~/.codex-work.

CLI and Desktop launch

Run Codex CLI commands or launch Codex Desktop with the selected profile environment.

Parallel Desktop instances

On macOS, app --instance can launch profile-specific Codex app clones with separate Electron user data.

Read-only diagnostics

list, status, and doctor inspect profiles without creating missing directories for typos.

Safe config cloning

clone-config copies only known non-secret root config files and refuses sensitive-looking keys.

No runtime dependencies

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	Value
Project	codex-profiles, installed as codex-profile on npm
Purpose	Switch Codex profiles by setting CODEX_HOME instead of copying auth tokens
Platforms	macOS and Linux for CLI-oriented commands; macOS for Desktop app launch workflows
License	MIT
Official URLs	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

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

Validation

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

Machine-readable docs

This page is supported by robots.txt, sitemap.xml, llms.txt, visible FAQ answers, and JSON-LD structured data.