Codex Profile

codex-profile

Small Bash profile manager for the OpenAI Codex CLI.

codex-profile creates separate CODEX_HOME directories for different Codex profiles while linking selected local context from the main profile. The common use case is using a second Codex account or profile without losing access to existing sessions, memories, rules, skills, and MCP configuration.

Authentication and runtime state stay profile-specific. Shared context is linked through symlinks.

Safety

Back up your current Codex home before using this tool:

cp -a "$HOME/.codex" "$HOME/.codex.backup.$(date +%Y%m%d-%H%M%S)"

This project is intended for sequential profile switching. Do not run multiple Codex profiles at the same time when they share sessions/, history.jsonl, or session_index.jsonl; concurrent writes can corrupt local Codex state.

What Gets Shared

Shared from the main Codex home:

sessions/
session_index.jsonl
history.jsonl
memories/
rules/
skills/
shell_snapshots/
AGENTS.md
config.toml
models_cache.json

Kept separate per profile:

auth.json
installation_id
state_*.sqlite
logs_*.sqlite
cache/
log/
tmp/
version.json

The script does not move files out of the main Codex home. It creates symlinks from ~/.codex-shared to the main profile, then from each profile to ~/.codex-shared.

Example:

~/.codex/config.toml
    ^
~/.codex-shared/config.toml -> ~/.codex/config.toml
    ^
~/.codex-profiles/backup/config.toml -> ~/.codex-shared/config.toml

Installation

git clone https://github.com/yalcin/codex-profile.git
cd codex-profile
./install.sh

The installer copies codex-profile to ~/.local/bin/codex-profile by default. Use INSTALL_DIR to choose a different location:

INSTALL_DIR="$HOME/bin" ./install.sh

Make sure the install directory is in your PATH, then verify:

codex-profile help

Usage

Initialize the shared link directory:

codex-profile init

Create a profile:

codex-profile add backup

Log in with that profile:

codex-profile login backup

Run Codex with that profile:

codex-profile run backup

Resume the latest session:

codex-profile resume backup --last

Show all profile paths and shared links:

codex-profile status

Commands

codex-profile init
codex-profile add 
codex-profile list
codex-profile path 
codex-profile login 
codex-profile run  [codex args...]
codex-profile resume  [codex resume args...]
codex-profile status
codex-profile help

Profile names may contain letters, numbers, dots, underscores, and hyphens. main, shared, and default are reserved.

Environment

CODEX_MAIN_HOME     Main Codex home. Default: ~/.codex
CODEX_PROFILE_BASE  Profile directory. Default: ~/.codex-profiles
CODEX_SHARED_HOME   Shared symlink directory. Default: ~/.codex-shared

Example:

CODEX_PROFILE_BASE="$HOME/.local/share/codex-profiles" codex-profile add backup

Aliases

alias codex-main='CODEX_HOME="$HOME/.codex" codex'
alias codex-backup='codex-profile run backup'
alias codex-backup-resume='codex-profile resume backup --last'
alias codex-backup-resume-all='codex-profile resume backup --all'

Per-Profile Config

config.toml is shared by default. To give a profile its own config file, replace the symlink with a real file:

rm "$HOME/.codex-profiles/backup/config.toml"
cp "$HOME/.codex/config.toml" "$HOME/.codex-profiles/backup/config.toml"

Troubleshooting

Check the current setup:

codex-profile status

If a profile cannot see previous sessions, try:

codex-profile resume backup --all

--last resumes the latest session for the current working directory. --all includes sessions from other working directories.

Development

shellcheck codex-profile install.sh
./codex-profile help

Run a local profile smoke test:

CODEX_MAIN_HOME=/tmp/codex-profile-main \
CODEX_PROFILE_BASE=/tmp/codex-profile-profiles \
CODEX_SHARED_HOME=/tmp/codex-profile-shared \
./codex-profile add test

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yalcin
• Source: yalcin/codex-profile
• License: MIT

Install and usage instructions live in the source repository linked above.