fxcodex

Independent workspaces and practical extras for Codex on macOS.

fxcodex is an unofficial companion CLI for developers who want to keep personal and work Codex accounts available side by side. It gives each managed workspace an isolated Codex home and desktop-app data directory, carries the same isolation into the Codex CLI, and can optionally preserve the Codex app name.

• Stay signed in to multiple Codex accounts at the same time.
• Open or focus an independent desktop-app instance for each account.
• Run codex and codex exec with the matching isolated profile.
• Manage workspaces from the terminal or generated Raycast Script Commands.
• Optionally rename ChatGPT.app to Codex.app.
• Update the fxcodex executable from verified GitHub Release artifacts.

fxcodex is not affiliated with or endorsed by OpenAI or Raycast.

Table of contents

• How it works
• Requirements
• Installation
  • Brew
  • Download a release
  • Build from source
• Quick start
• Desktop and terminal usage
• Managing workspaces
• App naming
• Updates
• Integration attributes
• Raycast integration
  • Script Commands
  • Extension
• Machine-readable output
• Uninstalling
• Data and privacy
  • Upgrading from 0.1.x to 0.2.y
• Development
• Publishing a release
• License

How it works

A workspace is an isolated Codex profile, not a source-code project or repository.

The built-in primary workspace represents the Codex setup already on the Mac and continues to use Codex's normal data locations. Each additional managed workspace stores its own Codex home and desktop-app data under the fxcodex support directory.

When fxcodex opens the desktop app, it launches or focuses the app instance associated with the requested workspace. When it runs the Codex CLI, it points CODEX_HOME at that workspace's home directory. No account is switched inside Codex itself; each instance simply starts with a different profile.

The current workspace is the default when a command does not include a workspace name. Selecting it does not close or modify instances that are already running, and multiple desktop workspaces can remain open at once.

Requirements

• macOS 14 or later
• The Codex desktop app for fxcodex open
• The codex executable in PATH for fxcodex cli and fxcodex exec
• Swift 6.3 or later only when building from source

Installation

Brew

brew install capturecontext/tap/fxcodex

Download a release

Download these files from the latest GitHub release:

• fxcodex-universal-apple-darwin
• fxcodex-universal-apple-darwin.sha256

The universal executable runs natively on both Apple Silicon and Intel Macs. Smaller architecture-specific aarch64 and x86_64 artifacts are available from the same release.

Verify and install the universal executable:

cd ~/Downloads
shasum -a 256 --check fxcodex-universal-apple-darwin.sha256
install -d "$HOME/.local/bin"
install -m 755 fxcodex-universal-apple-darwin "$HOME/.local/bin/fxcodex"
"$HOME/.local/bin/fxcodex" version

If fxcodex is not found, add this line to ~/.zshrc and start a new shell:

export PATH="$HOME/.local/bin:$PATH"

Release executables are signed with a Developer ID Application certificate, use the hardened runtime and a secure timestamp, and are notarized by Apple.

Build from source

Clone the repository with a Swift 6.3 toolchain available, then run:

make test
make install

make install builds a release executable and installs it to ~/.local/bin/fxcodex. Set PREFIX to choose a different installation prefix.

Quick start

Your existing Codex setup is immediately available as primary. A typical setup keeps the account already signed in to Codex there and creates a managed workspace for another account:

fxcodex workspace create work --use --open

Sign in to the new window with the account for that workspace. Its session and local state remain isolated from primary.

Workspace names must start and end with a lowercase letter or number and may contain lowercase letters, numbers, and hyphens in between.

Open or focus a particular workspace later:

fxcodex open primary
fxcodex open work

Run fxcodex open without a name to choose interactively, or change the default used by commands that omit a workspace name:

fxcodex use work

Inspect the current setup:

fxcodex workspace list
fxcodex status --all

Desktop and terminal usage

Start an interactive Codex CLI session in a workspace:

fxcodex cli work

Run codex exec in a workspace:

fxcodex exec work -- "Review the changes in this repository"

When the workspace name is omitted, both commands use the current workspace:

fxcodex cli
fxcodex exec -- "Summarize this project"

Arguments after -- are forwarded unchanged to codex or codex exec.

Managing workspaces

Task	Command
List workspaces	fxcodex workspace list
Create a workspace	fxcodex workspace create <name>
Create and select it	fxcodex workspace create <name> --use
Create and open it	fxcodex workspace create <name> --open
Open or focus a workspace	fxcodex open [name]
Select the current workspace	fxcodex use [name]
Rename the current managed workspace	fxcodex workspace rename <new-name>
Rename a specified managed workspace	fxcodex workspace rename <old-name> <new-name>
Clear managed workspace data	fxcodex erase [name ...]
Delete managed workspaces and their data	fxcodex delete [name ...]

erase keeps a workspace definition but clears its Codex home, desktop-app data, and integrations. delete removes the managed workspace completely. Both commands require confirmation and only operate on managed workspaces.

Close a workspace's Codex app instance before renaming, erasing, or deleting it. The primary workspace cannot be renamed, erased, or deleted.

App naming

App renaming is optional and independent of workspace isolation. Rename a valid ChatGPT.app immediately:

fxcodex rename

Restore the ChatGPT name:

fxcodex rename --undo

Enable automatic renaming before subsequent commands:

fxcodex preferences set auto-rename true

fxcodex only operates on /Applications/ChatGPT.app and /Applications/Codex.app when the bundle identifier is com.openai.codex. ChatGPT Classic.app, whose bundle identifier is com.openai.chat, is left untouched. If both valid app names exist, fxcodex reports the ambiguity and does not move either bundle.

Running fxcodex rename --undo also disables automatic renaming so a later command does not immediately restore the Codex name. List the current settings with fxcodex preferences.

Updates

fxcodex updates itself from GitHub Releases. Patch updates are the default:

fxcodex update
fxcodex update --minor
fxcodex update --major
fxcodex update --latest

• --patch stays within the current major and minor version.
• --minor stays within the current major version.
• --major selects the newest stable release.
• --latest also considers prereleases.

The updater preserves the current executable kind: a universal installation updates to the universal artifact, while an architecture-specific installation updates to its matching architecture. Every downloaded executable is verified against its published SHA-256 checksum before replacement.

Homebrew-managed installations are updated with brew upgrade fxcodex. fxcodex update and automatic executable replacement intentionally defer to Homebrew for those installations.

Automatic checks run at most once every 24 hours and do not prevent the requested command from running if a check fails. Configure an update policy anchored at a minimum version with:

fxcodex preferences set auto-update --patch-from 1.2.5
fxcodex preferences set auto-update --minor-from 1.5.0
fxcodex preferences set auto-update --major-from 2.0.0
fxcodex preferences set auto-update --latest-from 2.1.0
fxcodex preferences set auto-update --disabled

Patch policies stay within the anchor's major and minor line. Minor policies stay within its major line. Major and latest policies have no upper bound.

Automatic updates apply only to an external fxcodex executable. Applications that bundle fxcodex, such as the companion Raycast extension, manage their bundled executable separately.

Integration attributes

Frontends can store integration-owned JSON values in the shared fxcodex configuration. Read, replace, or remove either an integration root or a nested attribute selected with --path:

fxcodex integrations attributes get raycast --path script_commands
fxcodex integrations attributes set raycast '{"enabled":true}' --path settings
fxcodex integrations attributes remove raycast --path settings

Omitting the integration identifier or value starts guided input in an interactive terminal. Values that parse as JSON retain their JSON type; otherwise, set stores the input as a string.

Raycast integration

Script Commands

fxcodex can install and maintain Raycast Script Commands for quickly opening workspaces. Start the guided setup with:

fxcodex integrations raycast install

Or manage the Script Commands directly:

fxcodex integrations raycast install script-command
fxcodex integrations raycast status
fxcodex integrations raycast sync script-command
fxcodex integrations raycast uninstall script-command

By default, installation creates commands for every workspace and records the integration so commands remain synchronized when workspaces are created, renamed, erased, or deleted. Use --current-only during installation to create only the command for the workspace that is current at installation time. That workspace remains selected by its stable ID if it is renamed; newly created or later-selected workspaces are not added automatically. Reinstall without --current-only to return to automatic all-workspace management. Use --directory <path> to select the Raycast Script Commands directory explicitly.

Extension

A companion Raycast extension provides workspace navigation, management, custom icons, executable selection, and preferences. It is prepared separately for Raycast Store submission; the Script Commands above are available without it.

Machine-readable output

Supported commands can return a versioned JSON envelope for scripts and other integrations:

fxcodex --json status --all
FXCODEX_JSON=1 fxcodex workspace list
fxcodex integrations attributes get raycast --path script_commands --json
fxcodex integrations raycast install script-command \
  --directory "$HOME/.config/raycast/script-commands" \
  --json

Use --no-json to override the environment variable. Interactive selection is disabled when required input is missing in JSON mode, so automation should pass workspace names and confirmation flags explicitly. Attribute commands require an integration identifier, and attributes set also requires a value. JSON get and set responses contain the attribute value; remove returns the integration identifier and removed path. API-owned keys use lower snake case; opaque integration attribute keys are preserved exactly, and integrations are encouraged to use lower snake case for them.

Uninstalling

Run the guided uninstaller and choose whether to keep data, erase managed Codex data while retaining workspace definitions, or remove the complete support directory:

fxcodex uninstall

For non-interactive use, pass --yes together with one of --leave-data, --erase-data, or --delete-data. Managed Raycast Script Commands are removed in every mode. Erasing or deleting data is refused while a managed workspace is running.

If the executable was installed somewhere fxcodex cannot remove itself from, delete it manually after the command completes.

Data and privacy

fxcodex stores its configuration and managed workspaces in:

~/Library/Application Support/fxcodex/
├── configuration.json
├── preferences.json
├── runtime.json
├── storage.lock
├── update-state.json
└── workspaces/
    └── <workspace-id>/
        ├── workspace.json
        ├── codex-home/       # managed workspaces only
        └── user-data/        # managed workspaces only

configuration.json stores the current workspace ID and integration-owned attributes. runtime.json contains transient application-instance records, and workspace.json maps each stable workspace ID to its display name and kind. Some files are created only after their corresponding feature is used.

The primary workspace has metadata under workspaces/, but continues to use Codex's normal data locations. Managed workspace directories contain account-specific Codex state; treat the complete support directory as private data and do not commit or share it.

Upgrading from 0.1.x to 0.2.y

The first 0.2.x command migrates schema 1.0 storage to schema 2.0. In an interactive terminal, fxcodex explains the migration and requests confirmation. Non-interactive callers proceed automatically because the migration does not require additional input.

Close every managed Codex workspace before running the first 0.2.x command. Migration refuses to move a workspace whose recorded Codex process is still running. A live Codex process retains its original CODEX_HOME and user-data paths and can otherwise recreate the legacy name-based directory after it is moved.

The migration assigns stable IDs, moves managed workspace directories from name-based to ID-based paths, converts runtime records and integration attributes, and validates the new storage before continuing. An interrupted migration records its progress in .migration.json and resumes on the next invocation.

Schema 2.0 is not readable by fxcodex 0.1.x. Back up ~/Library/Application Support/fxcodex before upgrading if you may need to return to 0.1.x.

Development

Common development commands are:

make build
make test
make release
make universal

make universal cross-builds the Intel slice with SwiftPM's native build engine so macro plugins remain executable on the Apple Silicon build host. It works with the Swift 6.3 toolchain used by CI and the Swift 6.4 toolchain in Xcode 27; Rosetta is not required.

The package targets macOS 14 and uses Swift 6 language mode. Run fxcodex help <command> or fxcodex <command> --help for the complete CLI reference.

Publishing a release

Release versions use plain semantic versions such as 0.1.0 (without a v prefix). Update the embedded version in Sources/fxcodex-cli/AppCommand.swift, run make test, and push the release-ready commit to main. Then run the Release workflow from GitHub Actions and enter that version.

The workflow pins the release to the selected main commit, verifies that the version matches the executable, resolves one dependency graph for both architectures, builds and tests on Apple Silicon and Intel runners, and signs and notarizes all final executables. After every check succeeds, it creates the tag and publishes the release with post-signing SHA-256 checksum files:

• fxcodex-aarch64-apple-darwin
• fxcodex-x86_64-apple-darwin
• fxcodex-universal-apple-darwin

The release also includes the exact Package.resolved used by both builds. The file stays ignored during normal development; download it alongside GitHub's source archive when reproducing a release.

License

fxcodex is available under the MIT License.