codex

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

Add Reset in for rate limits (#4111 )

- Parse the headers
- Reorganize the struct because it's getting too long
- show the resets at in the tui

<img width="324" height="79" alt="image"
src="https://github.com/user-attachments/assets/ca15cd48-f112-4556-91ab-1e3a9bc4683d"
/>

Ahmed Ibrahim · 2025-09-24 15:31:08 +00:00

cb96f4f596

Send limits when getting rate limited (#4102 )

Users need visibility on rate limits when they are rate limited.

Ahmed Ibrahim · 2025-09-23 22:56:34 +00:00

8227a5ba1b

Add exec output-schema parameter (#4079 )

Adds structured output to `exec` via the `--structured-output`
parameter.

pakrym-oai · 2025-09-23 13:59:16 -07:00

fdb8dadcae

Use anyhow::Result in tests for error propagation (#4105 )

pakrym-oai · 2025-09-23 13:31:36 -07:00

0f9a796617

Change headers and struct of rate limits (#4060 )

Ahmed Ibrahim · 2025-09-22 21:06:20 +00:00

dd56750612

Forward Rate limits to the UI (#3965 )

We currently get information about rate limits in the response headers.
We want to forward them to the clients to have better transparency.
UI/UX plans have been discussed and this information is needed.

Ahmed Ibrahim · 2025-09-20 21:26:16 -07:00

04504d8218

feat: /review (#3774 )

Adds `/review` action in TUI

<img width="637" height="370" alt="Screenshot 2025-09-17 at 12 41 19 AM"
src="https://github.com/user-attachments/assets/b1979a6e-844a-4b97-ab20-107c185aec1d"
/>

dedrisian-oai · 2025-09-18 14:14:16 -07:00

62258df92f

Switch to uuid_v7 and tighten ConversationId usage (#3819 )

Make sure conversations have a timestamp.

pakrym-oai · 2025-09-18 14:37:03 +00:00

d4aba772cb

Fix EventMsg Optional (#3604 )

dedrisian-oai · 2025-09-15 00:34:33 +00:00

2aa84b8891

Handle resuming/forking after compact (#3533 )

We need to construct the history different when compact happens. For
this, we need to just consider the history after compact and convert
compact to a response item.

This needs to change and use `build_compact_history` when this #3446 is
merged.

Ahmed Ibrahim · 2025-09-14 13:23:31 +00:00

bbea6bbf7e

Review Mode (Core) (#3401 )

## 📝 Review Mode -- Core

This PR introduces the Core implementation for Review mode:

- New op `Op::Review { prompt: String }:` spawns a child review task
with isolated context, a review‑specific system prompt, and a
`Config.review_model`.
- `EnteredReviewMode`: emitted when the child review session starts.
Every event from this point onwards reflects the review session.
- `ExitedReviewMode(Option<ReviewOutputEvent>)`: emitted when the review
finishes or is interrupted, with optional structured findings:

```json
{
  "findings": [
    {
      "title": "<≤ 80 chars, imperative>",
      "body": "<valid Markdown explaining *why* this is a problem; cite files/lines/functions>",
      "confidence_score": <float 0.0-1.0>,
      "priority": <int 0-3>,
      "code_location": {
        "absolute_file_path": "<file path>",
        "line_range": {"start": <int>, "end": <int>}
      }
    }
  ],
  "overall_correctness": "patch is correct" | "patch is incorrect",
  "overall_explanation": "<1-3 sentence explanation justifying the overall_correctness verdict>",
  "overall_confidence_score": <float 0.0-1.0>
}
```

## Questions

### Why separate out its own message history?

We want the review thread to match the training of our review models as
much as possible -- that means using a custom prompt, removing user
instructions, and starting a clean chat history.

We also want to make sure the review thread doesn't leak into the parent
thread.

### Why do this as a mode, vs. sub-agents?

1. We want review to be a synchronous task, so it's fine for now to do a
bespoke implementation.
2. We're still unclear about the final structure for sub-agents. We'd
prefer to land this quickly and then refactor into sub-agents without
rushing that implementation.

dedrisian-oai · 2025-09-12 23:25:10 +00:00

90a0fd342f

feat: context compaction (#3446 )

## Compact feature:
1. Stops the model when the context window become too large
2. Add a user turn, asking for the model to summarize
3. Build a bridge that contains all the previous user message + the
summary. Rendered from a template
4. Start sampling again from a clean conversation with only that bridge

jif-oai · 2025-09-12 13:07:10 -07:00

ea225df22e

feat: reasoning effort as optional (#3527 )

Allow the reasoning effort to be optional

jif-oai · 2025-09-12 12:06:33 -07:00

c6fd056aa6

feat: include reasoning_effort in NewConversationResponse (#3506 )

`ClientRequest::NewConversation` picks up the reasoning level from the user's defaults in `config.toml`, so it should be reported in `NewConversationResponse`.

Michael Bolin · 2025-09-11 21:04:40 -07:00

9bbeb75361

Add Compact and Turn Context to the rollout items (#3444 )

Adding compact and turn context to the rollout items

based on #3440

Ahmed Ibrahim · 2025-09-11 18:08:51 +00:00

674e3d3c90

Change forking to read the rollout from file (#3440 )

This PR changes get history op to get path. Then, forking will use a
path. This will help us have one unified codepath for resuming/forking
conversations. Will also help in having rollout history in order. It
also fixes a bug where you won't see the UI when resuming after forking.

Ahmed Ibrahim · 2025-09-10 17:42:54 -07:00

162e1235a8

Added images to UserMessageEvent (#3400 )

This PR adds an `images` field to the existing `UserMessageEvent` so we
can encode zero or more images associated with a user message. This
allows images to be restored when conversations are restored.

Eric Traut · 2025-09-10 10:18:43 -07:00

39db113cc9

Move initial history to protocol (#3422 )

To fix an edge case of forking then resuming

#3419

Ahmed Ibrahim · 2025-09-10 10:17:24 -07:00

45bd5ca4b9

fix: include rollout_path in NewConversationResponse (#3352 )

Adding the `rollout_path` to the `NewConversationResponse` makes it so a
client can perform subsequent operations on a `(ConversationId,
PathBuf)` pair. #3353 will introduce support for `ArchiveConversation`.

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

Michael Bolin · 2025-09-09 00:11:48 -07:00

2a76a08a9e

Generate more typescript types and return conversation id with ConversationSummary (#3219 )

This PR does multiple things that are necessary for conversation resume
to work from the extension. I wanted to make sure everything worked so
these changes wound up in one PR:
1. Generate more ts types
2. Resume rollout history files rather than create a new one every time
it is resumed so you don't see a duplicate conversation in history for
every resume. Chatted with @aibrahim-oai to verify this
3. Return conversation_id in conversation summaries
4. [Cleanup] Use serde and strong types for a lot of the rollout file
parsing

Gabriel Peal · 2025-09-08 17:54:47 -04:00

5eaaf307e1

Format large numbers in a more readable way. (#2046 )

- In the bottom line of the TUI, print the number of tokens to 3 sigfigs
  with an SI suffix, e.g. "1.23K".
- Elsewhere where we print a number, I figure it's worthwhile to print
  the exact number, because e.g. it's a summary of your session. Here we print
  the numbers comma-separated.

Justin Lebar · 2025-09-08 21:48:48 +00:00

18330c2362

Use ConversationId instead of raw Uuids (#3282 )

We're trying to migrate from `session_id: Uuid` to `conversation_id:
ConversationId`. Not only does this give us more type safety but it
unifies our terminology across Codex and with the implementation of
session resuming, a conversation (which can span multiple sessions) is
more appropriate.

I started this impl on https://github.com/openai/codex/pull/3219 as part
of getting resume working in the extension but it's big enough that it
should be broken out.

Gabriel Peal · 2025-09-07 23:22:25 -04:00

c8fab51372

Move token usage/context information to session level (#3221 )

Move context information into the main loop so it can be used to
interrupt the loop or start auto-compaction.

pakrym-oai · 2025-09-06 15:19:23 +00:00

0269096229

Correctly calculate remaining context size (#3190 )

We had multiple issues with context size calculation:
1. `initial_prompt_tokens` calculation based on cache size is not
reliable, cache misses might set it to much higher value. For now
hardcoded to a safer constant.
2. Input context size for GPT-5 is 272k (that's where 33% came from).

Fixes.

pakrym-oai · 2025-09-04 23:34:14 +00:00

7df9e9c664

fix: fix serde_as annotation and verify with test (#3170 )

I didn't do https://github.com/openai/codex/pull/3163 correctly the
first time: now verified with a test.

Michael Bolin · 2025-09-04 10:38:00 -07:00

91708bb031

fix: use a more efficient wire format for ExecCommandOutputDeltaEvent.chunk (#3163 )

When serializing to JSON, the existing solution created an enormous
array of ints, which is far more bytes on the wire than a base64-encoded
string would be.

Michael Bolin · 2025-09-04 08:21:58 -07:00

0a83db5512

Dividing UserMsgs into categories to send it back to the tui (#3127 )

This PR does the following:

- divides user msgs into 3 categories: plain, user instructions, and
environment context
- Centralizes adding user instructions and environment context to a
degree
- Improve the integration testing

Building on top of #3123

Specifically this
[comment](https://github.com/openai/codex/pull/3123#discussion_r2319885089).
We need to send the user message while ignoring the User Instructions
and Environment Context we attach.

Ahmed Ibrahim · 2025-09-04 05:34:50 +00:00

2b96f9f569

Replay EventMsgs from Response Items when resuming a session with history. (#3123 )

### Overview

This PR introduces the following changes:
	1.	Adds a unified mechanism to convert ResponseItem into EventMsg.
2. Ensures that when a session is initialized with initial history, a
vector of EventMsg is sent along with the session configuration. This
allows clients to re-render the UI accordingly.
	3. 	Added integration testing

### Caveats

This implementation does not send every EventMsg that was previously
dispatched to clients. The excluded events fall into two categories:
	•	“Arguably” rolled-out events
Examples include tool calls and apply-patch calls. While these events
are conceptually rolled out, we currently only roll out ResponseItems.
These events are already being handled elsewhere and transformed into
EventMsg before being sent.
	•	Non-rolled-out events
Certain events such as TurnDiff, Error, and TokenCount are not rolled
out at all.

### Future Directions

At present, resuming a session involves maintaining two states:
	•	UI State
Clients can replay most of the important UI from the provided EventMsg
history.
	•	Model State
The model receives the complete session history to reconstruct its
internal state.

This design provides a solid foundation. If, in the future, more precise
UI reconstruction is needed, we have two potential paths:
1. Introduce a third data structure that allows us to derive both
ResponseItems and EventMsgs.
2. Clearly divide responsibilities: the core system ensures the
integrity of the model state, while clients are responsible for
reconstructing the UI.

Ahmed Ibrahim · 2025-09-04 04:47:00 +00:00

f2036572b6

rework message styling (#2877 )

https://github.com/user-attachments/assets/cf07f62b-1895-44bb-b9c3-7a12032eb371

Jeremy Rose · 2025-09-02 17:29:58 +00:00

e442ecedab

Following up on #2371 post commit feedback (#2852 )

- Introduce websearch end to complement the begin 
- Moves the logic of adding the sebsearch tool to
create_tools_json_for_responses_api
- Making it the client responsibility to toggle the tool on or off 
- Other misc in #2371 post commit feedback
- Show the query:

<img width="1392" height="151" alt="image"
src="https://github.com/user-attachments/assets/8457f1a6-f851-44cf-bcca-0d4fe460ce89"
/>

Ahmed Ibrahim · 2025-08-28 19:24:38 -07:00

9dbe7284d2

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

send context window with task started (#2752 )

- Send context window with task started
- Accounting for changing the model per turn

Ahmed Ibrahim · 2025-08-27 00:04:21 -07:00

d0e06f74e2

Add web search tool (#2371 )

Adds web_search tool, enabling the model to use Responses API web_search
tool.
- Disabled by default, enabled by --search flag
- When --search is passed, exposes web_search_request function tool to
the model, which triggers user approval. When approved, the model can
use the web_search tool for the remainder of the turn
<img width="1033" height="294" alt="image"
src="https://github.com/user-attachments/assets/62ac6563-b946-465c-ba5d-9325af28b28f"
/>

---------

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

Reuben Narad · 2025-08-23 22:58:56 -07:00

363636f5eb

send-aggregated output (#2364 )

We want to send an aggregated output of stderr and stdout so we don't
have to aggregate it stderr+stdout as we lose order sometimes.

---------

Co-authored-by: Gabriel Peal <gpeal@users.noreply.github.com>

Ahmed Ibrahim · 2025-08-23 16:54:31 +00:00

957d44918d

fork conversation from a previous message (#2575 )

This can be the underlying logic in order to start a conversation from a
previous message. will need some love in the UI.

Base for building this: #2588

Ahmed Ibrahim · 2025-08-22 17:06:09 -07:00

311ad0ce26

tui: coalesce command output; show unabridged commands in transcript (#2590 )

https://github.com/user-attachments/assets/effec7c7-732a-4b61-a2ae-3cb297b6b19b

Jeremy Rose · 2025-08-22 16:32:31 -07:00

d994019f3f

Parse and expose stream errors (#2540 )

easong-openai · 2025-08-21 01:15:24 -07:00

8ad56be06e

[tui] Support /mcp command (#2430 )

## Summary
Adds a `/mcp` command to list active tools. We can extend this command
to allow configuration of MCP tools, but for now a simple list command
will help debug if your config.toml and your tools are working as
expected.

Dylan · 2025-08-19 09:00:31 -07:00

e7e5fe91c8

fix: exclude sysprompt etc from context left % (#2446 )

- Prevents the % left indicator from immediately decrementing to ~97%.
- Tested by prompting "hi" and noting it only decremented to 99%. And by
adding a bunch of debug logs and observing numbers.

ae · 2025-08-19 08:20:32 -07:00

096bca2fa2

protocol-ts (#2425 )

Michael Bolin · 2025-08-18 13:08:53 -07:00

fc6cfd5ecc

Add an operation to override current task context (#2431 )

- Added an operation to override current task context
- Added a test to check that cache stays the same

Ahmed Ibrahim · 2025-08-18 19:59:19 +00:00

c283f9f6ce

remove mcp-server/src/mcp_protocol.rs and the code that depends on it (#2360 )

Michael Bolin · 2025-08-18 00:29:18 -07:00

a269754668

fix: introduce EventMsg::TurnAborted (#2365 )

Introduces `EventMsg::TurnAborted` that should be sent in response to
`Op::Interrupt`.

In the MCP server, updates the handling of a
`ClientRequest::InterruptConversation` request such that it sends the
`Op::Interrupt` but does not respond to the request until it sees an
`EventMsg::TurnAborted`.

Michael Bolin · 2025-08-17 21:40:31 -07:00

b581498882

fix: introduce codex-protocol crate (#2355 )

Michael Bolin · 2025-08-15 12:44:40 -07:00

d262244725

145 Commits