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

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. Use the arrow keys and Enter, or type to filter profiles. The project's binding is selected first, or your current shell profile when there is no binding; both are marked separately. Exact names and menu numbers also work. 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.

Use the native menu-bar companion

Source checkouts can build Codex Profiles.app for macOS 13 or newer:

make menu-app
open "build/macos/Codex Profiles.app"

Open an existing profile in ChatGPT or Terminal, or choose Create profile… on first run. No project folder is required. Add workspace… optionally binds a folder to a profile for project shortcuts. Search and filter profiles, pin frequent projects, repair moved folders, change a binding, or open a row in the other destination from its actions menu. Use ↑/↓ and Return, or ⌘1–9, to launch from the keyboard. Open at Login in the gear menu keeps the companion in the menu bar.

Profile rows show remaining Codex CLI quota beside the name, with window durations, compact meters and reset times on hover. A low window turns its meter orange or red and shows when it resets. The official CLI reads each profile's limits; unavailable readings leave the profile usable. ⌘R refreshes usage. These limits belong to the profile's Codex CLI sign-in; Desktop may use a different account.

The menu follows the system's light/dark appearance, accent colours, contrast, transparency and Reduce Motion preferences, including changes while running.

The app bundles the CLI and supports Apple silicon and Intel. Building needs Swift on macOS; installing the built app needs neither Swift nor a separate codex-profile installation. ChatGPT launches require the official app; Terminal launches and optional CLI sign-in require the official Codex CLI. Desktop and CLI sign-in remain separate.

make menu-dmg creates a disk image with an Applications shortcut and a SHA-256 checksum. Local builds are unsigned development artifacts. This companion is not yet a published release download. See the macOS guide and previews for installation, keyboard controls, and Developer ID signing and notarisation.

How separation works

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.

With Homebrew:

brew install Ducksss/tap/codex-profile

With the standalone installer:

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

With Nix:

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

From source:

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

Then verify the installation:

codex-profile doctor