178 Commits

• tui: preserve remote image attachments across resume/backtrack (#10590)

  ## Summary
  This PR makes app-server-provided image URLs first-class attachments in
  TUI, so they survive resume/backtrack/history recall and are resubmitted
  correctly.
  
  <img width="715" height="491" alt="Screenshot 2026-02-12 at 8 27 08 PM"
  src="https://github.com/user-attachments/assets/226cbd35-8f0c-4e51-a13e-459ef5dd1927"
  />
  
  Can delete the attached image upon backtracking:
  <img width="716" height="301" alt="Screenshot 2026-02-12 at 8 27 31 PM"
  src="https://github.com/user-attachments/assets/4558d230-f1bd-4eed-a093-8e1ab9c6db27"
  />
  
  In both history and composer, remote images are rendered as normal
  `[Image #N]` placeholders, with numbering unified with local images.
  
  ## What changed
  - Plumb remote image URLs through TUI message state:
    - `UserHistoryCell`
    - `BacktrackSelection`
    - `ChatComposerHistory::HistoryEntry`
    - `ChatWidget::UserMessage`
  - Show remote images as placeholder rows inside the composer box (above
  textarea), and in history cells.
  - Support keyboard selection/deletion for remote image rows in composer
  (`Up`/`Down`, `Delete`/`Backspace`).
  - Preserve remote-image-only turns in local composer history (Up/Down
  recall), including restore after backtrack.
  - Ensure submit/queue/backtrack resubmit include remote images in model
  input (`UserInput::Image`), and keep request shape stable for
  remote-image-only turns.
  - Keep image numbering contiguous across remote + local images:
    - remote images occupy `[Image #1]..[Image #M]`
    - local images start at `[Image #M+1]`
    - deletion renumbers consistently.
  - In protocol conversion, increment shared image index for remote images
  too, so mixed remote/local image tags stay in a single sequence.
  - Simplify restore logic to trust in-memory attachment order (no
  placeholder-number parsing path).
  - Backtrack/replay rollback handling now queues trims through
  `AppEvent::ApplyThreadRollback` and syncs transcript overlay/deferred
  lines after trims, so overlay/transcript state stays consistent.
  - Trim trailing blank rendered lines from user history rendering to
  avoid oversized blank padding.
  
  ## Docs + tests
  - Updated: `docs/tui-chat-composer.md` (remote image flow,
  selection/deletion, numbering offsets)
  - Added/updated tests across `tui/src/chatwidget/tests.rs`,
  `tui/src/app.rs`, `tui/src/app_backtrack.rs`, `tui/src/history_cell.rs`,
  and `tui/src/bottom_pane/chat_composer.rs`
  - Added snapshot coverage for remote image composer states, including
  deleting the first of two remote images.
  
  ## Validation
  - `just fmt`
  - `cargo test -p codex-tui`
  
  ## Codex author
  `codex fork 019c2636-1571-74a1-8471-15a3b1c3f49d`

  Charley Cunningham · 2026-02-13 14:54:06 -08:00
  26a7cd21e2
• Add js_repl_tools_only model and routing restrictions (#10671)

  # 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.
  
  
  #### [git stack](https://github.com/magus/git-stack-cli)
  - ✅ `1` https://github.com/openai/codex/pull/10674
  - ✅ `2` https://github.com/openai/codex/pull/10672
  - 👉 `3` https://github.com/openai/codex/pull/10671
  - ⏳ `4` https://github.com/openai/codex/pull/10673
  - ⏳ `5` https://github.com/openai/codex/pull/10670

  Curtis 'Fjord' Hawthorne · 2026-02-12 15:41:05 -08:00
  0dcfc59171
• Add js_repl host helpers and exec end events (#10672)

  ## Summary
  
  This PR adds host-integrated helper APIs for `js_repl` and updates model
  guidance so the agent can use them reliably.
  
  ### What’s included
  
  - Add `codex.tool(name, args?)` in the JS kernel so `js_repl` can call
  normal Codex tools.
  - Keep persistent JS state and scratch-path helpers available:
    - `codex.state`
    - `codex.tmpDir`
  - Wire `js_repl` tool calls through the standard tool router path.
  - Add/align `js_repl` execution completion/end event behavior with
  existing tool logging patterns.
  - Update dynamic prompt injection (`project_doc`) to document:
    - how to call `codex.tool(...)`
    - raw output behavior
  - image flow via `view_image` (`codex.tmpDir` +
  `codex.tool("view_image", ...)`)
  - stdio safety guidance (`console.log` / `codex.tool`, avoid direct
  `process.std*`)
  
  ## Why
  
  - Standardize JS-side tool usage on `codex.tool(...)`
  - Make `js_repl` behavior more consistent with existing tool execution
  and event/logging patterns.
  - Give the model enough runtime guidance to use `js_repl` safely and
  effectively.
  
  ## Testing
  
  - Added/updated unit and runtime tests for:
    - `codex.tool` calls from `js_repl` (including shell/MCP paths)
    - image handoff flow via `view_image`
    - prompt-injection text for `js_repl` guidance
    - execution/end event behavior and related regression coverage
  
  
  
  
  #### [git stack](https://github.com/magus/git-stack-cli)
  - ✅ `1` https://github.com/openai/codex/pull/10674
  - 👉 `2` https://github.com/openai/codex/pull/10672
  - ⏳ `3` https://github.com/openai/codex/pull/10671
  - ⏳ `4` https://github.com/openai/codex/pull/10673
  - ⏳ `5` https://github.com/openai/codex/pull/10670

  Curtis 'Fjord' Hawthorne · 2026-02-12 12:10:25 -08:00
  466be55abc
• Add feature-gated freeform js_repl core runtime (#10674)

  ## Summary
  
  This PR adds an **experimental, feature-gated `js_repl` core runtime**
  so models can execute JavaScript in a persistent REPL context across
  tool calls.
  
  The implementation integrates with existing feature gating, tool
  registration, prompt composition, config/schema docs, and tests.
  
  ## What changed
  
  - Added new experimental feature flag: `features.js_repl`.
  - Added freeform `js_repl` tool and companion `js_repl_reset` tool.
  - Gated tool availability behind `Feature::JsRepl`.
  - Added conditional prompt-section injection for JS REPL instructions
  via marker-based prompt processing.
  - Implemented JS REPL handlers, including freeform parsing and pragma
  support (timeout/reset controls).
  - Added runtime resolution order for Node:
    1. `CODEX_JS_REPL_NODE_PATH`
    2. `js_repl_node_path` in config
    3. `PATH`
  - Added JS runtime assets/version files and updated docs/schema.
  
  ## Why
  
  This enables richer agent workflows that require incremental JavaScript
  execution with preserved state, while keeping rollout safe behind an
  explicit feature flag.
  
  ## Testing
  
  Coverage includes:
  
  - Feature-flag gating behavior for tool exposure.
  - Freeform parser/pragma handling edge cases.
  - Runtime behavior (state persistence across calls and top-level `await`
  support).
  
  ## Usage
  
  ```toml
  [features]
  js_repl = true
  ```
  
  Optional runtime override:
  
  - `CODEX_JS_REPL_NODE_PATH`, or
  - `js_repl_node_path` in config.
  
  #### [git stack](https://github.com/magus/git-stack-cli)
  - 👉 `1` https://github.com/openai/codex/pull/10674
  - ⏳ `2` https://github.com/openai/codex/pull/10672
  - ⏳ `3` https://github.com/openai/codex/pull/10671
  - ⏳ `4` https://github.com/openai/codex/pull/10673
  - ⏳ `5` https://github.com/openai/codex/pull/10670

  Curtis 'Fjord' Hawthorne · 2026-02-11 12:05:02 -08:00
  42e22f3bde
• tui: keep history recall cursor at line end (#11295)

  ## Summary
  - keep cursor at end-of-line after Up/Down history recall
  - allow continued history navigation when recalled text cursor is at
  start or end boundary
  - add regression tests and document the history cursor contract in
  composer docs
  
  ## Testing
  - just fmt
  - cargo test -p codex-tui --lib
  history_navigation_leaves_cursor_at_end_of_line
  - cargo test -p codex-tui --lib
  should_handle_navigation_when_cursor_is_at_line_boundaries
  - cargo test -p codex-tui *(fails in existing integration test
  `suite::no_panic_on_startup::malformed_rules_should_not_panic` because
  `target/debug/codex` is not present in this environment)*

  Josh McKinney · 2026-02-10 17:21:46 +00:00
  e704f488bd
• fix(tui): tab submits when no task running in steer mode (#10035)

  When steer mode is enabled, Tab used to only queue while a task was
  running and otherwise did nothing. Treat Tab as an immediate submit when
  no task is running so input isn't dropped when the inflight turn ends
  mid-typing.
  
  Adds a regression test and updates docs/tooltips.

  Josh McKinney · 2026-02-10 00:39:09 +00:00
  a3e4bd3bc0
• fix(tui): rehydrate drafts and restore image placeholders (#9040)

  Fixes #9050
  
  When a draft is stashed with Ctrl+C, we now persist the full draft state
  (text elements, local image paths, and pending paste payloads) in local
  history. Up/Down recall rehydrates placeholder elements and attachments
  so styling remains correct and large pastes still expand on submit.
  Persistent (cross‑session) history remains text‑only.
  
  Backtrack prefills now reuse the selected user message’s text elements
  and local image paths, so image placeholders/attachments rehydrate when
  rolling back.
  
  External editor replacements keep only attachments whose placeholders
  remain and then normalize image placeholders to `[Image #1]..[Image #N]`
  to keep the attachment mapping consistent.
  
  Docs:
  - docs/tui-chat-composer.md
  
  Testing:
  - just fix -p codex-tui
  - cargo test -p codex-tui
  
  Co-authored-by: Eric Traut <etraut@openai.com>

  Chriss4123 · 2026-02-07 20:08:45 -08:00
  d68e9c0f19
• feat(core): add configurable log_dir (#10678)

  Adds a top-level `log_dir` config key (defaults to `$CODEX_HOME/log`) so
  one-off runs can redirect `codex-tui.log` via `-c`, e.g.:
  
    codex -c log_dir=./.codex-log
  
  Also resolves relative paths in CLI `-c/--config` overrides for
  `AbsolutePathBuf` values against the effective cwd (when available).
  
  Tests:
  - cargo test -p codex-core

  Josh McKinney · 2026-02-05 01:23:30 +00:00
  cddfd1e675
• tui: make Esc clear request_user_input notes while notes are shown (#10569)

  ## Summary
  
  This PR updates the `request_user_input` TUI overlay so `Esc` is
  context-aware:
  
  - When notes are visible for an option question, `Esc` now clears notes
  and exits notes mode.
  - When notes are not visible (normal option selection UI), `Esc` still
  interrupts as before.
  
  It also updates footer guidance text to match behavior.
  
  ## Changes
  
  - Added a shared notes-clear path for option questions:
  - `Tab` and `Esc` now both clear notes and return focus to options when
  notes are visible.
  - Updated footer hint text in notes-visible state:
    - from: `tab to clear notes | ... | esc to interrupt`
    - to: `tab or esc to clear notes | ...`
  - Hid `esc to interrupt` hint while notes are visible for option
  questions.
  - Kept `esc to interrupt` visible and functional in normal
  option-selection mode.
  - Updated tests to assert the new `Esc` behavior in notes mode.
  - Updated snapshot output for the notes-visible footer row.
  - Updated docs in `docs/tui-request-user-input.md` to reflect
  mode-specific `Esc` behavior.

  Charley Cunningham · 2026-02-03 16:17:06 -08:00
  a9eb766f33
• feat(tui): pace catch-up stream chunking with hysteresis (#10461)

  ## Summary
  - preserve baseline streaming behavior (smooth mode still commits one
  line per 50ms tick)
  - extract adaptive chunking policy and commit-tick orchestration from
  ChatWidget into `streaming/chunking.rs` and `streaming/commit_tick.rs`
  - add hysteresis-based catch-up behavior with bounded batch draining to
  reduce queue lag without bursty single-frame jumps
  - document policy behavior, tuning guidance, and debug flow in rustdoc +
  docs
  
  ## Testing
  - just fmt
  - cargo test -p codex-tui

  Josh McKinney · 2026-02-03 15:01:51 -08:00
  aec58ac29b
• [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
• Nicer highlighting of slash commands, /plan accepts prompt args and pasted images (#10269)

  ## Summary
  - Make typed slash commands become text elements when the user hits
  space, including paste‑burst spaces.
  - Enable `/plan` to accept inline args and submit them in plan mode,
  mirroring `/review` behavior and blocking submission while a task is
  running.
  - Preserve text elements/attachments for slash commands that take args.
  
  <img width="1510" height="500" alt="image"
  src="https://github.com/user-attachments/assets/446024df-b69a-4249-85db-1a85110e07f1"
  />
  
  ## Changes
  - Add safe helper to insert element ranges in the textarea.
  - Extend command‑with‑args pipeline to carry text elements and reuse
  submission prep.
  - Update `/plan` dispatch to switch to plan mode then submit prompt +
  elements.
  - Document new composer behavior and add tests.
  
  ## Notes
  - `/plan` is blocked during active tasks (same as `/review`).
  - Slash‑command elementization recognizes built‑ins and `/prompts:`
  custom commands only.
  
  ## Codex author
  `codex fork 019c16d3-4520-7bb0-9b9d-48720d40a8ab`

  Charley Cunningham · 2026-02-02 09:53:29 -08:00
  3392c5af24
• Restore image attachments/text elements when recalling input history (Up/Down) (#9628)

  **Summary**
  - Up/Down input history now restores image attachments and text elements
  for local entries.
  - Composer history stores rich local entries (text + text elements +
  local image paths) while persistent history remains text-only.
  - Added tests to verify history recall rehydrates image placeholders and
  attachments in both `tui` and `tui2`.
  
  **Changes**
  - `tui/src/bottom_pane/chat_composer_history.rs`: store `HistoryEntry`
  (text + elements + image paths) for local history; adapt navigation +
  tests.
  - `tui2/src/bottom_pane/chat_composer_history.rs`: same as above.
  - `tui/src/bottom_pane/chat_composer.rs`: record rich history entries
  and restore them on Up/Down; update Ctrl+C history and tests.
  - `tui2/src/bottom_pane/chat_composer.rs`: same as above.

  Charley Cunningham · 2026-01-27 18:39:59 -08:00
  add648df82
• Updated contribution guidelines (#9933)
  Eric Traut · 2026-01-26 17:13:25 -08:00
  6a279f6d77
• Add composer config and shared menu surface helpers (#9891)

  Centralize built-in slash-command gating and extract shared menu-surface
  helpers.
  
  - Add bottom_pane::slash_commands and reuse it from composer + command
  popup.
  - Introduce ChatComposerConfig + shared menu surface rendering without
  changing default behavior.

  Ahmed Ibrahim · 2026-01-26 23:16:29 +00:00
  a8f195828b
• [connectors] Support connectors part 1 - App server & MCP (#9667)

  In order to make Codex work with connectors, we add a built-in gateway
  MCP that acts as a transparent proxy between the client and the
  connectors. The gateway MCP collects actions that are accessible to the
  user and sends them down to the user, when a connector action is chosen
  to be called, the client invokes the action through the gateway MCP as
  well.
  
   - [x] Add the system built-in gateway MCP to list and run connectors.
   - [x] Add the app server methods and protocol

  Matthew Zeng · 2026-01-22 16:48:43 -08:00
  a2c829a808
• feat(tui): retire the tui2 experiment (#9640)

  ## Summary
  - Retire the experimental TUI2 implementation and its feature flag.
  - Remove TUI2-only config/schema/docs so the CLI stays on the
  terminal-native path.
  - Keep docs aligned with the legacy TUI while we focus on redraw-based
  improvements.
  
  ## Customer impact
  - Retires the TUI2 experiment and keeps Codex on the proven
  terminal-native UI while we invest in redraw-based improvements to the
  existing experience.
  
  ## Migration / compatibility
  - If you previously set tui2-related options in config.toml, they are
  now ignored and Codex continues using the existing terminal-native TUI
  (no action required).
  
  ## Context
  - What worked: a transcript-owned viewport delivered excellent resize
  rewrap and high-fidelity copy (especially for code).
  - Why stop: making that experience feel fully native across the
  environment matrix (terminal emulator, OS, input modality, multiplexer,
  font/theme, alt-screen behavior) creates a combinatorial explosion of
  edge cases.
  - What next: we are focusing on redraw-based improvements to the
  existing terminal-native TUI so scrolling, selection, and copy remain
  native while resize/redraw correctness improves.
  
  ## Testing
  - just write-config-schema
  - just fmt
  - cargo clippy --fix --all-features --tests --allow-dirty --allow-no-vcs
  -p codex-core
  - cargo clippy --fix --all-features --tests --allow-dirty --allow-no-vcs
  -p codex-cli
  - cargo check
  - cargo test -p codex-core
  - cargo test -p codex-cli

  Josh McKinney · 2026-01-22 01:02:29 +00:00
  a489b64cb5
• Add request-user-input overlay (#9585)

  - Add request-user-input overlay and routing in the TUI

  Ahmed Ibrahim · 2026-01-21 00:19:35 -08:00
  5f55ed666b
• fix CI by running pnpm (#9587)
  Ahmed Ibrahim · 2026-01-20 20:54:15 -08:00
  465da00d02
• Prompt Expansion: Preserve Text Elements (#9518)

  Summary
  - Preserve `text_elements` through custom prompt argument parsing and
  expansion (named and numeric placeholders).
  - Translate text element ranges through Shlex parsing using sentinel
  substitution, and rehydrate text + element ranges per arg.
  - Drop image attachments when their placeholder does not survive prompt
  expansion, keeping attachments consistent with rendered elements.
  - Mirror changes in TUI2 and expand tests for prompt parsing/expansion
  edge cases.
  
  Tests
  - placeholders with spaces as single tokens (positional + key=value,
  quoted + unquoted),
    - prompt expansion with image placeholders,
    - large paste + image arg combinations,
    - unused image arg dropped after expansion.

  charley-oai · 2026-01-20 18:30:20 -08:00
  531748a080
• Rename hierarchical_agents to child_agents_md (#9215)

  Clearer name

  pakrym-oai · 2026-01-14 19:14:24 +00:00
  e6d2ef432d
• tui: double-press Ctrl+C/Ctrl+D to quit (#8936)

  ## Problem
  
  Codex’s TUI quit behavior has historically been easy to trigger
  accidentally and hard to reason
  about.
  
  - `Ctrl+C`/`Ctrl+D` could terminate the UI immediately, which is a
  common key to press while trying
    to dismiss a modal, cancel a command, or recover from a stuck state.
  - “Quit” and “shutdown” were not consistently separated, so some exit
  paths could bypass the
    shutdown/cleanup work that should run before the process terminates.
  
  This PR makes quitting both safer (harder to do by accident) and more
  uniform across quit
  gestures, while keeping the shutdown-first semantics explicit.
  
  ## Mental model
  
  After this change, the system treats quitting as a UI request that is
  coordinated by the app
  layer.
  
  - The UI requests exit via `AppEvent::Exit(ExitMode)`.
  - `ExitMode::ShutdownFirst` is the normal user path: the app triggers
  `Op::Shutdown`, continues
  rendering while shutdown runs, and only ends the UI loop once shutdown
  has completed.
  - `ExitMode::Immediate` exists as an escape hatch (and as the
  post-shutdown “now actually exit”
  signal); it bypasses cleanup and should not be the default for
  user-triggered quits.
  
  User-facing quit gestures are intentionally “two-step” for safety:
  
  - `Ctrl+C` and `Ctrl+D` no longer exit immediately.
  - The first press arms a 1-second window and shows a footer hint (“ctrl
  + <key> again to quit”).
  - Pressing the same key again within the window requests a
  shutdown-first quit; otherwise the
    hint expires and the next press starts a fresh window.
  
  Key routing remains modal-first:
  
  - A modal/popup gets first chance to consume `Ctrl+C`.
  - If a modal handles `Ctrl+C`, any armed quit shortcut is cleared so
  dismissing a modal cannot
    prime a subsequent `Ctrl+C` to quit.
  - `Ctrl+D` only participates in quitting when the composer is empty and
  no modal/popup is active.
  
  The design doc `docs/exit-confirmation-prompt-design.md` captures the
  intended routing and the
  invariants the UI should maintain.
  
  ## Non-goals
  
  - This does not attempt to redesign modal UX or make modals uniformly
  dismissible via `Ctrl+C`.
  It only ensures modals get priority and that quit arming does not leak
  across modal handling.
  - This does not introduce a persistent confirmation prompt/menu for
  quitting; the goal is to keep
    the exit gesture lightweight and consistent.
  - This does not change the semantics of core shutdown itself; it changes
  how the UI requests and
    sequences it.
  
  ## Tradeoffs
  
  - Quitting via `Ctrl+C`/`Ctrl+D` now requires a deliberate second
  keypress, which adds friction for
    users who relied on the old “instant quit” behavior.
  - The UI now maintains a small time-bounded state machine for the armed
  shortcut, which increases
    complexity and introduces timing-dependent behavior.
  
  This design was chosen over alternatives (a modal confirmation prompt or
  a long-lived “are you
  sure” state) because it provides an explicit safety barrier while
  keeping the flow fast and
  keyboard-native.
  
  ## Architecture
  
  - `ChatWidget` owns the quit-shortcut state machine and decides when a
  quit gesture is allowed
    (idle vs cancellable work, composer state, etc.).
  - `BottomPane` owns rendering and local input routing for modals/popups.
  It is responsible for
  consuming cancellation keys when a view is active and for
  showing/expiring the footer hint.
  - `App` owns shutdown sequencing: translating
  `AppEvent::Exit(ShutdownFirst)` into `Op::Shutdown`
    and only terminating the UI loop when exit is safe.
  
  This keeps “what should happen” decisions (quit vs interrupt vs ignore)
  in the chat/widget layer,
  while keeping “how it looks and which view gets the key” in the
  bottom-pane layer.
  
  ## Observability
  
  You can tell this is working by running the TUIs and exercising the quit
  gestures:
  
  - While idle: pressing `Ctrl+C` (or `Ctrl+D` with an empty composer and
  no modal) shows a footer
  hint for ~1 second; pressing again within that window exits via
  shutdown-first.
  - While streaming/tools/review are active: `Ctrl+C` interrupts work
  rather than quitting.
  - With a modal/popup open: `Ctrl+C` dismisses/handles the modal (if it
  chooses to) and does not
  arm a quit shortcut; a subsequent quick `Ctrl+C` should not quit unless
  the user re-arms it.
  
  Failure modes are visible as:
  
  - Quits that happen immediately (no hint window) from `Ctrl+C`/`Ctrl+D`.
  - Quits that occur while a modal is open and consuming `Ctrl+C`.
  - UI termination before shutdown completes (cleanup skipped).
  
  ## Tests
  
  - Updated/added unit and snapshot coverage in `codex-tui` and
  `codex-tui2` to validate:
    - The quit hint appears and expires on the expected key.
  - Double-press within the window triggers a shutdown-first quit request.
  - Modal-first routing prevents quit bypass and clears any armed shortcut
  when a modal consumes
      `Ctrl+C`.
  
  These tests focus on the UI-level invariants and rendered output; they
  do not attempt to validate
  real terminal key-repeat timing or end-to-end process shutdown behavior.
  
  ---
  Screenshot:
  <img width="912" height="740" alt="Screenshot 2026-01-13 at 1 05 28 PM"
  src="https://github.com/user-attachments/assets/18f3d22e-2557-47f2-a369-ae7a9531f29f"
  />

  Josh McKinney · 2026-01-14 17:42:52 +00:00
  4283a7432b
• fix(tui): harden paste-burst state transitions (#9124)

  User-facing symptom: On terminals that deliver pastes as rapid
  KeyCode::Char/Enter streams (notably Windows), paste-burst transient
  state
  can leak into the next input. Users can see Enter insert a newline when
  they meant to submit, or see characters appear late / handled through
  the
  wrong path.
  
  System problem: PasteBurst is time-based. Clearing only the
  classification window (e.g. via clear_window_after_non_char()) can erase
  last_plain_char_time without emitting buffered text. If a buffer is
  still
  non-empty after that, flush_if_due() no longer has a timeout clock to
  flush against, so the buffer can get "stuck" until another plain char
  arrives.
  
  This was surfaced while adding deterministic regression tests for
  paste-burst behavior.
  
  Fix: when disabling burst detection, defuse any in-flight burst state:
  flush held/buffered text through handle_paste() (so it follows normal
  paste integration), then clear timing and Enter suppression.
  
  Document the rationale inline and update docs/tui-chat-composer.md so
  "disable_paste_burst" matches the actual behavior.

  Josh McKinney · 2026-01-14 01:42:21 +00:00
  ce49e92848
• fix(tui): document paste-burst state machine (#9020)

  Add a narrative doc and inline rustdoc explaining how `ChatComposer`
  and `PasteBurst` compose into a single state machine on terminals that
  lack reliable bracketed paste (notably Windows).
  
  This documents the key states, invariants, and integration points
  (`handle_input_basic`, `handle_non_ascii_char`, tick-driven flush) so
  future changes are easier to reason about.

  Josh McKinney · 2026-01-13 11:48:31 -08:00
  58e8f75b27
• add generated jsonschema for config.toml (#8956)

  ### What
  Add JSON Schema generation for `config.toml`, with checked‑in
  `docs/config.schema.json`. We can move the schema elsewhere if preferred
  (and host it if there's demand).
  
  Add fixture test to prevent drift and `just write-config-schema` to
  regenerate on schema changes.
  
  Generate MCP config schema from `RawMcpServerConfig` instead of
  `McpServerConfig` because that is the runtime type used for
  deserialization.
  
  Populate feature flag values into generated schema so they can be
  autocompleted.
  
  ### Tests
  Added tests + regenerate script to prevent drift. Tested autocompletions
  using generated jsonschema locally with Even Better TOML.
  
  
  
  https://github.com/user-attachments/assets/5aa7cd39-520c-4a63-96fb-63798183d0bc

  sayan-oai · 2026-01-13 10:22:51 -08:00
  40e2405998
• Add hierarchical agent prompt (#8996)
  pakrym-oai · 2026-01-09 13:47:37 -08:00
  acfd94f625
• fix: add tui.alternate_screen config and --no-alt-screen CLI flag for Zellij scrollback (#8555)

  Fixes #2558
  
  Codex uses alternate screen mode (CSI 1049) which, per xterm spec,
  doesn't support scrollback. Zellij follows this strictly, so users can't
  scroll back through output.
  
  **Changes:**
  - Add `tui.alternate_screen` config: `auto` (default), `always`, `never`
  - Add `--no-alt-screen` CLI flag
  - Auto-detect Zellij and skip alt screen (uses existing `ZELLIJ` env var
  detection)
  
  **Usage:**
  ```bash
  # CLI flag
  codex --no-alt-screen
  
  # Or in config.toml
  [tui]
  alternate_screen = "never"
  ```
  
  With default `auto` mode, Zellij users get working scrollback without
  any config changes.
  
  ---------
  
  Co-authored-by: Josh McKinney <joshka@openai.com>

  Helmut Januschka · 2026-01-09 18:38:26 +00:00
  7daaabc795
• chore: nuke telemetry file (#8985)
  jif-oai · 2026-01-09 08:55:21 -08:00
  46b0c4acbb
• feat: add a few metrics (#8910)
  jif-oai · 2026-01-08 15:39:57 +00:00
  5522663f92
• feat: metrics capabilities (#8318)

  Add metrics capabilities to Codex. The `README.md` is up to date.
  
  This will not be merged with the metrics before this PR of course:
  https://github.com/openai/codex/pull/8350

  jif-oai · 2026-01-08 11:47:36 +00:00
  634650dd25
• perf(tui2): cache transcript view rendering (#8693)

  The transcript viewport draws every frame. Ratatui's Line::render_ref
  does grapheme segmentation and span layout, so repeated redraws can burn
  CPU during streaming even when the visible transcript hasn't changed.
  
  Introduce TranscriptViewCache to reduce per-frame work:
  - WrappedTranscriptCache memoizes flattened+wrapped transcript lines per
  width, appends incrementally as new cells arrive, and rebuilds on width
  change, truncation (backtrack), or transcript replacement.
  - TranscriptRasterCache caches rasterized rows (Vec<Cell>) per line
  index and user-row styling; redraws copy cells instead of rerendering
  spans.
  
  The caches are width-scoped and store base transcript content only;
  selection highlighting and copy affordances are applied after drawing.
  User rows include the row-wide base style in the cached raster.
  
  Refactor transcript_render to expose append_wrapped_transcript_cell for
  incremental building and add a test that incremental append matches the
  full build.
  
  Add docs/tui2/performance-testing.md as a playbook for macOS sample
  profiles and hotspot greps.
  
  Expand transcript_view_cache tests to cover rebuild conditions, raster
  equivalence vs direct rendering, user-row caching, and eviction.
  
  Test: cargo test -p codex-tui2

  Josh McKinney · 2026-01-03 11:44:27 -08:00
  90f37e8549
• chore: update outdated docs (#8701)
  Thibault Sottiaux · 2026-01-03 02:19:52 -08:00
  ee9d441777
• Replaced user documentation with links to developers docs site (#8662)

  This eliminates redundant user documentation and allows us to focus our
  documentation investments.
  
  I left tombstone files for most of the existing ".md" docs files to
  avoid broken links. These now contain brief links to the developers docs
  site.

  Eric Traut · 2026-01-02 13:01:53 -07:00
  ab753387cc
• 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
• feat: add support for project_root_markers in config.toml (#8359)

  - allow configuring `project_root_markers` in `config.toml`
  (user/system/MDM) to control project discovery beyond `.git`
  - honor the markers after merging pre-project layers; default to
  `[".git"]` when unset and skip ancestor walk when set to an empty array
  - document the option and add coverage for alternate markers in config
  loader tests

  Michael Bolin · 2025-12-22 19:45:45 +00:00
  314937fb11
• chore: drop undo from the docs (#8431)
  jif-oai · 2025-12-22 15:09:48 +00:00
  45727b9ed3
• docs: add developer_instructions config option and update descriptions (#8376)

  Updates the configuration documentation to clarify and improve the
  description of the `developer_instructions` and `instructions` fields.
  
  Documentation updates:
  
  * Added a description for the `developer_instructions` field in
  `docs/config.md`, clarifying that it provides additional developer
  instructions.
  * Updated the comments in `docs/example-config.md` to specify that
  `developer_instructions` is injected before `AGENTS.md`, and clarified
  that the `instructions` field is ignored and that `AGENTS.md` is
  preferred.
  
  ___
  
  ref #7973 
  
  Thanks to @miraclebakelaser for the message. I have double-confirmed
  that developer instructions are always injected before user
  instructions. According to the source code
  [codex_core::codex::Session::build_initial_context](https://github.com/openai/codex/blob/rust-v0.77.0-alpha.2/codex-rs/core/src/codex.rs#L1279),
  we can see the specific order of these instructions.

  Robby He · 2025-12-22 07:37:37 -07:00
  372de6d2c5
• Update ghost_commit flag reference to undo (#8091)

  Minor documentation update to fix #7966 (documentation of undo flag).

  Charlie Weems · 2025-12-21 23:27:54 -08:00
  99cbba8ea5
• Point skills docs to developer documentation site (#8407)
  Eric Traut · 2025-12-21 16:18:58 -08:00
  d281bcfcd4
• Chore: remove rmcp feature and exp flag usages (#8087)

  ### Summary
  With codesigning on Mac, Windows and Linux, we should be able to safely
  remove `features.rmcp_client` and `use_experimental_use_rmcp_client`
  check from the codebase now.

  Shijie Rao · 2025-12-20 14:18:00 -08:00
  987dd7fde3
• feat(tui2): tune scrolling inpu based on (#8357)

  ## TUI2: Normalize Mouse Scroll Input Across Terminals (Wheel +
  Trackpad)
  
  This changes TUI2 scrolling to a stream-based model that normalizes
  terminal scroll event density into consistent wheel behavior (default:
  ~3 transcript lines per physical wheel notch) while keeping trackpad
  input higher fidelity via fractional accumulation.
  
  Primary code: `codex-rs/tui2/src/tui/scrolling/mouse.rs`
  
  Doc of record (model + probe-derived data):
  `codex-rs/tui2/docs/scroll_input_model.md`
  
  ### Why
  
  Terminals encode both mouse wheels and trackpads as discrete scroll
  up/down events with direction but no magnitude, and they vary widely in
  how many raw events they emit per physical wheel notch (commonly 1, 3,
  or 9+). Timing alone doesn’t reliably distinguish wheel vs trackpad, so
  cadence-based heuristics are unstable across terminals/hardware.
  
  This PR treats scroll input as short *streams* separated by silence or
  direction flips, normalizes raw event density into tick-equivalents,
  coalesces redraws for dense streams, and exposes explicit config
  overrides.
  
  ### What Changed
  
  #### Scroll Model (TUI2)
  
  - Stream detection
    - Start a stream on the first scroll event.
    - End a stream on an idle gap (`STREAM_GAP_MS`) or a direction flip.
  - Normalization
  - Convert raw events into tick-equivalents using per-terminal
  `tui.scroll_events_per_tick`.
  - Wheel-like vs trackpad-like behavior
  - Wheel-like: fixed “classic” lines per wheel notch; flush immediately
  for responsiveness.
  - Trackpad-like: fractional accumulation + carry across stream
  boundaries; coalesce flushes to ~60Hz to avoid floods and reduce “stop
  lag / overshoot”.
  - Trackpad divisor is intentionally capped: `min(scroll_events_per_tick,
  3)` so terminals with dense wheel ticks (e.g. 9 events per notch) don’t
  make trackpads feel artificially slow.
  - Auto mode (default)
    - Start conservatively as trackpad-like (avoid overshoot).
  - Promote to wheel-like if the first tick-worth of events arrives
  quickly.
  - Fallback for 1-event-per-tick terminals (no tick-completion timing
  signal).
  
  #### Trackpad Acceleration
  
  Some terminals produce relatively low vertical event density for
  trackpad gestures, which makes large/faster swipes feel sluggish even
  when small motions feel correct. To address that, trackpad-like streams
  apply a bounded multiplier based on event count:
  
  - `multiplier = clamp(1 + abs(events) / scroll_trackpad_accel_events,
  1..scroll_trackpad_accel_max)`
  
  The multiplier is applied to the trackpad stream’s computed line delta
  (including carried fractional remainder). Defaults are conservative and
  bounded.
  
  #### Config Knobs (TUI2)
  
  All keys live under `[tui]`:
  
  - `scroll_wheel_lines`: lines per physical wheel notch (default: 3).
  - `scroll_events_per_tick`: raw vertical scroll events per physical
  wheel notch (terminal-specific default; fallback: 3).
  - Wheel-like per-event contribution: `scroll_wheel_lines /
  scroll_events_per_tick`.
  - `scroll_trackpad_lines`: baseline trackpad sensitivity (default: 1).
  - Trackpad-like per-event contribution: `scroll_trackpad_lines /
  min(scroll_events_per_tick, 3)`.
  - `scroll_trackpad_accel_events` / `scroll_trackpad_accel_max`: bounded
  trackpad acceleration (defaults: 30 / 3).
  - `scroll_mode = auto|wheel|trackpad`: force behavior or use the
  heuristic (default: `auto`).
  - `scroll_wheel_tick_detect_max_ms`: auto-mode promotion threshold (ms).
  - `scroll_wheel_like_max_duration_ms`: auto-mode fallback for
  1-event-per-tick terminals (ms).
  - `scroll_invert`: invert scroll direction (applies to wheel +
  trackpad).
  
  Config docs: `docs/config.md` and field docs in
  `codex-rs/core/src/config/types.rs`.
  
  #### App Integration
  
  - The app schedules follow-up ticks to close idle streams (via
  `ScrollUpdate::next_tick_in` and `schedule_frame_in`) and finalizes
  streams on draw ticks.
    - `codex-rs/tui2/src/app.rs`
  
  #### Docs
  
  - Single doc of record describing the model + preserved probe
  findings/spec:
    - `codex-rs/tui2/docs/scroll_input_model.md`
  
  #### Other (jj-only friendliness)
  
  - `codex-rs/tui2/src/diff_render.rs`: prefer stable cwd-relative paths
  when the file is under the cwd even if there’s no `.git`.
  
  ### Terminal Defaults
  
  Per-terminal defaults are derived from scroll-probe logs (see doc).
  Notable:
  
  - Ghostty currently defaults to `scroll_events_per_tick = 3` even though
  logs measured ~9 in one setup. This is a deliberate stopgap; if your
  Ghostty build emits ~9 events per wheel notch, set:
  
    ```toml
    [tui]
    scroll_events_per_tick = 9
    ```
  
  ### Testing
  
  - `just fmt`
  - `just fix -p codex-core --allow-no-vcs`
  - `cargo test -p codex-core --lib` (pass)
  - `cargo test -p codex-tui2` (scroll tests pass; remaining failures are
  known flaky VT100 color tests in `insert_history`)
  
  ### Review Focus
  
  - Stream finalization + frame scheduling in `codex-rs/tui2/src/app.rs`.
  - Auto-mode promotion thresholds and the 1-event-per-tick fallback
  behavior.
  - Trackpad divisor cap (`min(events_per_tick, 3)`) and acceleration
  defaults.
  - Ghostty default tradeoff (3 vs ~9) and whether we should change it.

  Josh McKinney · 2025-12-20 12:48:12 -08:00
  63942b883c
• Fix link to contributing.md in experimental.md (#8311)

  # 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.

  jdijk-deventit · 2025-12-19 09:42:56 -08:00
  b15b5082c6
• Set exclude to true by default in app server (#8281)
  Andrew Ambrosino · 2025-12-18 14:28:30 -08:00
  9fb9ed6cea
• docs: clarify codex resume --all (CWD column & filtering) (#8264)

  This pull request makes a small update to the session picker
  documentation for `codex resume`. The main change clarifies how to view
  the original working directory (CWD) for sessions and when the Git
  branch is shown.
  
  - The session picker now displays the recorded Git branch when
  available, and instructions are added for showing the original working
  directory by using the `--all` flag, which also disables CWD filtering
  and adds a `CWD` column.

  Magson Leone dos Santos · 2025-12-18 16:54:50 +00:00
  4c9d589f14
• fix: PathBuf -> AbsolutePathBuf in ConfigToml struct (#8205)

  We should not have any `PathBuf` fields in `ConfigToml` or any of the
  transitive structs we include, as we should use `AbsolutePathBuf`
  instead so that we do not have to keep track of the file from which
  `ConfigToml` was loaded such that we need it to resolve relative paths
  later when the values of `ConfigToml` are used.
  
  I only found two instances of this: `experimental_instructions_file` and
  `experimental_compact_prompt_file`. Incidentally, when these were
  specified as relative paths, they were resolved against `cwd` rather
  than `config.toml`'s parent, which seems wrong to me. I changed the
  behavior so they are resolved against the parent folder of the
  `config.toml` being parsed, which we get "for free" due to the
  introduction of `AbsolutePathBufGuard ` in
  https://github.com/openai/codex/pull/7796.
  
  While it is not great to change the behavior of a released feature,
  these fields are prefixed with `experimental_`, which I interpret to
  mean we have the liberty to change the contract.
  
  For reference:
  
  - `experimental_instructions_file` was introduced in
  https://github.com/openai/codex/pull/1803
  - `experimental_compact_prompt_file` was introduced in
  https://github.com/openai/codex/pull/5959

  Michael Bolin · 2025-12-17 12:08:18 -08:00
  1e9babe178
• feat: add config to disable warnings around ghost snapshot (#8178)
  jif-oai · 2025-12-17 18:50:22 +00:00
  3d92b443b0
• feat: experimental menu (#8071)

  This will automatically render any `Stage::Beta` features.
  
  The change only gets applied to the *next session*. This started as a
  bug but actually this is a good thing to prevent out of distribution
  push
  
  <img width="986" height="288" alt="Screenshot 2025-12-15 at 15 38 35"
  src="https://github.com/user-attachments/assets/78b7a71d-0e43-4828-a118-91c5237909c7"
  />
  
  
  <img width="509" height="109" alt="Screenshot 2025-12-15 at 17 35 44"
  src="https://github.com/user-attachments/assets/6933de52-9b66-4abf-b58b-a5f26d5747e2"
  />

  jif-oai · 2025-12-17 17:08:03 +00:00
  ac6ba286aa
• feat: if .codex is a sub-folder of a writable root, then make it read-only to the sandbox (#8088)

  In preparation for in-repo configuration support, this updates
  `WritableRoot::get_writable_roots_with_cwd()` to include the `.codex`
  subfolder in `WritableRoot.read_only_subpaths`, if it exists, as we
  already do for `.git`.
  
  As noted, currently, like `.git`, `.codex` will only be read-only under
  macOS Seatbelt, but we plan to bring support to other OSes, as well.
  
  Updated the integration test in `seatbelt.rs` so that it actually
  attempts to run the generated Seatbelt commands, verifying that:
  
  - trying to write to `.codex/config.toml` in a writable root fails
  - trying to write to `.git/hooks/pre-commit` in a writable root fails
  - trying to write to the writable root containing the `.codex` and
  `.git` subfolders succeeds

  Michael Bolin · 2025-12-15 22:54:43 -08:00
  bef36f4ae7
• docs: fix gpt-5.2 typo in config.md (#8079)

  Fix small typo in docs/config.md: `gpt5-2` -> `gpt-5.2`

  Lucas Kim · 2025-12-15 15:15:14 -08:00
  54def78a22
• Fixed formatting issue (#8069)
  Eric Traut · 2025-12-15 06:18:33 -08:00
  5b472c933d