core-agent-ide

Agent IDE — Codex fork for AI-native development environment

Find a file

Michael Bolin d363a0968e feat: codex-shell-tool-mcp (#7005 ) This adds a GitHub workflow for building a new npm module we are experimenting with that contains an MCP server for running Bash commands. The new workflow, `shell-tool-mcp`, is a dependency of the general `release` workflow so that we continue to use one version number for all artifacts across the project in one GitHub release. `.github/workflows/shell-tool-mcp.yml` is the primary workflow introduced by this PR, which does the following: - builds the `codex-exec-mcp-server` and `codex-execve-wrapper` executables for both arm64 and x64 versions of Mac and Linux (preferring the MUSL version for Linux) - builds Bash (dynamically linked) for a [comically] large number of platforms (both x64 and arm64 for most) with a small patch specified by `shell-tool-mcp/patches/bash-exec-wrapper.patch`: - `debian-11` - `debian-12` - `ubuntu-20.04` - `ubuntu-22.04` - `ubuntu-24.04` - `centos-9` - `macos-13` (x64 only) - `macos-14` (arm64 only) - `macos-15` (arm64 only) - builds the TypeScript for the [new] Node module declared in the `shell-tool-mcp/` folder, which creates `bin/mcp-server.js` - adds all of the native binaries to `shell-tool-mcp/vendor/` folder; `bin/mcp-server.js` does a runtime check to determine which ones to execute - uses `npm pack` to create the `.tgz` for the module - if `publish: true` is set, invokes the `npm publish` call with the `.tgz` The justification for building Bash for so many different operating systems is because, since it is dynamically linked, we want to increase our confidence that the version we build is compatible with the glibc whatever OS we end up running on. (Note this is less of a concern with `codex-exec-mcp-server` and `codex-execve-wrapper` on Linux, as they are statically linked.) This PR also introduces the code for the npm module in `shell-tool-mcp/` (the proposed module name is `@openai/codex-shell-tool-mcp`). Initially, I intended the module to be a single file of vanilla JavaScript (like [`codex-cli/bin/codex.js`](`ab5972d447/codex-cli/bin/codex.js`)), but some of the logic seemed a bit tricky, so I decided to port it to TypeScript and add unit tests. `shell-tool-mcp/src/index.ts` defines the `main()` function for the module, which performs runtime checks to determine the clang triple to find the path to the Rust executables within the `vendor/` folder (`resolveTargetTriple()`). It uses a combination of `readOsRelease()` and `resolveBashPath()` to determine the correct Bash executable to run in the environment. Ultimately, it spawns a command like the following: ``` codex-exec-mcp-server \ --execve codex-execve-wrapper \ --bash custom-bash "$@" ``` Note `.github/workflows/shell-tool-mcp-ci.yml` defines a fairly standard CI job for the module (`format`/`build`/`test`). To test this PR, I pushed this branch to my personal fork of Codex and ran the CI job there: https://github.com/bolinfest/codex/actions/runs/19564311320 Admittedly, the graph looks a bit wild now: <img width="5115" height="2969" alt="Screenshot 2025-11-20 at 11 44 58 PM" src="https://github.com/user-attachments/assets/cc5ef306-efc1-4ed7-a137-5347e394f393" /> But when it finished, I was able to download `codex-shell-tool-mcp-npm` from the Artifacts for the workflow in an empty temp directory, unzip the `.zip` and then the `.tgz` inside it, followed by `xattr -rc .` to remove the quarantine bits. Then I ran: ```shell npx @modelcontextprotocol/inspector node /private/tmp/foobar4/package/bin/mcp-server.js ``` which launched the MCP Inspector and I was able to use it as expected! This bodes well that this should work once the package is published to npm: ```shell npx @modelcontextprotocol/inspector npx @openai/codex-shell-tool-mcp ``` Also, to verify the package contains what I expect: ```shell /tmp/foobar4/package$ tree . ├── bin │ └── mcp-server.js ├── package.json ├── README.md └── vendor ├── aarch64-apple-darwin │ ├── bash │ │ ├── macos-14 │ │ │ └── bash │ │ └── macos-15 │ │ └── bash │ ├── codex-exec-mcp-server │ └── codex-execve-wrapper ├── aarch64-unknown-linux-musl │ ├── bash │ │ ├── centos-9 │ │ │ └── bash │ │ ├── debian-11 │ │ │ └── bash │ │ ├── debian-12 │ │ │ └── bash │ │ ├── ubuntu-20.04 │ │ │ └── bash │ │ ├── ubuntu-22.04 │ │ │ └── bash │ │ └── ubuntu-24.04 │ │ └── bash │ ├── codex-exec-mcp-server │ └── codex-execve-wrapper ├── x86_64-apple-darwin │ ├── bash │ │ └── macos-13 │ │ └── bash │ ├── codex-exec-mcp-server │ └── codex-execve-wrapper └── x86_64-unknown-linux-musl ├── bash │ ├── centos-9 │ │ └── bash │ ├── debian-11 │ │ └── bash │ ├── debian-12 │ │ └── bash │ ├── ubuntu-20.04 │ │ └── bash │ ├── ubuntu-22.04 │ │ └── bash │ └── ubuntu-24.04 │ └── bash ├── codex-exec-mcp-server └── codex-execve-wrapper 26 directories, 26 files ```		2025-11-21 08:16:36 -08:00
.devcontainer	chore: install an extension for TOML syntax highlighting in the devcontainer (#1650 )	2025-07-22 10:58:09 -07:00
.github	feat: codex-shell-tool-mcp (#7005 )	2025-11-21 08:16:36 -08:00
.vscode	Move rust analyzer target dir (#5328 )	2025-10-18 17:31:46 -07:00
codex-cli	detect Bun installs in CLI update banner (#5074 )	2025-10-14 17:49:44 +00:00
codex-rs	Revert "fix: read `max_output_tokens` param from config" (#7088 )	2025-11-21 11:40:02 +01:00
docs	Added feature switch to disable animations in TUI (#6870 )	2025-11-20 10:40:08 -08:00
scripts	fix: ToC so it doesn’t include itself or duplicate the end marker (#4388 )	2025-11-05 14:52:51 -08:00
sdk/typescript	feat(ts-sdk): allow overriding CLI environment (#6648 )	2025-11-14 19:44:19 +00:00
shell-tool-mcp	feat: codex-shell-tool-mcp (#7005 )	2025-11-21 08:16:36 -08:00
.codespellignore	feat: make it possible to toggle mouse mode in the Rust TUI (#971 )	2025-05-16 16:16:50 -07:00
.codespellrc	TypeScript SDK scaffold (#4455 )	2025-09-29 13:27:13 -07:00
.gitignore	nit: personal git ignore (#6787 )	2025-11-17 17:45:52 +00:00
.npmrc	chore: migrate to pnpm for improved monorepo management (#287 )	2025-04-18 16:25:15 -07:00
.prettierignore	[apply-patch] Clean up apply-patch tool definitions (#2539 )	2025-08-21 20:07:41 -07:00
.prettierrc.toml	Initial commit	2025-04-16 12:56:08 -04:00
AGENTS.md	tests: replace mount_sse_once_match with mount_sse_once for SSE mocking (#6640 )	2025-11-13 18:04:05 -08:00
CHANGELOG.md	Documentation improvement: add missing period (#3754 )	2025-10-30 13:01:33 -07:00
cliff.toml	docs(changelog): update install command to @openai/codex@<version> (#2073 )	2025-10-18 11:02:22 -07:00
flake.lock	Fix nix build (#4048 )	2025-10-17 12:19:08 -07:00
flake.nix	Fix nix build (#4048 )	2025-10-17 12:19:08 -07:00
LICENSE	Initial commit	2025-04-16 12:56:08 -04:00
NOTICE	resizable viewport (#1732 )	2025-07-31 00:06:55 +00:00
package.json	chore: subject docs/*.md to Prettier checks (#4645 )	2025-10-03 11:35:48 -07:00
pnpm-lock.yaml	feat: codex-shell-tool-mcp (#7005 )	2025-11-21 08:16:36 -08:00
pnpm-workspace.yaml	feat: codex-shell-tool-mcp (#7005 )	2025-11-21 08:16:36 -08:00
PNPM.md	fix: include pnpm lock file (#377 )	2025-04-18 17:01:11 -07:00
README.md	execpolicycheck command in codex cli (#7012 )	2025-11-20 16:44:31 -05:00

README.md

npm i -g @openai/codex
or brew install --cask codex

Codex CLI is a coding agent from OpenAI that runs locally on your computer.

If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex

Codex CLI splash

Quickstart

Installing and running Codex CLI

Install globally with your preferred package manager. If you use npm:

npm install -g @openai/codex

Alternatively, if you use Homebrew:

brew install --cask codex

Then simply run codex to get started:

codex

If you're running into upgrade issues with Homebrew, see the FAQ entry on brew upgrade codex.

You can also go to the latest GitHub Release and download the appropriate binary for your platform.

Each GitHub Release contains many executables, but in practice, you likely want one of these:

macOS
- Apple Silicon/arm64: codex-aarch64-apple-darwin.tar.gz
- x86_64 (older Mac hardware): codex-x86_64-apple-darwin.tar.gz
Linux
- x86_64: codex-x86_64-unknown-linux-musl.tar.gz
- arm64: codex-aarch64-unknown-linux-musl.tar.gz

Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.

Using Codex with your ChatGPT plan

Codex CLI login

Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.

You can also use Codex with an API key, but this requires additional setup. If you previously used an API key for usage-based billing, see the migration steps. If you're having trouble with login, please comment on this issue.

Model Context Protocol (MCP)

Codex can access MCP servers. To configure them, refer to the config docs.

Configuration

Codex CLI supports a rich set of configuration options, with preferences stored in ~/.codex/config.toml. For full configuration options, see Configuration.

Execpolicy Quickstart

Codex can enforce your own rules-based execution policy before it runs shell commands.

Create a policy directory: mkdir -p ~/.codex/policy.
Create one or more .codexpolicy files in that folder. Codex automatically loads every .codexpolicy file in there on startup.
Write prefix_rule entries to describe the commands you want to allow, prompt, or block:

prefix_rule(
    pattern = ["git", ["push", "fetch"]],
    decision = "prompt",  # allow | prompt | forbidden
    match = [["git", "push", "origin", "main"]],  # examples that must match
    not_match = [["git", "status"]],              # examples that must not match
)

pattern is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (e.g., match both push and fetch).
decision sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow).
match and not_match act as (optional) unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior.

In this example rule, if Codex wants to run commands with the prefix git push or git fetch, it will first ask for user approval.

Use the codex execpolicy check subcommand to preview decisions before you save a rule (see the codex-execpolicy README for syntax details):

codex execpolicy check --policy ~/.codex/policy/default.codexpolicy git push origin main

Pass multiple --policy flags to test how several files combine, and use --pretty for formatted JSON output. See the codex-rs/execpolicy README for a more detailed walkthrough of the available syntax.

Note: `execpolicy` commands are still in preview. The API may have breaking changes in the future.

Docs & FAQ

License

This repository is licensed under the Apache-2.0 License.