Skip to main content

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 codex on PATH
  • 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_HOME or ~/.codex, named <name>.config.toml.
  • Set up integrations using the vendor docs, then keep their Codex settings in sidecars such as linear.config.toml and braintrust.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.toml in the active $CODEX_HOME and 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)

Source distribution for codex-wrapper 0.1.0
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)

Table of built distributions (wheels) for codex-wrapper 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page