codex

Documentation improvement: add missing period (#3754 )

Pull request template, minimal:

---

### **What?**

Minor change (low-hanging fruit).

### **Why?**

To improve code quality or documentation with minimal risk and effort.

### **How?**

Edited directly via VSCode Editor.

---

**Checklist (pre-PR):**

* [x] I have read the CLA Document and hereby sign the CLA.
* [x] I reviewed the “Contributing” markdown file for this project.

*This template meets standard external (non-OpenAI) PR requirements and
signals compliance for maintainers.*

Co-authored-by: Eric Traut <etraut@openai.com>

Brad M. Harris · 2025-10-30 13:01:33 -07:00

8b8be343a7

[app-server] remove serde(skip_serializing_if = "Option::is_none") annotations (#5939 )

We had this annotation everywhere in app-server APIs which made it so
that fields get serialized as `field?: T`, meaning if the field as
`None` we would omit the field in the payload. Removing this annotation
changes it so that we return `field: T | null` instead, which makes
codex app-server's API more aligned with the convention of public OpenAI
APIs like Responses.

Separately, remove the `#[ts(optional_fields = nullable)]` annotations
that were recently added which made all the TS types become `field?: T |
null` which is not great since clients need to handle undefined and
null.

I think generally it'll be best to have optional types be either:
- `field: T | null` (preferred, aligned with public OpenAI APIs)
- `field?: T` where we have to, such as types generated from the MCP
schema:
https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts
(see changes to `mcp-types/`)

I updated @etraut-openai's unit test to check that all generated TS
types are one or the other, not both (so will error if we have a type
that has `field?: T | null`). I don't think there's currently a good use
case for that - but we can always revisit.

Owen Lin · 2025-10-30 18:18:53 +00:00

89c00611c2

[codex] add developer instructions (#5897 )

we are using developer instructions for code reviews, we need to pass
them in cli as well.

Anton Panasenko · 2025-10-30 11:18:31 -07:00

9572cfc782

chore: testing on freeform apply_patch (#5952 )

## Summary
Duplicates the tests in `apply_patch_cli.rs`, but tests the freeform
apply_patch tool as opposed to the function call path. The good news is
that all the tests pass with zero logical tests, with the exception of
the heredoc, which doesn't really make sense in the freeform tool
context anyway.

@jif-oai since you wrote the original tests in #5557, I'd love your
opinion on the right way to DRY these test cases between the two. Happy
to set up a more sophisticated harness, but didn't want to go down the
rabbit hole until we agreed on the right pattern

## Testing
- [x] These are tests

Dylan Hurd · 2025-10-30 10:40:48 -07:00

4a55646a02

nit: log rmcp_client (#5978 )

jif-oai · 2025-10-30 17:40:38 +00:00

209af68611

feat: compaction prompt configurable (#5959 )

```
 codex -c compact_prompt="Summarize in bullet points"
 ```

jif-oai · 2025-10-30 14:24:24 +00:00

f4f9695978

Pass initial history as an optional to codex delegate (#5950 )

This will give us more freedom on controlling the delegation. i.e we can
fork our history and run `compact`.

Ahmed Ibrahim · 2025-10-30 07:22:42 -07:00

5fcc380bd9

chore: unify config crates (#5958 )

jif-oai · 2025-10-30 10:28:32 +00:00

aa76003e28

Send delegate header (#5942 )

Send delegate type header

Ahmed Ibrahim · 2025-10-30 09:49:40 +00:00

fac548e430

Add debug-only slash command for rollout path (#5936 )

## Summary
- add a debug-only `/rollout` slash command that prints the rollout file
path or reports when none is known
- surface the new command in the slash command metadata and cover it
with unit tests

<img width="539" height="99" alt="image"
src="https://github.com/user-attachments/assets/688e1334-8a06-4576-abb8-ada33b458661"
/>

Ahmed Ibrahim · 2025-10-30 03:51:00 +00:00

9bd3453592

asdf (#5940 )

zhao-oai · 2025-10-30 01:10:41 +00:00

b34efde2f3

ignore agent message deltas for the review mode (#5937 )

The deltas produce the whole json output. ignore them.

Ahmed Ibrahim · 2025-10-30 00:47:55 +00:00

7aa46ab5fc

Re-enable SDK image forwarding test (#5934 )

## Summary
- re-enable the TypeScript SDK test that verifies local images are
forwarded to `codex exec`

## Testing
- `pnpm test` *(fails: unable to download pnpm 10.8.1 because external
network access is blocked in the sandbox)*

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

pakrym-oai · 2025-10-29 23:18:26 +00:00

bf35105af6

Add item streaming events (#5546 )

Adds AgentMessageContentDelta, ReasoningContentDelta,
ReasoningRawContentDelta item streaming events while maintaining
compatibility for old events.

---------

Co-authored-by: Owen Lin <owen@openai.com>

pakrym-oai · 2025-10-29 22:33:57 +00:00

3429e82e45

[exec] Add MCP tool arguments and results (#5899 )

Extends mcp_tool_call item to include arguments and results.

pakrym-oai · 2025-10-29 14:23:57 -07:00

815ae4164a

Delegate review to codex instance (#5572 )

In this PR, I am exploring migrating task kind to an invocation of
Codex. The main reason would be getting rid off multiple
`ConversationHistory` state and streamlining our context/history
management.

This approach depends on opening a channel between the sub-codex and
codex. This channel is responsible for forwarding `interactive`
(`approvals`) and `non-interactive` events. The `task` is responsible
for handling those events.

This opens the door for implementing `codex as a tool`, replacing
`compact` and `review`, and potentially subagents.

One consideration is this code is very similar to `app-server` specially
in the approval part. If in the future we wanted an interactive
`sub-codex` we should consider using `codex-mcp`

Ahmed Ibrahim · 2025-10-29 21:04:25 +00:00

13e1d0362d

chore: config editor (#5878 )

The goal is to have a single place where we actually write files

In a follow-up PR, will move everything config related in a dedicated
module and move the helpers in a dedicated file

jif-oai · 2025-10-29 20:52:46 +00:00

db31f6966d

fix: icu_decimal version (#5919 )

jif-oai · 2025-10-29 20:46:45 +00:00

2b20cd66af

Add a wrapper around raw response items (#5923 )

We currently have nested enums when sending raw response items in the
app-server protocol. This makes downstream schemas confusing because we
need to embed `type`-discriminated enums within each other.

This PR adds a small wrapper around the response item so we can keep the
schemas separate

Rasmus Rygaard · 2025-10-29 20:32:40 +00:00

39e09c289d

Add missing "nullable" macro to protocol structs that contain optional fields (#5901 )

This PR addresses a current hole in the TypeScript code generation for
the API server protocol. Fields that are marked as "Optional<>" in the
Rust code are serialized such that the value is omitted when it is
deserialized — appearing as `undefined`, but the TS type indicates
(incorrectly) that it is always defined but possibly `null`. This can
lead to subtle errors that the TypeScript compiler doesn't catch. The
fix is to include the `#[ts(optional_fields = nullable)]` macro for all
protocol structs that contain one or more `Optional<>` fields.

This PR also includes a new test that validates that all TS protocol
code containing "| null" in its type is marked optional ("?") to catch
cases where `#[ts(optional_fields = nullable)]` is omitted.

Eric Traut · 2025-10-29 12:09:47 -07:00

069a38a06c

feat: add output even in sandbox denied (#5908 )

jif-oai · 2025-10-29 18:21:18 +00:00

3183935bd7

feat: deprecation warning (#5825 )

<img width="955" height="311" alt="Screenshot 2025-10-28 at 14 26 25"
src="https://github.com/user-attachments/assets/99729b3d-3bc9-4503-aab3-8dc919220ab4"
/>

jif-oai · 2025-10-29 12:29:28 +00:00

060637b4d4

chore: merge git crates (#5909 )

Merge `git-apply` and `git-tooling` into `utils/`

jif-oai · 2025-10-29 12:11:44 +00:00

fa92cd92fa

feature: Add "!cmd" user shell execution (#2471 )

feature: Add "!cmd" user shell execution

This change lets users run local shell commands directly from the TUI by
prefixing their input with ! (e.g. !ls). Output is truncated to keep the
exec cell usable, and Ctrl-C cleanly
  interrupts long-running commands (e.g. !sleep 10000).

**Summary of changes**

- Route Op::RunUserShellCommand through a dedicated UserShellCommandTask
(core/src/tasks/user_shell.rs), keeping the task logic out of codex.rs.
- Reuse the existing tool router: the task constructs a ToolCall for the
local_shell tool and relies on ShellHandler, so no manual MCP tool
lookup is required.
- Emit exec lifecycle events (ExecCommandBegin/ExecCommandEnd) so the
TUI can show command metadata, live output, and exit status.

**End-to-end flow**

  **TUI handling**

1. ChatWidget::submit_user_message (TUI) intercepts messages starting
with !.
2. Non-empty commands dispatch Op::RunUserShellCommand { command };
empty commands surface a help hint.
3. No UserInput items are created, so nothing is enqueued for the model.

  **Core submission loop**
4. The submission loop routes the op to handlers::run_user_shell_command
(core/src/codex.rs).
5. A fresh TurnContext is created and Session::spawn_user_shell_command
enqueues UserShellCommandTask.

  **Task execution**
6. UserShellCommandTask::run emits TaskStartedEvent, formats the
command, and prepares a ToolCall targeting local_shell.
  7. ToolCallRuntime::handle_tool_call dispatches to ShellHandler.

  **Shell tool runtime**
8. ShellHandler::run_exec_like launches the process via the unified exec
runtime, honoring sandbox and shell policies, and emits
ExecCommandBegin/End.
9. Stdout/stderr are captured for the UI, but the task does not turn the
resulting ToolOutput into a model response.

  **Completion**
10. After ExecCommandEnd, the task finishes without an assistant
message; the session marks it complete and the exec cell displays the
final output.

  **Conversation context**

- The command and its output never enter the conversation history or the
model prompt; the flow is local-only.
  - Only exec/task events are emitted for UI rendering.

**Demo video**


https://github.com/user-attachments/assets/fcd114b0-4304-4448-a367-a04c43e0b996

Abhishek Bhardwaj · 2025-10-29 00:31:20 -07:00

89591e4246

Fix bash detection failure in VS Code Codex extension on Windows under certain conditions (#3421 )

Found that the VS Code Codex extension throws “Error starting
conversation” when initializing a conversation with Git for Windows’
bash on PATH.
Debugging showed the bash-detection logic did not return as expected;
this change makes it reliable in that scenario.
Possibly related to issue #2841.

Axojhf · 2025-10-28 21:29:16 -07:00

802d2440b4

fix(windows-path): preserve PATH order; include core env vars (#5579 )

# Preserve PATH precedence & fix Windows MCP env propagation

## Problem & intent

Preserve user PATH precedence and reduce Windows setup friction for MCP
servers by avoiding PATH reordering and ensuring Windows child processes
receive essential env vars.

- Addresses: #4180 #5225 #2945 #3245 #3385 #2892 #3310 #3457 #4370  
- Supersedes: #4182, #3866, #3828 (overlapping/inferior once this
merges)
- Notes: #2626 / #2646 are the original PATH-mutation sources being
corrected.

---

## Before / After

**Before**  
- PATH was **prepended** with an `apply_patch` helper dir (Rust + Node
wrapper), reordering tools and breaking virtualenvs/shims on
macOS/Linux.
- On Windows, MCP servers missed core env vars and often failed to start
without explicit per-server env blocks.

**After**  
- Helper dir is **appended** to PATH (preserves user/tool precedence).  
- Windows MCP child env now includes common core variables and mirrors
`PATH` → `Path`, so typical CLIs/plugins work **without** per-server env
blocks.

---

## Scope of change

### `codex-rs/arg0/src/lib.rs`
- Append temp/helper dir to `PATH` instead of prepending.

### `codex-cli/bin/codex.js`
- Mirror the same append behavior for the Node wrapper.

### `codex-rs/rmcp-client/src/utils.rs`
- Expand Windows `DEFAULT_ENV_VARS` (e.g., `COMSPEC`, `SYSTEMROOT`,
`PROGRAMFILES*`, `APPDATA`, etc.).
- Mirror `PATH` → `Path` for Windows child processes.  
- Small unit test; conditional `mut` + `clippy` cleanup.

---

## Security effects

No broadened privileges. Only environment propagation for well-known
Windows keys on stdio MCP child processes. No sandbox policy changes and
no network additions.

---

## Testing evidence

**Static**  
- `cargo fmt`  
- `cargo clippy -p codex-arg0 -D warnings` → **clean**  
- `cargo clippy -p codex-rmcp-client -D warnings` → **clean**  
- `cargo test -p codex-rmcp-client` → **13 passed**

**Manual**  
- Local verification on Windows PowerShell 5/7 and WSL (no `unused_mut`
warnings on non-Windows targets).

---

## Checklist

- [x] Append (not prepend) helper dir to PATH in Rust and Node wrappers
- [x] Windows MCP child inherits core env vars; `PATH` mirrored to
`Path`
- [x] `cargo fmt` / `clippy` clean across touched crates  
- [x] Unit tests updated/passing where applicable  
- [x] Cross-platform behavior preserved (macOS/Linux PATH precedence
intact)

Curt · 2025-10-28 21:06:39 -07:00

e9135fa7c5

Refresh tokens more often and log a better message when both auth and token refresh fails (#5655 )

<img width="784" height="153" alt="image"
src="https://github.com/user-attachments/assets/c44b0eb2-d65c-4fc2-8b54-b34f7e1c4d95"
/>

pakrym-oai · 2025-10-28 18:55:53 -07:00

ef3e075ad6

[codex][app-server] resume conversation from history (#5893 )

Anton Panasenko · 2025-10-28 18:18:03 -07:00

149e198ce8

[App Server] Allow fetching or resuming a conversation summary from the conversation id (#5890 )

This PR adds an option to app server to allow conversation summaries to
be fetched from just the conversation id rather than rollout path for
convenience at the cost of some latency to discover the rollout path.

This convenience is non-trivial as it allows app servers to simply
maintain conversation ids rather than rollout paths and the associated
platform (Windows) handling associated with storing and encoding them
correctly.

Gabriel Peal · 2025-10-28 20:17:22 -04:00

1d76ba5ebe

[app-server] Annotate more exported types with a title (#5879 )

Follow-up to https://github.com/openai/codex/pull/5063

Refined the app-server export pipeline so JSON Schema variants and
discriminator fields are annotated with descriptive, stable titles
before writing the bundle. This eliminates anonymous enum names in the
generated Pydantic models (goodbye Type7) while keeping downstream
tooling simple. Added shared helpers to derive titles and literals, and
reused them across the traversal logic for clarity. Running just fix -p
codex-app-server-protocol, just fmt, and cargo test -p
codex-app-server-protocol validates the change.

Rasmus Rygaard · 2025-10-28 16:35:12 -07:00

a1635eea25

verify mime type of images (#5888 )

solves: https://github.com/openai/codex/issues/5675

Block non-image uploads in the view_image workflow. We now confirm the
file’s MIME is image/* before building the data URL; otherwise we emit a
“unsupported MIME type” error to the model. This stops the agent from
sending application/json blobs that the Responses API rejects with 400s.

<img width="409" height="556" alt="Screenshot 2025-10-28 at 1 15 10 PM"
src="https://github.com/user-attachments/assets/a92199e8-2769-4b1d-8e33-92d9238c90fe"
/>

zhao-oai · 2025-10-28 14:52:51 -07:00

36113509f2

Fixed bug that results in a sporadic hang when attaching images (#5891 )

Addresses https://github.com/openai/codex/issues/5773

Testing: I tested that images work (regardless of order that they are
associated with the task prompt) in both the CLI and Extension. Also
verified that conversations in CLI and extension with images can be
resumed.

Eric Traut · 2025-10-28 14:42:46 -07:00

ba95d9862c

remove beta experimental header (#5892 )

Ahmed Ibrahim · 2025-10-28 21:28:56 +00:00

ef55992ab0

revert #5812 release file (#5887 )

revert #5812 release file

Ahmed Ibrahim · 2025-10-28 20:06:16 +00:00

e3f913f567

Filter out reasoning items from previous turns (#5857 )

Reduces request size and prevents 400 errors when switching between API
orgs.

Based on Responses API behavior described in
https://cookbook.openai.com/examples/responses_api/reasoning_items#caching

pakrym-oai · 2025-10-28 11:39:34 -07:00

1b8f2543ac

Fix handling of non-main default branches for cloud task submissions (#5069 )

## Summary
- detect the repository's default branch before submitting a cloud task
- expose a helper in `codex_core::git_info` for retrieving the default
branch name

Fixes #4888


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

Jeremy Rose · 2025-10-28 11:02:25 -07:00

65107d24a2

tui: show queued messages during response stream (#5540 )

This fixes an issue where messages sent during the final response stream
would seem to disappear, because the "queued messages" UI wasn't shown
during streaming.

Jeremy Rose · 2025-10-28 16:59:19 +00:00

36eb071998

tui: wait longer for color query results (#5004 )

this bumps the timeout when reading the responses to OSC 10/11 so that
we're less likely to pass the deadline halfway through reading the
response.

Jeremy Rose · 2025-10-28 09:42:57 -07:00

9b33ce3409

fix advanced.md (#5833 )

table wasn't formatting correctly

zhao-oai · 2025-10-28 16:32:20 +00:00

926c89cb20

chore: decompose submission loop (#5854 )

jif-oai · 2025-10-28 15:23:46 +00:00

5ba2a17576

chore: use anyhow::Result for all app-server integration tests (#5836 )

There's a lot of visual noise in app-server's integration tests due to
the number of `.expect("<some_msg>")` lines which are largely redundant
/ not very useful. Clean them up by using `anyhow::Result` + `?`
consistently.

Replaces the existing pattern of:
```
    let codex_home = TempDir::new().expect("create temp dir");
    create_config_toml(codex_home.path()).expect("write config.toml");

    let mut mcp = McpProcess::new(codex_home.path())
        .await
        .expect("spawn mcp process");
    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize())
        .await
        .expect("initialize timeout")
        .expect("initialize request");
```

With:
```
    let codex_home = TempDir::new()?;
    create_config_toml(codex_home.path())?;

    let mut mcp = McpProcess::new(codex_home.path()).await?;
    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
```

Owen Lin · 2025-10-28 08:10:23 -07:00

266419217e

chore: drop useless shell stuff (#5848 )

jif-oai · 2025-10-28 14:52:52 +00:00

be4bdfec93

chore: speed-up pipeline (#5812 )

Speed-up pipeline by:
* Decoupling tests and clippy
* Use pre-built binary in tests
* `sccache` for caching of the builds

jif-oai · 2025-10-28 14:08:52 +00:00

7ff142d93f

[Auth] Choose which auth storage to use based on config (#5792 )

This PR is a follow-up to #5591. It allows users to choose which auth
storage mode they want by using the new
`cli_auth_credentials_store_mode` config.

Celia Chen · 2025-10-27 19:41:49 -07:00

4a42c4e142

feat(tui): clarify Windows auto mode requirements (#5568 )

## Summary
- Coerce Windows `workspace-write` configs back to read-only, surface
the forced downgrade in the approvals popup,
  and funnel users toward WSL or Full Access.
- Add WSL installation instructions to the Auto preset on Windows while
keeping the preset available for other
  platforms.
- Skip the trust-on-first-run prompt on native Windows so new folders
remain read-only without additional
  confirmation.
- Expose a structured sandbox policy resolution from config to flag
Windows downgrades and adjust tests (core,
exec, TUI) to reflect the new behavior; provide a Windows-only approvals
snapshot.

  ## Testing
  - cargo fmt
- cargo test -p codex-core
config::tests::add_dir_override_extends_workspace_writable_roots
- cargo test -p codex-exec
suite::resume::exec_resume_preserves_cli_configuration_overrides
- cargo test -p codex-tui
chatwidget::tests::approvals_selection_popup_snapshot
- cargo test -p codex-tui
approvals_popup_includes_wsl_note_for_auto_mode
  - cargo test -p codex-tui windows_skips_trust_prompt
  - just fix -p codex-core
  - just fix -p codex-tui

Josh McKinney · 2025-10-28 01:19:32 +00:00

66a4b89822

Truncate the content-item for mcp tools (#5835 )

This PR truncates the text output of MCP tool

Ahmed Ibrahim · 2025-10-28 00:39:35 +00:00

d7b333be97

fix image drag drop (#5794 )

fixing drag/drop photos bug in codex

state of the world before:

sometimes, when you drag screenshots into codex, the image does not
properly render into context. instead, the file name is shown in
quotation marks.


https://github.com/user-attachments/assets/3c0e540a-505c-4ec0-b634-e9add6a73119

the screenshot is not actually included in agent context. the agent
needs to manually call the view_image tool to see the screenshot. this
can be unreliable especially if the image is part of a longer prompt and
is dependent on the agent going out of its way to view the image.

state of the world after:


https://github.com/user-attachments/assets/5f2b7bf7-8a3f-4708-85f3-d68a017bfd97

now, images will always be directly embedded into chat context

## Technical Details

- MacOS sends screenshot paths with a narrow no‑break space right before
the “AM/PM” suffix, which used to trigger our non‑ASCII fallback in the
paste burst detector.
- That fallback flushed the partially buffered paste immediately, so the
path arrived in two separate `handle_paste` calls (quoted prefix +
`PM.png'`). The split string could not be normalized to a real path, so
we showed the quoted filename instead of embedding the image.
- We now append non‑ASCII characters into the burst buffer when a burst
is already active. Finder’s payload stays intact, the path normalizes,
and the image attaches automatically.
- When no burst is active (e.g. during IME typing), non‑ASCII characters
still bypass the buffer so text entry remains responsive.

zhao-oai · 2025-10-27 17:11:30 -07:00

4d6a42a622

[MCP] Render MCP tool call result images to the model (#5600 )

It's pretty amazing we have gotten here without the ability for the
model to see image content from MCP tool calls.

This PR builds off of 4391 and fixes #4819. I would like @KKcorps to get
adequete credit here but I also want to get this fix in ASAP so I gave
him a week to update it and haven't gotten a response so I'm going to
take it across the finish line.


This test highlights how absured the current situation is. I asked the
model to read this image using the Chrome MCP
<img width="2378" height="674" alt="image"
src="https://github.com/user-attachments/assets/9ef52608-72a2-4423-9f5e-7ae36b2b56e0"
/>

After this change, it correctly outputs:
> Captured the page: image dhows a dark terminal-style UI labeled
`OpenAI Codex (v0.0.0)` with prompt `model: gpt-5-codex medium` and
working directory `/codex/codex-rs`
(and more)  

Before this change, it said:
> Took the full-page screenshot you asked for. It shows a long,
horizontally repeating pattern of stylized people in orange, light-blue,
and mustard clothing, holding hands in alternating poses against a white
background. No text or other graphics-just rows of flat illustration
stretching off to the right.

Without this change, the Figma, Playwright, Chrome, and other visual MCP
servers are pretty much entirely useless.

I tested this change with the openai respones api as well as a third
party completions api

Gabriel Peal · 2025-10-27 17:55:57 -04:00

b0bdc04c30

fix: move account struct to app-server-protocol and use camelCase (#5829 )

Makes sense to move this struct to `app-server-protocol/` since we want
to serialize as camelCase, but we don't for structs defined in
`protocol/`

It was:
```
export type Account = { "type": "ApiKey", api_key: string, } | { "type": "chatgpt", email: string | null, plan_type: PlanType, };
```

But we want:
```
export type Account = { "type": "apiKey", apiKey: string, } | { "type": "chatgpt", email: string | null, planType: PlanType, };
```

Owen Lin · 2025-10-27 14:06:13 -07:00

67a219ffc2

Centralize truncation in conversation history (#5652 )

move the truncation logic to conversation history to use on any tool
output. This will help us in avoiding edge cases while truncating the
tool calls and mcp calls.

Ahmed Ibrahim · 2025-10-27 14:05:35 -07:00

7226365397

3718 Commits