codex-profiles

Named Codex homes. Separate ChatGPT windows.

Keep personal, work, and client Codex profiles organized. Open named ChatGPT windows on macOS, and bind projects to the profile they use.

10-second looping overview; desktop UI is illustrative. Watch the full 30-second video with sound.

Quick start · Workflows · Manual · Project site

See the CLI welcome screen

The CLI's welcome screen. Run codex-profile to see it in your terminal.

• Choose a profile: each name selects its own Codex home, login, and sessions.
• Keep windows separate: named macOS launches select local state for the whole ChatGPT window.
• Remember your project: bind a directory once, then launch its profile with run.

A single Bash script with no runtime dependencies beyond standard system tools. Community-maintained; not an official OpenAI project.

Quick start

You need Bash and a working Codex CLI (on PATH, or discoverable from the installed macOS app). Desktop launches also require the installed ChatGPT app. The npm installation below requires npm; a standalone installer is available under other installation methods.

npm install -g codex-profile
codex-profile setup work
codex-profile cli work

setup work creates the profile and offers Codex CLI login. Accept the login prompt and authenticate with the account you want for this profile. Setup also offers project binding, terminal integration, and a launcher on macOS; each is optional and defaults to no. Terminal integration adds the profile prompt, completions, tab titles, and completion notifications to your shell startup file after showing the exact snippet for approval. Open a new shell to use it. Setup requires an interactive terminal and can reuse an existing profile.

The npm package is codex-profile (singular). It installs both codex-profile and codex-profiles; the plural npm package is another project.

For scripts or manual setup:

codex-profile init work
codex-profile login work
codex-profile cli work

Initialize a name before launching it. Commands refuse unknown profiles so a typo does not silently create another home.

Let your agent set it up

Copy this prompt into your coding agent:

Install and configure codex-profiles using this guide:
https://github.com/Ducksss/codex-profiles/blob/main/agent.md

Ask me which profile names I want. Guide me through signing in.

Read the agent setup guide.

Everyday workflows

Switch between personal and work

After setting up work above, add your personal profile:

codex-profile setup personal
codex-profile cli personal
codex-profile cli work exec "review this repo"

Run codex-profile cli without a name for an interactive picker. Type a profile name or menu number; Enter uses the project's binding, or your current shell profile when there is no binding. Both are marked separately. In scripts, pass the name explicitly. Each profile authenticates independently.

For a profile label and completions in your current shell:

# Use bash instead of zsh for Bash.
eval "$(codex-profile shell-init zsh --prompt --completions)"
codex-profile use work

Fish and persistent setup are covered in shell integration.

To label terminal tabs and receive one-shot completion notifications, opt in:

export CODEX_PROFILE_TERMINAL_TITLE=1 CODEX_PROFILE_NOTIFY=1
codex-profile cli work exec "run tests"

Titles identify the profile and launch directory. Notifications require a compatible terminal. Terminal feedback details.

Let the project choose its profile

From your project directory, bind the initialized work profile:

codex-profile workspace bind . work
codex-profile run
codex-profile run exec "run tests and summarize failures"

The nearest bound parent directory wins, so subprojects can use different profiles. Bindings are private local metadata; no project files are changed. In a terminal, run without a binding offers profile selection and optional binding. Declining the binding still launches the selected profile. Explicitly launching a different profile warns by default. Workspace rules and strict mode.

Open a named ChatGPT window on macOS

Using the initialized work profile:

codex-profile app work

Sign into ChatGPT in the named window when prompted. Desktop and CLI sign-in are separate; the tool does not verify that they use the same account. Different names can run side by side, and reopening a name reuses its process and local data. The selected local state covers Chat, Work, and Codex.

To open your normal stock session:

codex-profile init default
codex-profile app default

To open the profile bound to your current project:

codex-profile run --app

The original signed app stays untouched. For a named, colored shortcut in Finder or the Dock, see macOS launchers.

How separation works

Selection	Local state used
default	~/.codex; app default preserves the stock ChatGPT Desktop session.
Any other name, such as work	~/.codex-work; app work also uses that home's electron-user-data/.
cli, login, env, use	Codex-only selection; these do not switch an open ChatGPT window.

Profiles do not inherit from default. Explicit configuration sharing is available through init --share-with. Profile names such as work are your labels, independent of ChatGPT's Work mode.

The tool never reads or copies authentication tokens or ChatGPT cookies. Local-state separation is not an account, OS, or server-side security boundary. OS credentials, external tools, and server-side policies remain outside its control. Use separate OS users when you need a stronger boundary. See the security model and profile layout.

Install

The npm command in Quick start is the shortest path for npm users.

Other installation methods: standalone, Homebrew, Nix, and source

With Homebrew:

brew install Ducksss/tap/codex-profile

With the standalone installer:

curl -fsSL https://raw.githubusercontent.com/Ducksss/codex-profiles/v1.1.0/install.sh \
  | CODEX_PROFILE_VERSION=v1.1.0 sh

With Nix:

nix run github:Ducksss/codex-profiles/v1.1.0
nix profile install github:Ducksss/codex-profiles/v1.1.0

From source:

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

Then verify the installation:

codex-profile doctor

Command reference

Run codex-profile for the welcome screen or codex-profile help for all commands. In a non-dumb terminal, the welcome also shows this project's binding, the current shell profile, and the relevant launch commands.

Task	Command
Guided setup	codex-profile setup work
Choose a CLI profile	codex-profile cli
Choose a ChatGPT window (macOS)	codex-profile app
List profiles	codex-profile list
Inspect Codex-local status	codex-profile status
Check your installation	codex-profile doctor
Launch this project's profile	codex-profile run
Find a profile's home	codex-profile path work
Print shell integration	codex-profile shell-init <bash|zsh|fish> [--prompt] [--completions]

Full command syntax · Shell integration · Completions · Environment overrides

Platform support

CLI commands work on macOS and Linux. app and launcher create require macOS. The CLI can use Bash, Zsh, or Fish shell integration. Terminal artwork adapts to width and UTF-8 support; NO_COLOR=1 disables colors, and piped help is plain text.

Help and documentation

• Full manual and FAQ: advanced workflows, upgrades, and troubleshooting.
• Work and personal CLI guide.
• Named ChatGPT windows guide.
• What stays separate and what remains shared.
• Report a bug or discuss a workflow.
• Agent setup instructions and machine-readable summary.

Upstream Codex's --profile selects configuration within one home; this tool selects the home itself. status reports Codex-local status, not the account shown in a Desktop window. See the FAQ for more.

Contributing

See the contributor guide and coding-agent instructions. There is no build step. Run the complete local gate before submitting changes:

make check

License

MIT