Each profile maps to its own Codex home, such as default to ~/.codex and work to ~/.codex-work.
What it is
Direct answer
codex-profiles is a dependency-free Bash CLI for named Codex homes and, on macOS, named ChatGPT windows with separate local state. Codex-only commands stay separate from whole-window Desktop launches, and authentication files are never copied.
npm install -g codex-profile
brew install Ducksss/tap/codex-profile
codex-profile doctorInteractive isolation model · drag the nodes
One home for every profile.
Every CLI profile selects its own CODEX_HOME. On macOS, a named app launch also selects separate local state for the whole ChatGPT window. Flip the switch to see why this beats swapping one 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→~/.codexwork→~/.codex-workpersonal→~/.codex-personaledu→~/.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
Run Codex-only commands with a named home, or open a whole ChatGPT window with matching Codex state.
On macOS, named app launches use separate Electron state while preserving the original signed ChatGPT app.
list, status, and doctor inspect profiles without creating missing directories for typos.
clone-config copies only known non-secret root config files and refuses sensitive-looking keys.
The distributed command is Bash and is tested on macOS and Ubuntu/Linux.
Desktop proof
Two named windows, side by side.
app personal and app work open the original signed ChatGPT app with separate whole-window state and matching Codex homes — without cloning, patching, or re-signing the app.
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 | Select named Codex homes and named ChatGPT windows with separate local state without 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
Questions, answered.
What is codex-profiles?
codex-profiles is a Bash command that selects named CODEX_HOME directories and, on macOS, named ChatGPT windows with separate local state.
Why use separate CODEX_HOME directories?
Separate CODEX_HOME directories keep Codex auth, config, sessions, plugins, caches, logs, and local state separated by profile.
How does Desktop separation work?
A named app launch selects separate Electron state for the whole ChatGPT window and a matching CODEX_HOME for Codex. The boundary applies across Chat, Work, and Codex, but account identity remains unverified.
What does app default do?
After the default profile is initialized, app default uses ~/.codex and preserves the stock ChatGPT Desktop session without a custom Electron user-data directory.
Does codex-profiles verify that CLI and Desktop use the same account?
No. CLI and Desktop sessions can be authenticated independently, and codex-profiles does not inspect account identifiers or credentials to compare them.
Does codex-profiles copy auth tokens?
No. codex-profiles does not read, copy, print, parse, upload, compare, or migrate authentication tokens or ChatGPT cookies.
Which platforms does codex-profiles support?
CLI-oriented commands are tested on macOS and Linux, while ChatGPT Desktop launching is available on macOS.
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 multiple named ChatGPT windows run at once?
Yes. Different names use separate local Electron state and can run side by side, while app default keeps the ordinary stock ChatGPT session.
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, initialize work, and run codex-profile cli work to start Codex on that profile. Coding agents working inside a clone of the repository can read its AGENTS.md file for setup, test, and usage instructions.
Why does fork fail with rollout path must be in Codex home directory?
Current Codex Desktop resolves the rollout path before checking that it stays under CODEX_HOME. A sessions/ or state_5.sqlite symlink from a named home into another home makes that check fail, so fork and side chats break. A shared state_5.sqlite also breaks archive and delete, which restrict rollout paths to sessions/ and mention that directory in the error. init --share-with never creates those links. Do not symlink the session store. Sharing chats across people means one real Desktop CODEX_HOME. Separate ChatGPT logins then require selecting that account's auth.json; the account chip follows CODEX_HOME auth.json, not Electron user-data alone. This tool does not copy auth.json.
Trust
The boundary is explicit local state.
Codex-only commands select a CODEX_HOME. Named app launches also select separate Electron state for the whole ChatGPT window. The project never copies authentication files and documents what remains shared.
codex-profiles sets environment variables and creates private Codex and Electron-state directories. It does not claim VM, container, separate macOS account, or verified account-identity isolation.
The repository uses make check as one deterministic syntax, behavior, packaging, release, documentation, and shell-lint gate.
This page is supported by robots.txt, sitemap.xml, llms.txt, visible FAQ answers, and JSON-LD structured data.