221 Commits

• 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
• Update config.md (#8066)

  Update supporting docs with the actual options

  Mikhail Beliakov · 2025-12-15 06:12:52 -08:00
  4501c0ece4
• feat: config ghost commits (#7873)
  jif-oai · 2025-12-15 09:13:06 +01:00
  4274e6189a
• docs: document enabling experimental skills (#8024)

  ## Notes
  
  Skills are behind the experimental `skills` feature flag (disabled by
  default), but the skills guide didn't explain how to turn them on.
  
  - Add an explicit enable section to `docs/skills.md` (config +
  `--enable`)
  - Add the skills flag to `docs/config.md` and `docs/example-config.md`
  - Document the `/skills` slash command

  Victor Vannara · 2025-12-14 14:34:22 -08:00
  7c6a47958a
• docs: clarify xhigh reasoning effort on gpt-5.2 (#7911)

  ## Changes
  - Update config docs and example config comments to state that "xhigh"
  is supported on gpt-5.2 as well as gpt-5.1-codex-max
  - Adjust the FAQ model-support section to reflect broader xhigh
  availability

  Victor Vannara · 2025-12-11 21:18:47 -08:00
  190fa9e104
• Fix toasts on Windows under WSL 2 (#7137)

  Before this: no notifications or toasts when using Codex CLI in WSL 2.
  
  After this: I get toasts from Codex

  dank-openai · 2025-12-11 15:09:00 -08:00
  36610d975a
• fix: policy/*.codexpolicy -> rules/*.rules (#7888)

  We decided that `*.rules` is a more fitting (and concise) file extension
  than `*.codexpolicy`, so we are changing the file extension for the
  "execpolicy" effort. We are also changing the subfolder of `$CODEX_HOME`
  from `policy` to `rules` to match.
  
  This PR updates the in-repo docs and we will update the public docs once
  the next CLI release goes out.
  
  Locally, I created `~/.codex/rules/default.rules` with the following
  contents:
  
  ```
  prefix_rule(pattern=["gh", "pr", "view"])
  ```
  
  And then I asked Codex to run:
  
  ```
  gh pr view 7888 --json title,body,comments
  ```
  
  and it was able to!

  Michael Bolin · 2025-12-11 14:46:00 -08:00
  e0d7ac51d3
• remove release script (#7885)
  Ahmed Ibrahim · 2025-12-11 13:40:48 -08:00
  c4f3f566a5