Manage separate Codex CLI and ChatGPT profiles with isolated state

codex-profiles is a dependency-free Bash wrapper that gives Codex CLI and the ChatGPT desktop app named, separate local homes - each name selects its own CODEX_HOME, and on macOS a named Desktop launch also selects a separate Electron user-data directory for that whole ChatGPT window - without copying, inspecting, or migrating auth tokens. It draws a hard scope distinction: cli, login, env, and use only ever touch Codex-local state under the selected CODEX_HOME and never switch an open ChatGPT window, while app default opens the normal installed ChatGPT app against ~/.codex, and app <name> opens a named window with its own local Electron data across Chat, Work, and Codex modes plus a matching ~/.codex-<name>. Only default is special and maps to ~/.codex; every other name maps to ~/.codex-<name>, for example personal maps to ~/.codex-personal. A basic session:

codex-profile cli personal                     # Codex CLI on personal
codex-profile cli work exec "review this repo" # one-shot Codex CLI on work
codex-profile app default ~/Dev/app             # stock ChatGPT session
codex-profile app work ~/Dev/client             # named work ChatGPT window

Account equality between a CLI profile and a Desktop window is deliberately left unverified: the tool never inspects tokens, account identifiers, cookies, or private application data, and local-state separation is explicitly not an account, OS, or server-side boundary.

Directories can be bound to a profile once (workspace bind), after which the current directory selects its profile automatically for both run, the CLI path, and run --app, the Desktop path - the nearest bound ancestor wins, and a workspace guard (off, warn, or strict) controls whether an explicit profile selection that mismatches the bound workspace is a warning by default or a hard rejection before launch. A linked profile can be created to share only an explicit configuration allowlist - config.toml, AGENTS.md, AGENTS.override.md, instructions.md, custom-instructions.md, rules/, plugins/ - via symlinks, while auth.json, sessions/, logs/, electron-user-data/, caches, skills, and connector state are never linked; detach later converts those symlinks back into independent copies, refusing to copy anything but regular files and directories. macOS supports small, color-coded, unsigned launcher apps (launcher create) that call codex-profile app <profile> and leave the real signed ChatGPT.app untouched. doctor reports installation and local-state health, including any symlinked or hard-linked private state such as auth.json, sessions/, or state_5.sqlite, which would either couple identity across profiles or break Desktop's current fork and side-chat behavior, since that requires the session store to physically resolve inside the selected CODEX_HOME.

Use it when working across personal, work, school, client, or test Codex/ChatGPT accounts and needing genuinely separate local state per account rather than repeatedly logging in and out of one shared ~/.codex. It is explicitly not an account-identity verifier: status and doctor report Codex-local login and installation health, not which account is signed into a given ChatGPT window, and the workspace guard is a mistake-prevention guardrail, not a security boundary - it can be bypassed by invoking upstream Codex directly. It is not the same as upstream Codex's own --profile option, which selects settings within one CODEX_HOME; this tool selects the CODEX_HOME itself. It is not a substitute for separate operating-system users when a stronger isolation boundary is required, and it does not create an OS sandbox or touch server-side ChatGPT workspaces, policies, histories, connectors, plans, or limits. app and launcher create are macOS-only; the CLI-oriented commands are tested on both macOS and Ubuntu/Linux.

init <profile> [--share-with <source>] creates a profile's home, optionally symlinking the shared-configuration allowlist from a source profile; setup <profile> runs an interactive walkthrough - init, optional CLI login, optional workspace binding, optional macOS launcher - that resumes cleanly if interrupted. status/status --json and doctor/doctor --json --check report Codex-local auth and installation health, with doctor --check exiting nonzero when the CLI is missing, status collection fails, workspace state is invalid or stale, or private profile state is unsafely linked. env <profile> prints shell code to export CODEX_HOME and CODEX_PROFILE_NAME into the current shell, and the shorter use <profile> does the same after installing a one-time shell wrapper via shell-init, optionally showing the active profile in the prompt. clone-config <source> <target> copies only root-level config.toml and AGENTS.md, refusing anything that looks like a sensitive key. logs <profile> [--tail N] reads the named window's desktop.log. upgrade resolves and checks out the latest immutable GitHub release by default, or an explicit --ref for source or development updates. On macOS, launcher create <profile> --name <display-name> --color <color> generates a small, unsigned, color-coded launcher app in ~/Applications that calls codex-profile app <profile>, so different profiles show up as distinctly named, distinctly colored icons in Finder, Launchpad, and the Dock.

Wraps the upstream Codex CLI, auto-detected on PATH or falling back to the CLI bundled with the detected ChatGPT app unless CODEX_CLI is explicitly set, and the installed, signed ChatGPT.app on macOS - it never clones, patches, re-signs, or replaces that app. Numerous environment variables override its behavior: CHATGPT_APP/CODEX_APP for the app bundle, CODEX_PROFILE_CONFIG_HOME for where workspace bindings and launcher metadata live, CODEX_PROFILE_LAUNCHER_ROOT for the launcher install directory, and several upgrade and update-check variables, with the update check itself disabled via CODEX_PROFILE_NO_UPDATE_CHECK=1 or the standard DO_NOT_TRACK=1. Installable via npm, which installs both codex-profile and codex-profiles binaries, Homebrew, a standalone install script, Nix, or from source via make install.

Anyone running Codex CLI or the ChatGPT desktop app under more than one account - personal, work, a client engagement, or a test account - who wants each one to keep its own login, config, sessions, skills, and, on macOS, its own Electron-backed ChatGPT window, without hand-managing ~/.codex or accepting the tool's account-equality claims as verified security. It is MIT licensed.