codex

[MCP] Add support for resources (#5239 )

This PR adds support for [MCP
resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)
by adding three new tools for the model:
1. `list_resources`
2. `list_resource_templates`
3. `read_resource`

These 3 tools correspond to the [three primary MCP resource protocol
messages](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#protocol-messages).

Example of listing and reading a GitHub resource tempalte
<img width="2984" height="804" alt="CleanShot 2025-10-15 at 17 31 10"
src="https://github.com/user-attachments/assets/89b7f215-2e2a-41c5-90dd-b932ac84a585"
/>

`/mcp` with Figma configured
<img width="2984" height="442" alt="CleanShot 2025-10-15 at 18 29 35"
src="https://github.com/user-attachments/assets/a7578080-2ed2-4c59-b9b4-d8461f90d8ee"
/>

Fixes #4956

Gabriel Peal · 2025-10-17 01:05:15 -04:00

40fba1bb4c

[MCP] Allow specifying cwd and additional env vars (#5246 )

This makes stdio mcp servers more flexible by allowing users to specify
the cwd to run the server command from and adding additional environment
variables to be passed through to the server.

Example config using the test server in this repo:
```toml
[mcp_servers.test_stdio]
cwd = "/Users/<user>/code/codex/codex-rs"
command = "cargo"
args = ["run", "--bin", "test_stdio_server"]
env_vars = ["MCP_TEST_VALUE"]
```

@bolinfest I know you hate these env var tests but let's roll with this
for now. I may take a stab at the env guard + serial macro at some
point.

Gabriel Peal · 2025-10-17 00:24:43 -04:00

bdda762deb

Fix notify documentation to use emitted input-messages key (#5071 )

## Summary
- align the notify configuration example with the CLI payload by reading
the `input-messages` key

Fixes #4954


------
https://chatgpt.com/codex/tasks/task_i_68e95e2be6ec832c8d09d6c65aac7c93

Jeremy Rose · 2025-10-15 23:22:39 -07:00

0139f6780c

[codex][otel] propagate user email in otel events (#5223 )

include user email into otel events for proper user-level attribution in
case of workspace setup

Anton Panasenko · 2025-10-15 17:53:33 -07:00

c146585cdb

feat: pass codex thread ID in notifier metadata (#4582 )

Javi · 2025-10-14 11:55:10 -07:00

13035561cd

fixes #5011 : update mcp server doc (#5014 )

Shijie Rao · 2025-10-10 17:23:41 -07:00

26f7c46856

[MCP] Add an enabled config field (#4917 )

This lets users more easily toggle MCP servers.

Gabriel Peal · 2025-10-08 16:24:51 -04:00

d3820f4782

Fix event names in exec docs. (#4833 )

Fixes: https://github.com/openai/codex/issues

pakrym-oai · 2025-10-06 10:07:52 -07:00

661663c98a

[MCP] Improve docs (#4811 )

Updated, expanded on, clarified, and deduplicated some MCP docs

Gabriel Peal · 2025-10-06 11:43:50 -04:00

721003c552

add codex sandbox {linux|macos} (#4782 )

## Summary
- add a `codex sandbox` subcommand with macOS and Linux targets while
keeping the legacy `codex debug` aliases
- update documentation to highlight the new sandbox entrypoints and
point existing references to the new command
- clarify the core README about the linux sandbox helper alias

## Testing
- just fmt
- just fix -p codex-cli
- cargo test -p codex-cli


------
https://chatgpt.com/codex/tasks/task_i_68e2e00ca1e8832d8bff53aa0b50b49e

Fouad Matin · 2025-10-05 15:51:57 -07:00

77a8b7fdeb

chore: subject docs/*.md to Prettier checks (#4645 )

Apparently we were not running our `pnpm run prettier` check in CI, so
many files that were covered by the existing Prettier check were not
well-formatted.

This updates CI and formats the files.

Michael Bolin · 2025-10-03 11:35:48 -07:00

c32e9cfe86

[MCP] Add support for MCP Oauth credentials (#4517 )

This PR adds oauth login support to streamable http servers when
`experimental_use_rmcp_client` is enabled.

This PR is large but represents the minimal amount of work required for
this to work. To keep this PR smaller, login can only be done with
`codex mcp login` and `codex mcp logout` but it doesn't appear in `/mcp`
or `codex mcp list` yet. Fingers crossed that this is the last large MCP
PR and that subsequent PRs can be smaller.

Under the hood, credentials are stored using platform credential
managers using the [keyring crate](https://crates.io/crates/keyring).
When the keyring isn't available, it falls back to storing credentials
in `CODEX_HOME/.credentials.json` which is consistent with how other
coding agents handle authentication.

I tested this on macOS, Windows, WSL (ubuntu), and Linux. I wasn't able
to test the dbus store on linux but did verify that the fallback works.

One quirk is that if you have credentials, during development, every
build will have its own ad-hoc binary so the keyring won't recognize the
reader as being the same as the write so it may ask for the user's
password. I may add an override to disable this or allow
users/enterprises to opt-out of the keyring storage if it causes issues.

<img width="5064" height="686" alt="CleanShot 2025-09-30 at 19 31 40"
src="https://github.com/user-attachments/assets/9573f9b4-07f1-4160-83b8-2920db287e2d"
/>
<img width="745" height="486" alt="image"
src="https://github.com/user-attachments/assets/9562649b-ea5f-4f22-ace2-d0cb438b143e"
/>

Gabriel Peal · 2025-10-03 13:43:12 -04:00

1d17ca1fa3

feat: codex exec writes only the final message to stdout (#4644 )

This updates `codex exec` so that, by default, most of the agent's
activity is written to stderr so that only the final agent message is
written to stdout. This makes it easier to pipe `codex exec` into
another tool without extra filtering.

I introduced `#![deny(clippy::print_stdout)]` to help enforce this
change and renamed the `ts_println!()` macro to `ts_msg()` because (1)
it no longer calls `println!()` and (2), `ts_eprintln!()` seemed too
long of a name.

While here, this also adds `-o` as an alias for `--output-last-message`.

Fixes https://github.com/openai/codex/issues/1670

Michael Bolin · 2025-10-03 16:22:12 +00:00

042d4d55d9

fix: replace --api-key with --with-api-key in codex login (#4646 )

Previously, users could supply their API key directly via:

```shell
codex login --api-key KEY
```

but this has the drawback that `KEY` is more likely to end up in shell
history, can be read from `/proc`, etc.

This PR removes support for `--api-key` and replaces it with
`--with-api-key`, which reads the key from stdin, so either of these are
better options:

```
printenv OPENAI_API_KEY | codex login --with-api-key
codex login --with-api-key < my_key.txt
```

Other CLIs, such as `gh auth login --with-token`, follow the same
practice.

Michael Bolin · 2025-10-03 06:17:31 +00:00

69ac5153d4

Add a separate exec doc (#4583 )

More/better docs.

pakrym-oai · 2025-10-02 13:33:08 -07:00

b93cc0f431

Fall back to configured instruction files if AGENTS.md isn't available (#4544 )

Allow users to configure an agents.md alternative to consume, but warn
the user it may degrade model performance.

Fixes #4376

easong-openai · 2025-10-01 18:19:59 +00:00

400a5a90bf

fix: separate codex mcp into codex mcp-server and codex app-server (#4471 )

This is a very large PR with some non-backwards-compatible changes.

Historically, `codex mcp` (or `codex mcp serve`) started a JSON-RPC-ish
server that had two overlapping responsibilities:

- Running an MCP server, providing some basic tool calls.
- Running the app server used to power experiences such as the VS Code
extension.

This PR aims to separate these into distinct concepts:

- `codex mcp-server` for the MCP server
- `codex app-server` for the "application server"

Note `codex mcp` still exists because it already has its own subcommands
for MCP management (`list`, `add`, etc.)

The MCP logic continues to live in `codex-rs/mcp-server` whereas the
refactored app server logic is in the new `codex-rs/app-server` folder.
Note that most of the existing integration tests in
`codex-rs/mcp-server/tests/suite` were actually for the app server, so
all the tests have been moved with the exception of
`codex-rs/mcp-server/tests/suite/mod.rs`.

Because this is already a large diff, I tried not to change more than I
had to, so `codex-rs/app-server/tests/common/mcp_process.rs` still uses
the name `McpProcess` for now, but I will do some mechanical renamings
to things like `AppServer` in subsequent PRs.

While `mcp-server` and `app-server` share some overlapping functionality
(like reading streams of JSONL and dispatching based on message types)
and some differences (completely different message types), I ended up
doing a bit of copypasta between the two crates, as both have somewhat
similar `message_processor.rs` and `outgoing_message.rs` files for now,
though I expect them to diverge more in the near future.

One material change is that of the initialize handshake for `codex
app-server`, as we no longer use the MCP types for that handshake.
Instead, we update `codex-rs/protocol/src/mcp_protocol.rs` to add an
`Initialize` variant to `ClientRequest`, which takes the `ClientInfo`
object we need to update the `USER_AGENT_SUFFIX` in
`codex-rs/app-server/src/message_processor.rs`.

One other material change is in
`codex-rs/app-server/src/codex_message_processor.rs` where I eliminated
a use of the `send_event_as_notification()` method I am generally trying
to deprecate (because it blindly maps an `EventMsg` into a
`JSONNotification`) in favor of `send_server_notification()`, which
takes a `ServerNotification`, as that is intended to be a custom enum of
all notification types supported by the app server. So to make this
update, I had to introduce a new variant of `ServerNotification`,
`SessionConfigured`, which is a non-backwards compatible change with the
old `codex mcp`, and clients will have to be updated after the next
release that contains this PR. Note that
`codex-rs/app-server/tests/suite/list_resume.rs` also had to be update
to reflect this change.

I introduced `codex-rs/utils/json-to-toml/src/lib.rs` as a small utility
crate to avoid some of the copying between `mcp-server` and
`app-server`.

Michael Bolin · 2025-09-30 07:06:18 +00:00

d9dbf48828

Update MCP docs to reference experimental RMCP client (#4422 )

Gabriel Peal · 2025-09-30 02:44:16 -04:00

2e95e5602d

Custom prompt args (numeric) (#4470 )

[Cherry picked from /pull/3565]

Adds $1, $2, $3, $ARGUMENTS param parsing for custom prompts.

dedrisian-oai · 2025-09-29 16:14:37 -07:00

80ccec6530

OpenTelemetry events (#2103 )

### Title

## otel

Codex can emit [OpenTelemetry](https://opentelemetry.io/) **log events**
that
describe each run: outbound API requests, streamed responses, user
input,
tool-approval decisions, and the result of every tool invocation. Export
is
**disabled by default** so local runs remain self-contained. Opt in by
adding an
`[otel]` table and choosing an exporter.

```toml
[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"          # defaults to "none"; set to otlp-http or otlp-grpc to send events
log_user_prompt = false    # defaults to false; redact prompt text unless explicitly enabled
```

Codex tags every exported event with `service.name = "codex-cli"`, the
CLI
version, and an `env` attribute so downstream collectors can distinguish
dev/staging/prod traffic. Only telemetry produced inside the
`codex_otel`
crate—the events listed below—is forwarded to the exporter.

### Event catalog

Every event shares a common set of metadata fields: `event.timestamp`,
`conversation.id`, `app.version`, `auth_mode` (when available),
`user.account_id` (when available), `terminal.type`, `model`, and
`slug`.

With OTEL enabled Codex emits the following event types (in addition to
the
metadata above):

- `codex.api_request`
  - `cf_ray` (optional)
  - `attempt`
  - `duration_ms`
  - `http.response.status_code` (optional)
  - `error.message` (failures)
- `codex.sse_event`
  - `event.kind`
  - `duration_ms`
  - `error.message` (failures)
  - `input_token_count` (completion only)
  - `output_token_count` (completion only)
  - `cached_token_count` (completion only, optional)
  - `reasoning_token_count` (completion only, optional)
  - `tool_token_count` (completion only)
- `codex.user_prompt`
  - `prompt_length`
  - `prompt` (redacted unless `log_user_prompt = true`)
- `codex.tool_decision`
  - `tool_name`
  - `call_id`
- `decision` (`approved`, `approved_for_session`, `denied`, or `abort`)
  - `source` (`config` or `user`)
- `codex.tool_result`
  - `tool_name`
  - `call_id`
  - `arguments`
  - `duration_ms` (execution time for the tool)
  - `success` (`"true"` or `"false"`)
  - `output`

### Choosing an exporter

Set `otel.exporter` to control where events go:

- `none` – leaves instrumentation active but skips exporting. This is
the
  default.
- `otlp-http` – posts OTLP log records to an OTLP/HTTP collector.
Specify the
  endpoint, protocol, and headers your collector expects:

  ```toml
  [otel]
  exporter = { otlp-http = {
    endpoint = "https://otel.example.com/v1/logs",
    protocol = "binary",
    headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
  }}
  ```

- `otlp-grpc` – streams OTLP log records over gRPC. Provide the endpoint
and any
  metadata headers:

  ```toml
  [otel]
  exporter = { otlp-grpc = {
    endpoint = "https://otel.example.com:4317",
    headers = { "x-otlp-meta" = "abc123" }
  }}
  ```

If the exporter is `none` nothing is written anywhere; otherwise you
must run or point to your
own collector. All exporters run on a background batch worker that is
flushed on
shutdown.

If you build Codex from source the OTEL crate is still behind an `otel`
feature
flag; the official prebuilt binaries ship with the feature enabled. When
the
feature is disabled the telemetry hooks become no-ops so the CLI
continues to
function without the extra dependencies.

---------

Co-authored-by: Anton Panasenko <apanasenko@openai.com>

vishnu-oai · 2025-09-29 11:30:55 -07:00

04c1782e52

fix typo in sandbox doc (#4256 )

just fixes a simple typo I noticed.

iceweasel-oai · 2025-09-25 16:03:44 -07:00

38c9d7dca1

feat: update default (#4076 )

Changes:
- Default model and docs now use gpt-5-codex. 
- Disables the GPT-5 Codex NUX by default.
- Keeps presets available for API key users.

Thibault Sottiaux · 2025-09-22 20:10:52 -07:00

c93e77b68b

timeouts for mcp tool calls (#3959 )

defaults to 60sec, overridable with MCP_TOOL_TIMEOUT or on a per-server
basis in the config.

Jeremy Rose · 2025-09-22 10:30:59 -07:00

19f46439ae

fix: make GitHub Action publish to npm using trusted publishing (#3431 )

Michael Bolin · 2025-09-16 20:33:59 -07:00

791d7b125f

Update azure model provider example (#3680 )

Make the section linkable.

pakrym-oai · 2025-09-16 08:43:29 -07:00

5e2c4f7e35

notifications on approvals and turn end (#3329 )

uses OSC 9 to notify when a turn ends or approval is required. won't
work in vs code or terminal.app but iterm2/kitty/wezterm supports it :)

Jeremy Rose · 2025-09-15 10:22:02 -07:00

0560079c41

initial mcp add interface (#3543 )

Adds `codex mcp add`, `codex mcp list`, `codex mcp remove`. Currently writes to global config.

easong-openai · 2025-09-15 04:30:56 +00:00

6a8e743d57

enable-resume (#3537 )

Adding the ability to resume conversations.
we have one verb `resume`. 

Behavior:

`tui`:
`codex resume`: opens session picker
`codex resume --last`: continue last message
`codex resume <session id>`: continue conversation with `session id`

`exec`:
`codex resume --last`: continue last conversation
`codex resume <session id>`: continue conversation with `session id`

Implementation:
- I added a function to find the path in `~/.codex/sessions/` with a
`UUID`. This is helpful in resuming with session id.
- Added the above mentioned flags
- Added lots of testing

Ahmed Ibrahim · 2025-09-14 19:33:19 -04:00

a30e5e40ee

MCP Documentation Changes Requests in Code Review (#3507 )

Add in review changes from @bolinfest that were dropped due to
auto-merge (#3345).

Charlie Weems · 2025-09-12 09:04:49 -07:00

f805d17930

Add more detailed documentation on MCP server usage (#3345 )

Adds further information on how to get started with `codex mcp`:
- Tool details and parameter references
- Quickstart with example using MCP inspector.

Charlie Weems · 2025-09-11 14:38:24 -07:00

8f7b22b652

Simplify auth flow and reconcile differences between ChatGPT and API Key auth (#3189 )

This PR does the following:
* Adds the ability to paste or type an API key.
* Removes the `preferred_auth_method` config option. The last login
method is always persisted in auth.json, so this isn't needed.
* If OPENAI_API_KEY env variable is defined, the value is used to
prepopulate the new UI. The env variable is otherwise ignored by the
CLI.
* Adds a new MCP server entry point "login_api_key" so we can implement
this same API key behavior for the VS Code extension.
<img width="473" height="140" alt="Screenshot 2025-09-04 at 3 51 04 PM"
src="https://github.com/user-attachments/assets/c11bbd5b-8a4d-4d71-90fd-34130460f9d9"
/>
<img width="726" height="254" alt="Screenshot 2025-09-04 at 3 51 32 PM"
src="https://github.com/user-attachments/assets/6cc76b34-309a-4387-acbc-15ee5c756db9"
/>

Eric Traut · 2025-09-11 09:16:34 -07:00

e13b35ecb0

Remove a broken link to prompting_guide.md in docs/getting-started.md (#2858 )

The file no longer exists. We've been receiving this feedback several
times.
- https://github.com/openai/codex/issues/2374
- https://github.com/openai/codex/issues/2810
- https://github.com/openai/codex/issues/2826

My previous PR https://github.com/openai/codex/pull/2413 for this issue
restored the file but now it's compatible with the current file
structure. Thus, let's simply delete the link.

Kazuhiro Sera · 2025-09-10 10:52:50 -07:00

97338de578

Improve explanation of how the shell handles quotes in config.md (#3169 )

* Clarify how the shell's handling of quotes affects the interpretation
of TOML values in `--config`/`-c`
* Provide examples of the right way to pass complex TOML values
* The previous explanation incorrectly demonstrated how to pass TOML
values to `--config`/`-c` (misunderstanding how the shell’s handling of
quotes affects things) and would result in invalid invocations of
`codex`.

Robert · 2025-09-08 15:58:25 -07:00

79cbd2ab1b

feat(mcp): per-server startup timeout (#3182 )

Seeing timeouts on certain, slow mcp server starting up when codex is
invoked. Before this change, the timeout was a hard-coded 10s. Need the
ability to define arbitrary timeouts on a per-server basis.

## Summary of changes

- Add startup_timeout_ms to McpServerConfig with 10s default when unset
- Use per-server timeout for initialize and tools/list
- Introduce ManagedClient to store client and timeout; rename
LIST_TOOLS_TIMEOUT to DEFAULT_STARTUP_TIMEOUT
- Update docs to document startup_timeout_ms with example and options
table

---------

Co-authored-by: Matthew Dolan <dolan-openai@users.noreply.github.com>

dolan · 2025-09-08 08:12:08 -07:00

6efb52e545

fix: change create_github_release to take either --publish-alpha or --publish-release (#3231 )

No more picking out version numbers by hand! Now we let the script do
it:

```
$ ./codex-rs/scripts/create_github_release --dry-run --publish-alpha
Running gh api GET /repos/openai/codex/releases/latest
Running gh api GET /repos/openai/codex/releases?per_page=100
Publishing version 0.31.0-alpha.3
$ ./codex-rs/scripts/create_github_release --dry-run --publish-release
Running gh api GET /repos/openai/codex/releases/latest
Publishing version 0.31.0
```

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/3230).
* __->__ #3231
* #3230
* #3228
* #3226

Michael Bolin · 2025-09-05 22:08:34 -07:00

70a6d4b1b4

hide resume until it's complete (#3218 )

Hide resume functionality until it's fully done.

Ahmed Ibrahim · 2025-09-05 13:12:46 -07:00

c11696f6b1

Never store requests (#3212 )

When item ids are sent to Responses API it will load them from the
database ignoring the provided values. This adds extra latency.

Not having the mode to store requests also allows us to simplify the
code.

## Breaking change

The `disable_response_storage` configuration option is removed.

pakrym-oai · 2025-09-05 10:41:47 -07:00

5775174ec2

[codex] move configuration for reasoning summary format to model family config type (#3171 )

Anton Panasenko · 2025-09-04 11:00:01 -07:00

e60a44cbab

TUI: Add session resume picker (--resume) and quick resume (--continue) (#3135 )

Adds a TUI resume flow with an interactive picker and quick resume.

- CLI: 
  - --resume / -r: open picker to resume a prior session
  - --continue   / -l: resume the most recent session (no picker)
- Behavior on resume: initial history is replayed, welcome banner
hidden, and the first redraw is suppressed to avoid flicker.
- Implementation:
- New tui/src/resume_picker.rs (paginated listing via
RolloutRecorder::list_conversations)
  - App::run accepts ResumeSelection; resumes from disk when requested
- ChatWidget refactor with ChatWidgetInit and new_from_existing; replays
initial messages
- Tests: cover picker sorting/preview extraction and resumed-history
rendering.
- Docs: getting-started updated with flags and picker usage.



https://github.com/user-attachments/assets/1bb6469b-e5d1-42f6-bec6-b1ae6debda3b

Ahmed Ibrahim · 2025-09-04 06:20:40 +00:00

234c0a0469

[codex] document use_experimental_reasoning_summary toml key config (#3118 )

Follow up on https://github.com/openai/codex/issues/3101

Anton Panasenko · 2025-09-03 11:16:07 -07:00

77fb9f3465

Update guidance on API key permissions (#3112 )

Fixes https://github.com/openai/codex/issues/3108

Gabriel Peal · 2025-09-03 12:44:16 -04:00

fb5dfe3396

docs: fix typo of config.md (#3082 )

Fixed a typo in config.md. I guess TOML doesn't have the “key”: “value”
syntax.

Zhongsheng Ji · 2025-09-02 23:14:57 -07:00

3f76220055

docs: update link to point to https://agents.md/ (#3089 )

Given the link text is "official AGENTS.md documentation," this seems
like the right URL.

Michael Bolin · 2025-09-02 23:13:04 -07:00

90725fe3d5

fix config reference table (#3063 )

3 quick fixes to docs/config.md

- Fix the reference table so option lists render correctly
- Corrected the default `stream_max_retries` to 5 (Old: 10)
- Update example approval_policy to untrusted (Old: unless-allow-listed)

Reuben Narad · 2025-09-02 13:03:11 -07:00

7bcdc5cc7c

Custom /prompts (#2696 )

Adds custom `/prompts` to `~/.codex/prompts/<command>.md`.

<img width="239" height="107" alt="Screenshot 2025-08-25 at 6 22 42 PM"
src="https://github.com/user-attachments/assets/fe6ebbaa-1bf6-49d3-95f9-fdc53b752679"
/>

---

Details:

1. Adds `Op::ListCustomPrompts` to core.
2. Returns `ListCustomPromptsResponse` with list of `CustomPrompt`
(name, content).
3. TUI calls the operation on load, and populates the custom prompts
(excluding prompts that collide with builtins).
4. Selecting the custom prompt automatically sends the prompt to the
agent.

dedrisian-oai · 2025-08-29 02:16:39 +00:00

b8e8454b3f

README / docs refactor (#2724 )

This PR cleans up the monolithic README by breaking it into a set
navigable pages under docs/ (install, getting started, configuration,
authentication, sandboxing and approvals, platform details, FAQ, ZDR,
contributing, license). The top‑level README is now more concise and
intuitive, (with corrected screenshots).

It also consolidates overlapping content from codex-rs/README.md into
the top‑level docs and updates links accordingly. The codex-rs README
remains in place for now as a pointer and for continuity.

Finally, added an extensive config reference table at the bottom of
docs/config.md.

---------

Co-authored-by: easong-openai <easong@openai.com>

Reuben Narad · 2025-08-27 10:30:39 -07:00

459363e17b

fix: improve npm release process (#2055 )

This improves the release process by introducing
`scripts/publish_to_npm.py` to automate publishing to npm (modulo the
human 2fac step).

As part of this, it updates `.github/workflows/rust-release.yml` to
create the artifact for npm using `npm pack`.

And finally, while it is long overdue, this memorializes the release
process in `docs/release_management.md`.

Michael Bolin · 2025-08-08 19:07:36 -07:00

e87974ae83

Set up CLA process and remove DCO (#129 )

Signed-off-by: Ilan Bigio <ilan@openai.com>

Ilan Bigio · 2025-04-16 15:24:31 -07:00

50925c0d6c

48 Commits