codex-isolate

codex-isolate is an isolated-home launcher for Codex with multi-account support.

It keeps the original codex command and ~/.codex home untouched, while managing additional isolates under ~/.codex-isolate/isolates/<name>.

Purpose

codex-isolate is for people who want to:

• keep the original codex workflow unchanged
• sign in to more than one Codex account on the same machine
• launch separate Codex isolate homes in parallel
• install optional shell wrappers such as codex2 without overriding codex

This project is a launcher and isolate manager. It is not a Codex plugin, and it does not patch the original Codex executable.

Requirements

• Node.js >=22
• An existing codex installation available in PATH
• A default Codex home at ~/.codex

Install

npm install -g @captain-pam/codex-isolate

Install from the local source tree:

cd /path/to/codex-isolate
npm install
npm run build
npm install -g .

How It Works

• codex stays the original command
• ~/.codex stays the original Codex home
• codex-isolate only manages extra isolates such as codex2, codex3, or custom names like work
• managed isolates live under ~/.codex-isolate/isolates/<name>
• stable configuration is linked from ~/.codex
• login state, sessions, history, and runtime files stay isolated per managed isolate

Design Overview

flowchart LR
  User[User] --> CLI["codex-isolate run work"]
  CLI -->|spawns| Codex["original codex"]
  Codex -->|CODEX_HOME| Isolate["~/.codex-isolate/isolates/work"]

  Source["~/.codex"] -->|shared symlinks| Shared["skills
superpowers
config.toml
AGENTS.md"]
  Shared -. mounted into .-> Isolate

  Isolate --> State["auth.json
accounts/
sessions/
history.jsonl
log/
state_*.sqlite"]

  Source --> Unchanged["default codex setup stays unchanged"]

Loading

The launcher only redirects CODEX_HOME for the selected isolate. Shared configuration is linked from ~/.codex, while login state and runtime data remain isolated per managed home.

Quick Start

Create the next managed isolate:

codex-isolate isolate add

Create a named isolate:

codex-isolate isolate add work

Log into that isolate:

codex-isolate login codex2 --device-auth

Run Codex with that isolate:

codex-isolate run codex2
codex-isolate run work -- --full-auto

List and inspect local isolate status:

codex-isolate isolate list
codex-isolate isolate show work
codex-isolate doctor

Remove a managed isolate:

codex-isolate isolate remove work

Command Summary

• codex-isolate isolate add [name] Create a managed isolate. Auto-generated names start at codex2.
• codex-isolate isolate list Show all managed isolates and whether they are logged in or shell-enabled.
• codex-isolate isolate show <name> Show one isolate in detail.
• codex-isolate isolate remove <name> Remove one managed isolate.
• codex-isolate login <name> [--device-auth] Run codex login inside the selected managed isolate home.
• codex-isolate run <name> [-- <codex args...>] Launch the original codex with CODEX_HOME redirected to the selected isolate.
• codex-isolate install-shell Install wrapper functions for the current bash or zsh shell.
• codex-isolate uninstall-shell Remove only the wrapper block added by codex-isolate.
• codex-isolate doctor Check whether codex is available, shared source files exist, and isolate links are intact.

Shell Integration

Install shell wrappers for the current bash or zsh shell:

codex-isolate install-shell
source ~/.bashrc

For zsh:

codex-isolate install-shell
source ~/.zshrc

After installation, managed isolate names can be called directly:

codex2
work-team --full-auto

After installing shell wrappers, managed isolate names such as codex2 or work-team can be called directly. The original codex command is never overridden.

What Gets Shared vs Isolated

Shared from ~/.codex into each managed isolate:

• skills
• superpowers
• config.toml
• AGENTS.md

Isolated per managed isolate:

• auth.json
• accounts/
• sessions/
• history.jsonl
• log/
• runtime SQLite state

Example Workflow

codex
codex-isolate isolate add
codex-isolate login codex2 --device-auth
codex-isolate run codex2
codex-isolate install-shell
source ~/.bashrc
codex2

Safety

• codex-isolate never replaces the original codex executable
• codex-isolate never takes ownership of ~/.codex
• shell integration only adds managed isolate wrappers
• removing one managed isolate does not modify the default Codex home

Development

npm install
npm test
npm run build