codex-wrapper
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.
Requirements
- 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
Install the command with uv:
uv tool install codex-wrapper
The 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 --help
Add 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-wrapper
To run it without a persistent install, use:
uvx codex-wrapper
From 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.
Why combine profiles?
-
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
Configure and run
- 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.
Troubleshooting
- 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.
Verify changes
Run the focused acceptance suite from the checkout:
make test
The tests use a fake Codex executable and temporary configuration files; they do not require Codex login or network access.
Contributing
See CONTRIBUTING.md for setup, test, pull request, and maintainer release guidance.
Security reports
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.
Metadata
Release files for codex-wrapper 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codex_wrapper-0.1.0.tar.gz | 16.3 kB | With provenance | Details for codex_wrapper-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codex_wrapper-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for codex_wrapper-0.1.0-py3-none-any.whl |
Total release size: 25.2 kB
Release files / codex_wrapper-0.1.0.tar.gz
| Download URL | codex_wrapper-0.1.0.tar.gz |
|---|---|
| Size | 16.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca20265248ec415b112ec3490c141c69454144375ad1267a001b4e523a8f514e
|
|
BLAKE2b-256 checksum How to use checksums |
117d339cac1ae13d10b5bd5db89e6510877da09fa24a2164865a3caa3e22fcef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logRelease files / codex_wrapper-0.1.0-py3-none-any.whl
| Download URL | codex_wrapper-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8bc2c28e7721346a0b901964c4867caecb902d57477786b7385a0774258acfe3
|
|
BLAKE2b-256 checksum How to use checksums |
88d36a08d5aa85a418f9afa88dd62ab67cbe3e40db7eb999b7906043e6cb3ab7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logSecurity for codex-wrapper 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for codex_wrapper-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.