codex

Rename Realtime V2 tool to background_agent (#17278 )

Rename the Realtime V2 delegation tool and parser constant to
background_agent, and update the tool description and fixtures to match.

Validation: just fmt; cargo check -p codex-api; git diff --check

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-04-09 22:17:55 -07:00

60236e8c92

Add realtime voice selection (#17176 )

- Add realtime voice selection for realtime/start.
- Expose the supported v1/v2 voice lists and cover explicit, configured,
default, and invalid voice paths.

Ahmed Ibrahim · 2026-04-08 20:19:15 -07:00

2f9090be62

Attach WebRTC realtime starts to sideband websocket (#17057 )

Summary:
- parse the realtime call Location header and join that call over the
direct realtime WebSocket
- keep WebRTC starts alive on the existing realtime conversation path

Validation:
- just fmt
- git diff --check
- cargo check -p codex-api
- cargo check -p codex-core --tests
- local cargo tests not run; relying on PR CI

Ahmed Ibrahim · 2026-04-08 15:25:42 -07:00

794a0240f9

Use model metadata for Fast Mode status (#16949 )

Fast Mode status was still tied to one model name in the TUI and
model-list plumbing. This changes the model metadata shape so a model
can advertise additional speed tiers, carries that field through the
app-server model list, and uses it to decide when to show Fast Mode
status.

For people using Codex, the behavior is intended to stay the same for
existing models. Fast Mode still requires the existing signed-in /
feature-gated path; the difference is that the UI can now recognize any
model the model list marks as Fast-capable, instead of requiring a new
client-side slug check.

pash-openai · 2026-04-07 17:55:40 -07:00

80ebc80be5

Add WebRTC transport to realtime start (#16960 )

Adds WebRTC startup to the experimental app-server
`thread/realtime/start` method with an optional transport enum. The
websocket path remains the default; WebRTC offers create the realtime
session through the shared start flow and emit the answer SDP via
`thread/realtime/sdp`.

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-04-07 15:43:38 -07:00

fb3dcfde1d

fix(app-server) revert null instructions changes (#17047 )

Dylan Hurd · 2026-04-07 15:18:34 -07:00

6c36e7d688

feat(analytics): generate an installation_id and pass it in responsesapi client_metadata (#16912 )

## Summary

This adds a stable Codex installation ID and includes it on Responses
API requests via `x-codex-installation-id` passed in via the
`client_metadata` field for analytics/debugging.

The main pieces are:
- persist a UUID in `$CODEX_HOME/installation_id`
- thread the installation ID into `ModelClient`
- send it in `client_metadata` on Responses requests so it works
consistently across HTTP and WebSocket transports

Owen Lin · 2026-04-07 09:52:17 -07:00

5d1671ca70

[codex] reduce module visibility (#16978 )

## Summary
- reduce public module visibility across Rust crates, preferring private
or crate-private modules with explicit crate-root public exports
- update external call sites and tests to use the intended public crate
APIs instead of reaching through module trees
- add the module visibility guideline to AGENTS.md

## Validation
- `cargo check --workspace --all-targets --message-format=short` passed
before the final fix/format pass
- `just fix` completed successfully
- `just fmt` completed successfully
- `git diff --check` passed

pakrym-oai · 2026-04-07 08:03:35 -07:00

413c1e1fdf

Honor null thread instructions (#16964 )

- Treat explicit null thread instructions as a blank-slate override
while preserving omitted-field fallback behavior.
- Preserve null through rollout resume/fork and keep explicit empty
strings distinct.
- Add app-server v2 start/fork coverage for the tri-state instruction
params.

Ahmed Ibrahim · 2026-04-07 04:10:19 +00:00

24c598e8a9

chore: clean up argument-comment lint and roll out all-target CI on macOS (#16054 )

## Why

`argument-comment-lint` was green in CI even though the repo still had
many uncommented literal arguments. The main gap was target coverage:
the repo wrapper did not force Cargo to inspect test-only call sites, so
examples like the `latest_session_lookup_params(true, ...)` tests in
`codex-rs/tui_app_server/src/lib.rs` never entered the blocking CI path.

This change cleans up the existing backlog, makes the default repo lint
path cover all Cargo targets, and starts rolling that stricter CI
enforcement out on the platform where it is currently validated.

## What changed

- mechanically fixed existing `argument-comment-lint` violations across
the `codex-rs` workspace, including tests, examples, and benches
- updated `tools/argument-comment-lint/run-prebuilt-linter.sh` and
`tools/argument-comment-lint/run.sh` so non-`--fix` runs default to
`--all-targets` unless the caller explicitly narrows the target set
- fixed both wrappers so forwarded cargo arguments after `--` are
preserved with a single separator
- documented the new default behavior in
`tools/argument-comment-lint/README.md`
- updated `rust-ci` so the macOS lint lane keeps the plain wrapper
invocation and therefore enforces `--all-targets`, while Linux and
Windows temporarily pass `-- --lib --bins`

That temporary CI split keeps the stricter all-targets check where it is
already cleaned up, while leaving room to finish the remaining Linux-
and Windows-specific target-gated cleanup before enabling
`--all-targets` on those runners. The Linux and Windows failures on the
intermediate revision were caused by the wrapper forwarding bug, not by
additional lint findings in those lanes.

## Validation

- `bash -n tools/argument-comment-lint/run.sh`
- `bash -n tools/argument-comment-lint/run-prebuilt-linter.sh`
- shell-level wrapper forwarding check for `-- --lib --bins`
- shell-level wrapper forwarding check for `-- --tests`
- `just argument-comment-lint`
- `cargo test` in `tools/argument-comment-lint`
- `cargo test -p codex-terminal-detection`

## Follow-up

- Clean up remaining Linux-only target-gated callsites, then switch the
Linux lint lane back to the plain wrapper invocation.
- Clean up remaining Windows-only target-gated callsites, then switch
the Windows lint lane back to the plain wrapper invocation.

Michael Bolin · 2026-03-27 19:00:44 -07:00

61dfe0b86c

Prefer websockets when providers support them (#13592 )

Remove all flags and model settings.

---------

Co-authored-by: Codex <noreply@openai.com>

pakrym-oai · 2026-03-17 19:46:44 -07:00

770616414a

[stack 2/4] Align main realtime v2 wire and runtime flow (#14830 )

## Stack Position
2/4. Built on top of #14828.

## Base
- #14828

## Unblocks
- #14829
- #14827

## Scope
- Port the realtime v2 wire parsing, session, app-server, and
conversation runtime behavior onto the split websocket-method base.
- Branch runtime behavior directly on the current realtime session kind
instead of parser-derived flow flags.
- Keep regression coverage in the existing e2e suites.

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-03-16 21:38:07 -07:00

fbd7f9b986

Add realtime transcription mode for websocket sessions (#14556 )

- add experimental_realtime_ws_mode (conversational/transcription) and
plumb it into realtime conversation session config
- switch realtime websocket intent and session.update payload shape
based on mode
- update config schema and realtime/config tests

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-03-12 23:50:30 -07:00

2253a9d1d7

Add realtime v2 event parser behind feature flag (#14537 )

- Add a feature-flagged realtime v2 parser on the existing
websocket/session pipeline.
- Wire parser selection from core feature flags and map the codex
handoff tool-call path into existing handoff events.

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-03-12 21:12:40 -07:00

3e8f47169e

feat(search_tool): gate search_tool on model supports_search_tool field (#14502 )

Anton Panasenko · 2026-03-12 16:03:50 -07:00

651717323c

chore: add web_search_tool_type for image support (#13538 )

add `web_search_tool_type` on model_info that can be populated from
backend. will be used to filter which models can use `web_search` with
images and which cant.

added small unit test.

sayan-oai · 2026-03-05 07:02:27 +00:00

03d55f0e6f

Add under-development original-resolution view_image support (#13050 )

## Summary

Add original-resolution support for `view_image` behind the
under-development `view_image_original_resolution` feature flag.

When the flag is enabled and the target model is `gpt-5.3-codex` or
newer, `view_image` now preserves original PNG/JPEG/WebP bytes and sends
`detail: "original"` to the Responses API instead of using the legacy
resize/compress path.

## What changed

- Added `view_image_original_resolution` as an under-development feature
flag.
- Added `ImageDetail` to the protocol models and support for serializing
`detail: "original"` on tool-returned images.
- Added `PromptImageMode::Original` to `codex-utils-image`.
  - Preserves original PNG/JPEG/WebP bytes.
  - Keeps legacy behavior for the resize path.
- Updated `view_image` to:
- use the shared `local_image_content_items_with_label_number(...)`
helper in both code paths
  - select original-resolution mode only when:
    - the feature flag is enabled, and
    - the model slug parses as `gpt-5.3-codex` or newer
- Kept local user image attachments on the existing resize path; this
change is specific to `view_image`.
- Updated history/image accounting so only `detail: "original"` images
use the docs-based GPT-5 image cost calculation; legacy images still use
the old fixed estimate.
- Added JS REPL guidance, gated on the same feature flag, to prefer JPEG
at 85% quality unless lossless is required, while still allowing other
formats when explicitly requested.
- Updated tests and helper code that construct
`FunctionCallOutputContentItem::InputImage` to carry the new `detail`
field.

## Behavior

### Feature off
- `view_image` keeps the existing resize/re-encode behavior.
- History estimation keeps the existing fixed-cost heuristic.

### Feature on + `gpt-5.3-codex+`
- `view_image` sends original-resolution images with `detail:
"original"`.
- PNG/JPEG/WebP source bytes are preserved when possible.
- History estimation uses the GPT-5 docs-based image-cost calculation
for those `detail: "original"` images.


#### [git stack](https://github.com/magus/git-stack-cli)
- 👉 `1` https://github.com/openai/codex/pull/13050
- ⏳ `2` https://github.com/openai/codex/pull/13331
- ⏳ `3` https://github.com/openai/codex/pull/13049

Curtis 'Fjord' Hawthorne · 2026-03-03 15:56:54 -08:00

b92146d48b

Remove Responses V1 websocket implementation (#13364 )

V2 is the way to go!

pakrym-oai · 2026-03-03 11:32:53 -07:00

69df12efb3

add fast mode toggle (#13212 )

- add a local Fast mode setting in codex-core (similar to how model id
is currently stored on disk locally)
- send `service_tier=priority` on requests when Fast is enabled
- add `/fast` in the TUI and persist it locally
- feature flag

pash-openai · 2026-03-02 20:29:33 -08:00

2f5b01abd6

Update realtime websocket API (#13265 )

- migrate the realtime websocket transport to the new session and
handoff flow
- make the realtime model configurable in config.toml and use API-key
auth for the websocket

---------

Co-authored-by: Codex <noreply@openai.com>

Ahmed Ibrahim · 2026-03-02 16:05:40 -08:00

b20b6aa46f

Add model availability NUX metadata (#12972 )

- replace show_nux with structured availability_nux model metadata
- expose availability NUX data through the app-server model API
- update shared fixtures and tests for the new field

Ahmed Ibrahim · 2026-02-26 22:02:57 -08:00

4d180ae428

Use model catalog default for reasoning summary fallback (#12873 )

## Summary
- make `Config.model_reasoning_summary` optional so unset means use
model default
- resolve the optional config value to a concrete summary when building
`TurnContext`
- add protocol support for `default_reasoning_summary` in model metadata

## Validation
- `cargo test -p codex-core --lib client::tests -- --nocapture`

---------

Co-authored-by: Codex <noreply@openai.com>

pakrym-oai · 2026-02-26 09:31:13 -08:00

ba41e84a50

Delete AggregatedStream (#12441 )

Used only in test

pakrym-oai · 2026-02-21 08:50:27 +00:00

e7b6f38b58

Wire realtime api to core (#12268 )

- Introduce `RealtimeConversationManager` for realtime API management 
- Add `op::conversation` to start conversation, insert audio, insert
text, and close conversation.
- emit conversation lifecycle and realtime events.
- Move shared realtime payload types into codex-protocol and add core
e2e websocket tests for start/replace/transport-close paths.

Things to consider:
- Should we use the same `op::` and `Events` channel to carry audio? I
think we should try this simple approach and later we can create
separate one if the channels got congested.
- Sending text updates to the client: we can start simple and later
restrict that.
- Provider auth isn't wired for now intentionally

Ahmed Ibrahim · 2026-02-20 19:06:35 -08:00

6817f0be8a

codex-api: realtime websocket session.create + typed inbound events (#12036 )

## Summary
- add realtime websocket client transport in codex-api
- send session.create on connect with backend prompt and optional
conversation_id
- keep session.update for prompt changes after connect
- switch inbound event parsing to a tagged enum (typed variants instead
of optional field bag)
- add a websocket e2e integration test in
codex-rs/codex-api/tests/realtime_websocket_e2e.rs

## Why
This moves the realtime transport to an explicit session-create
handshake and improves protocol safety with typed inbound events.

## Testing
- Added e2e integration test coverage for session create + event flow in
the API crate.

Ahmed Ibrahim · 2026-02-17 22:17:01 -08:00

03ce01e71f

fix: show user warning when using default fallback metadata (#11690 )

### What
It's currently unclear when the harness falls back to the default,
generic `ModelInfo`. This happens when the `remote_models` feature is
disabled or the model is truly unknown, and can lead to bad performance
and issues in the harness.

Add a user-facing warning when this happens so they are aware when their
setup is broken.

### Tests
Added tests, tested locally.

sayan-oai · 2026-02-15 18:46:05 -08:00

060a320e7d

Do not attempt to append after response.completed (#11402 )

Completed responses are fully done, and new response must be created.

pakrym-oai · 2026-02-11 07:45:17 -08:00

eac5473114

Prefer websocket transport when model opts in (#11386 )

Summary
- add a `prefer_websockets` field to `ModelInfo`, defaulting to `false`
in all fixtures and constructors
- wire the new flag into websocket selection so models that opt in
always use websocket transport even when the feature gate is off

Testing
- Not run (not requested)

pakrym-oai · 2026-02-10 18:50:48 -08:00

c68999ee6d

Remove ApiPrompt (#11265 )

Keep things simple and build a full Responses API request request right
in the model client

pakrym-oai · 2026-02-10 16:12:31 +00:00

3322b99900

feat: drop wire_api from clients (#10498 )

jif-oai · 2026-02-03 12:43:09 +00:00

88598b9402

chore: nuke chat/completions API (#10157 )

jif-oai · 2026-02-03 11:31:57 +00:00

d2394a2494

[Codex][CLI] Gate image inputs by model modalities (#10271 )

###### Summary

- Add input_modalities to model metadata so clients can determine
supported input types.
- Gate image paste/attach in TUI when the selected model does not
support images.
- Block submits that include images for unsupported models and show a
clear warning.
- Propagate modality metadata through app-server protocol/model-list
responses.
  - Update related tests/fixtures.

  ###### Rationale

  - Models support different input modalities.
- Clients need an explicit capability signal to prevent unsupported
requests.
- Backward-compatible defaults preserve existing behavior when modality
metadata is absent.

  ###### Scope

  - codex-rs/protocol, codex-rs/core, codex-rs/tui
  - codex-rs/app-server-protocol, codex-rs/app-server
  - Generated app-server types / schema fixtures

  ###### Trade-offs

- Default behavior assumes text + image when field is absent for
compatibility.
  - Server-side validation remains the source of truth.

  ###### Follow-up

- Non-TUI clients should consume input_modalities to disable unsupported
attachments.
- Model catalogs should explicitly set input_modalities for text-only
models.

  ###### Testing

  - cargo fmt --all
  - cargo test -p codex-tui
  - env -u GITHUB_APP_KEY cargo test -p codex-core --lib
  - just write-app-server-schema
- cargo run -p codex-cli --bin codex -- app-server generate-ts --out
app-server-types
  - test against local backend
  
<img width="695" height="199" alt="image"
src="https://github.com/user-attachments/assets/d22dd04f-5eba-4db9-a7c5-a2506f60ec44"
/>

---------

Co-authored-by: Josh McKinney <joshka@openai.com>

Colin Young · 2026-02-02 18:56:39 -08:00

7e07ec8f73

chore: add phase to message responseitem (#10455 )

### What

add wiring for `phase` field on `ResponseItem::Message` to lay
groundwork for differentiating model preambles and final messages.
currently optional.

follows pattern in #9698.

updated schemas with `just write-app-server-schema` so we can see type
changes.

### Tests
Updated existing tests for SSE parsing and hydrating from history

sayan-oai · 2026-02-03 02:52:26 +00:00

fc05374344

chore(personality) new schema with fallbacks (#10147 )

## Summary
Let's dial in this api contract in a bit more with more robust fallback
behavior when model_instructions_template is false.

Switches to a more explicit template / variables structure, with more
fallbacks.

## Testing
- [x] Adding unit tests
- [x] Tested locally

Dylan Hurd · 2026-01-30 00:10:12 -07:00

e3ab0bd973

Support end_turn flag (#9698 )

Experimental flag that signals the end of the turn.

pakrym-oai · 2026-01-22 17:27:48 +00:00

b511c38ddb

feat(core) ModelInfo.model_instructions_template (#9597 )

## Summary
#9555 is the start of a rename, so I'm starting to standardize here.
Sets up `model_instructions` templating with a strongly-typed object for
injecting a personality block into the model instructions.

## Testing
- [x] Added tests
- [x] Ran locally

Dylan Hurd · 2026-01-21 18:11:18 -08:00

96a72828be

Turn-state sticky routing per turn (#9332 )

- capture the header from SSE/WS handshakes, store it per
ModelClientSession using `Oncelock`, echo it on turn-scoped requests,
and add SSE+WS integration tests for within-turn persistence +
cross-turn reset.

- keep `x-codex-turn-state` sticky within a user turn to maintain
routing continuity for retries/tool follow-ups.

Ahmed Ibrahim · 2026-01-16 09:30:11 -08:00

ebdd8795e9

Add feature for optional request compression (#8767 )

Adds a new feature
`enable_request_compression` that will compress using zstd requests to
the codex-backend. Currently only enabled for codex-backend so only enabled for openai providers when using chatgpt::auth even when the feature is enabled

Added a new info log line too for evaluating the compression ratio and
overhead off compressing before requesting. You can enable with
`RUST_LOG=$RUST_LOG,codex_client::transport=info`

```
2026-01-06T00:09:48.272113Z  INFO codex_client::transport: Compressed request body with zstd pre_compression_bytes=28914 post_compression_bytes=11485 compression_duration_ms=0
```

Channing Conger · 2026-01-07 13:21:40 -08:00

21c6d40a44

Merge Modelfamily into modelinfo (#8763 )

- Merge ModelFamily into ModelInfo
- Remove logic for adding instructions to apply patch
- Add compaction limit and visible context window to `ModelInfo`

Ahmed Ibrahim · 2026-01-07 10:35:09 -08:00

9179c9deac

Refresh on models etag mismatch (#8491 )

- Send models etag
- Refresh models on 412
- This wires `ModelsManager` to `ModelFamily` so we don't mutate it
mid-turn

Ahmed Ibrahim · 2026-01-01 11:41:16 -08:00

66b7c673e9

Remove reasoning format (#8484 )

This isn't very useful parameter. 

logic:
```
if model puts `**` in their reasoning, trim it and visualize the header.
if couldn't trim: don't render
if model doesn't support: don't render
```

We can simplify to:
```
if could trim, visualize header.
if not, don't render
```

Ahmed Ibrahim · 2025-12-23 16:01:46 -08:00

40de81e7af

remove minimal client version (#8447 )

This isn't needed value by client

Ahmed Ibrahim · 2025-12-22 12:52:24 -08:00

6b2ef216f1

Update Model Info (#7853 )

Ahmed Ibrahim · 2025-12-11 14:06:07 -08:00

b7fa7ca8e9

override instructions using ModelInfo (#7754 )

Making sure we can override base instructions

Ahmed Ibrahim · 2025-12-08 17:30:42 -08:00

cacfd003ac

load models from disk and set a ttl and etag (#7722 )

# External (non-OpenAI) Pull Request Requirements

Before opening this Pull Request, please read the dedicated
"Contributing" markdown file or your PR may be closed:
https://github.com/openai/codex/blob/main/docs/contributing.md

If your PR conforms to our contribution guidelines, replace this text
with a detailed and high quality description of your changes.

Include a link to a bug report or enhancement request.

Ahmed Ibrahim · 2025-12-08 13:43:04 -08:00

222a491570

Add remote models feature flag (#7648 )

# External (non-OpenAI) Pull Request Requirements

Before opening this Pull Request, please read the dedicated
"Contributing" markdown file or your PR may be closed:
https://github.com/openai/codex/blob/main/docs/contributing.md

If your PR conforms to our contribution guidelines, replace this text
with a detailed and high quality description of your changes.

Include a link to a bug report or enhancement request.

Ahmed Ibrahim · 2025-12-07 09:47:48 -08:00

53a486f7ea

Call models endpoint in models manager (#7616 )

- Introduce `with_remote_overrides` and update
`refresh_available_models`
- Put `auth_manager` instead of `auth_mode` on `models_manager`
- Remove `ShellType` and `ReasoningLevel` to use already existing
structs

Ahmed Ibrahim · 2025-12-04 18:28:03 -08:00

7b359c9c8e

Add models endpoint (#7603 )

- Use the codex-api crate to introduce models endpoint. 
- Add `models` to codex core tests helpers
- Add `ModelsInfo` for the endpoint return type

Ahmed Ibrahim · 2025-12-04 12:57:54 -08:00

903b7774bc

chore: proper client extraction (#6996 )

jif-oai · 2025-11-25 18:06:12 +00:00

4502b1b263

49 Commits