codex-wrapper lets one Codex CLI invocation combine multiple named configuration profiles. With zero or one --profile/-p, it passes arguments through unchanged. With multiple profiles, Codex loads the first profile natively; the wrapper reads each later profile from $CODEX_HOME/<name>.config.toml (or ~/.codex/<name>.config.toml) and passes its settings as command-line overrides.
This project is released under the MIT License.
This is an independent community utility. It is not affiliated with or endorsed by OpenAI. It relies on Codex CLI profile and --config behavior. The current sidecar profile layout is described in Codex configuration documentation. A smoke test verified profile loading, overlay merging, and explicit -c precedence with Codex CLI 0.165.0 on macOS with Python 3.12.7; automated acceptance tests use a fake Codex executable. Other CLI versions and operating systems have not been tested manually, and no broader compatibility guarantee is made.
- macOS or Linux with a POSIX shell environment
- Python 3.11 or newer; the wrapper uses only the Python standard library
- uv for installation and local tests
- Codex CLI available as
codexonPATH - Windows is not currently supported.
Install the command with uv:
uv tool install codex-wrapperThe command is installed in an isolated Python environment as codex-wrapper. uv can manage the Python environment for the tool. Ensure uv's tool bin directory (usually ~/.local/bin) is on your PATH:
export PATH="$HOME/.local/bin:$PATH"
command -v codex-wrapper
codex-wrapper --helpAdd the PATH line to your shell startup file (such as ~/.zshrc or ~/.bashrc) to keep it available in new terminals. Update or uninstall the tool with:
uv tool upgrade codex-wrapper
uv tool uninstall codex-wrapperTo run it without a persistent install, use:
uvx codex-wrapperFrom a source checkout, run uv tool install . to try local changes. This installs a uv-managed command shim. If an older version was copied directly to ~/bin/codex-wrapper, remove that old file before using the new installation so PATH does not select it first.
-
Keep task-specific MCP settings in profiles so unrelated tools do not need to be enabled for every session.
-
Use Linear for issue planning and project discussions (Linear MCP docs).
-
Use Braintrust to query production logs, author scorers and prompts, or run evaluations (Braintrust MCP docs).
-
Combine both when a workflow needs planning and evaluation:
codex-wrapper --profile linear --profile braintrust
- Put profile files in
$CODEX_HOMEor~/.codex, named<name>.config.toml. - Set up integrations using the vendor docs, then keep their Codex settings in sidecars such as
linear.config.tomlandbraintrust.config.toml. - Codex loads the first selected profile natively; the wrapper composes later sidecars in order.
- MCP servers from global configuration remain active. Profiles do not isolate tools or create a security boundary.
The later profile recursively merges TOML tables. Later scalar values and arrays replace earlier values; arrays are not concatenated. Explicit -c/--config settings keep Codex's normal CLI precedence over the composed values. The wrapper recognizes profile options before --; everything after -- passes through unchanged.
When using an alternate Codex home, set CODEX_HOME in the environment. Profile files contain regular Codex TOML, and any values from later profiles are placed in the child Codex process's argument list. Avoid putting secrets in those profile values because process inspection tools may expose command arguments. Prefer environment variables or a secret-management integration supported by the configured service.
- If launch reports that it cannot find Codex, install the Codex CLI or add its location to
PATH. - If a later profile is missing or malformed, check that the file is named
<profile>.config.tomlin the active$CODEX_HOMEand contains valid TOML. - The first profile is read by Codex itself. The wrapper reads only later profiles.
Run the focused acceptance suite from the checkout:
make testThe tests use a fake Codex executable and temporary configuration files; they do not require Codex login or network access.
See CONTRIBUTING.md for setup, test, pull request, and maintainer release guidance.
Do not include credentials or private configuration in public issues. If GitHub private vulnerability reporting is enabled for this repository, use its Report a vulnerability flow. If private vulnerability reporting is disabled, open an issue asking the maintainer for a private contact channel. Do not include vulnerability details in that issue.