feat: show Config overview at start of exec (#1073)

Now the `exec` output starts with something like:

```
--------
workdir:  /Users/mbolin/code/codex/codex-rs
model:  o3
provider:  openai
approval:  Never
sandbox:  SandboxPolicy { permissions: [DiskFullReadAccess, DiskWritePlatformUserTempFolder, DiskWritePlatformGlobalTempFolder, DiskWriteCwd, DiskWriteFolder { folder: "/Users/mbolin/.pyenv/shims" }] }
--------
```

which makes it easier to reason about when looking at logs.

.codespellignore

@@ -0,0 +1 @@
+iTerm

.codespellrc

@@ -0,0 +1,6 @@
+[codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = .git*,vendor,*-lock.yaml,*.lock,.codespellrc,*test.ts
+check-hidden = true
+ignore-regex = ^\s*"image/\S+": ".*|\b(afterAll)\b
+ignore-words-list = ratatui,ser

.github/workflows/cla.yml

@@ -23,7 +23,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          path-to-document: docs/CLA.md
+          path-to-document: https://github.com/openai/codex/blob/main/docs/CLA.md
           path-to-signatures: signatures/cla.json
           branch: cla-signatures
           allowlist: dependabot[bot]

.github/workflows/codespell.yml

@@ -0,0 +1,27 @@
+# Codespell configuration is within .codespellrc
+---
+name: Codespell
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Annotate locations with typos
+        uses: codespell-project/codespell-problem-matcher@b80729f885d32f78a716c2f107b4db1025001c42 # v1
+      - name: Codespell
+        uses: codespell-project/actions-codespell@406322ec52dd7b488e48c1c4b82e2a8b3a1bf630 # v2
+        with:
+          ignore_words_file: .codespellignore

.github/workflows/rust-ci.yml

@@ -26,7 +26,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@1.87
+        with:
+          components: rustfmt
       - name: cargo fmt
         run: cargo fmt -- --config imports_granularity=Item --check
 
@@ -58,9 +60,10 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@1.87
         with:
           targets: ${{ matrix.target }}
+          components: clippy
 
       - uses: actions/cache@v4
         with:

.github/workflows/rust-release.yml

@@ -74,7 +74,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@1.87
         with:
           targets: ${{ matrix.target }}
 
@@ -115,13 +115,42 @@ jobs:
       - name: Compress artifacts
         shell: bash
         run: |
+          # Path that contains the uncompressed binaries for the current
+          # ${{ matrix.target }}
           dest="dist/${{ matrix.target }}"
-          zstd -T0 -19 --rm "$dest"/*
+
+          # For compatibility with environments that lack the `zstd` tool we
+          # additionally create a `.tar.gz` alongside every single binary that
+          # we publish. The end result is:
+          #   codex-<target>.zst          (existing)
+          #   codex-<target>.tar.gz       (new)
+          #   ...same naming for codex-exec-* and codex-linux-sandbox-*
+
+          # 1. Produce a .tar.gz for every file in the directory *before* we
+          #    run `zstd --rm`, because that flag deletes the original files.
+          for f in "$dest"/*; do
+            base="$(basename "$f")"
+            # Skip files that are already archives (shouldn't happen, but be
+            # safe).
+            if [[ "$base" == *.tar.gz ]]; then
+              continue
+            fi
+
+            # Create per-binary tar.gz
+            tar -C "$dest" -czf "$dest/${base}.tar.gz" "$base"
+
+            # Also create .zst (existing behaviour) *and* remove the original
+            # uncompressed binary to keep the directory small.
+            zstd -T0 -19 --rm "$dest/$base"
+          done
 
       - uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.target }}
-          path: codex-rs/dist/${{ matrix.target }}/*
+          # Upload the per-binary .zst files as well as the new .tar.gz
+          # equivalents we generated in the previous step.
+          path: |
+            codex-rs/dist/${{ matrix.target }}/*
 
   release:
     needs: build

.gitignore

@@ -77,3 +77,7 @@ yarn.lock
 package.json-e
 session.ts-e
 CHANGELOG.ignore.md
+
+# nix related
+.direnv
+.envrc

AGENTS.md

@@ -0,0 +1,5 @@
+# Rust/codex-rs
+
+In the codex-rs folder where the rust code lives:
+
+- Never add or modify any code related to `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR`. You operate in a sandbox where `CODEX_SANDBOX_NETWORK_DISABLED=1` will be set whenever you use the `shell` tool. Any existing code that uses `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` was authored with this fact in mind. It is often used to early exit out of tests that the author knew you would not be able to run given your sandbox limitations.

CHANGELOG.md

@@ -2,6 +2,48 @@
 
 You can install any of these versions: `npm install -g codex@version`
 
+## `0.1.2505172129`
+
+### 🪲 Bug Fixes
+
+- Add node version check (#1007)
+- Persist token after refresh (#1006)
+
+## `0.1.2505171619`
+
+- `codex --login` + `codex --free` (#998)
+
+## `0.1.2505161800`
+
+- Sign in with chatgpt credits (#974)
+- Add support for OpenAI tool type, local_shell (#961)
+
+## `0.1.2505161243`
+
+- Sign in with chatgpt (#963)
+- Session history viewer (#912)
+- Apply patch issue when using different cwd (#942)
+- Diff command for filenames with special characters (#954)
+
+## `0.1.2505160811`
+
+- `codex-mini-latest` (#951)
+
+## `0.1.2505140839`
+
+### 🪲 Bug Fixes
+
+- Gpt-4.1 apply_patch handling (#930)
+- Add support for fileOpener in config.json (#911)
+- Patch in #366 and #367 for marked-terminal (#916)
+- Remember to set lastIndex = 0 on shared RegExp (#918)
+- Always load version from package.json at runtime (#909)
+- Tweak the label for citations for better rendering (#919)
+- Tighten up some logic around session timestamps and ids (#922)
+- Change EventMsg enum so every variant takes a single struct (#925)
+- Reasoning default to medium, show workdir when supplied (#931)
+- Test_dev_null_write() was not using echo as intended (#923)
+
 ## `0.1.2504301751`
 
 ### 🚀 Features

README.md

@@ -98,12 +98,14 @@ export OPENAI_API_KEY="your-api-key-here"
 >
 > - openai (default)
 > - openrouter
+> - azure
 > - gemini
 > - ollama
 > - mistral
 > - deepseek
 > - xai
 > - groq
+> - arceeai
 > - any other provider that is compatible with the OpenAI API
 >
 > If you use a provider other than OpenAI, you will need to set the API key for the provider in the config file or in the environment variable as:
@@ -226,13 +228,13 @@ Key flags: `--model/-m`, `--approval-mode/-a`, `--quiet/-q`, and `--notify`.
 
 ## Memory & project docs
 
-Codex merges Markdown instructions in this order:
+You can give Codex extra instructions and guidance using `AGENTS.md` files. Codex looks for `AGENTS.md` files in the following places, and merges them top-down:
 
-1. `~/.codex/instructions.md` - personal global guidance
-2. `codex.md` at repo root - shared project notes
-3. `codex.md` in cwd - sub-package specifics
+1. `~/.codex/AGENTS.md` - personal global guidance
+2. `AGENTS.md` at repo root - shared project notes
+3. `AGENTS.md` in the current working directory - sub-folder/feature specifics
 
-Disable with `--no-project-doc` or `CODEX_DISABLE_PROJECT_DOC=1`.
+Disable loading of these files with `--no-project-doc` or the environment variable `CODEX_DISABLE_PROJECT_DOC=1`.
 
 ---
 
@@ -394,6 +396,11 @@ Below is a comprehensive example of `config.json` with multiple custom providers
       "baseURL": "https://api.openai.com/v1",
       "envKey": "OPENAI_API_KEY"
     },
+    "azure": {
+      "name": "AzureOpenAI",
+      "baseURL": "https://YOUR_PROJECT_NAME.openai.azure.com/openai",
+      "envKey": "AZURE_OPENAI_API_KEY"
+    },
     "openrouter": {
       "name": "OpenRouter",
       "baseURL": "https://openrouter.ai/api/v1",
@@ -428,6 +435,11 @@ Below is a comprehensive example of `config.json` with multiple custom providers
       "name": "Groq",
       "baseURL": "https://api.groq.com/openai/v1",
       "envKey": "GROQ_API_KEY"
+    },
+    "arceeai": {
+      "name": "ArceeAI",
+      "baseURL": "https://conductor.arcee.ai/v1",
+      "envKey": "ARCEEAI_API_KEY"
     }
   },
   "history": {
@@ -440,7 +452,7 @@ Below is a comprehensive example of `config.json` with multiple custom providers
 
 ### Custom instructions
 
-You can create a `~/.codex/instructions.md` file to define custom instructions:
+You can create a `~/.codex/AGENTS.md` file to define custom guidance for the agent:
 
 ```markdown
 - Always respond with emojis
@@ -455,6 +467,10 @@ For each AI provider, you need to set the corresponding API key in your environm
 # OpenAI
 export OPENAI_API_KEY="your-api-key-here"
 
+# Azure OpenAI
+export AZURE_OPENAI_API_KEY="your-azure-api-key-here"
+export AZURE_OPENAI_API_VERSION="2025-03-01-preview" (Optional)
+
 # OpenRouter
 export OPENROUTER_API_KEY="your-openrouter-key-here"
 
@@ -636,17 +652,21 @@ The **DCO check** blocks merges until every commit in the PR carries the footer
 
 ### Releasing `codex`
 
-To publish a new version of the CLI, run the following in the `codex-cli` folder to stage the release in a temporary directory:
+To publish a new version of the CLI you first need to stage the npm package. A
+helper script in `codex-cli/scripts/` does all the heavy lifting. Inside the
+`codex-cli` folder run:
 
-```
+```bash
+# Classic, JS implementation that includes small, native binaries for Linux sandboxing.
 pnpm stage-release
-```
 
-Note you can specify the folder for the staged release:
-
-```
+# Optionally specify the temp directory to reuse between runs.
 RELEASE_DIR=$(mktemp -d)
-pnpm stage-release "$RELEASE_DIR"
+pnpm stage-release --tmp "$RELEASE_DIR"
+
+# "Fat" package that additionally bundles the native Rust CLI binaries for
+# Linux. End-users can then opt-in at runtime by setting CODEX_RUST=1.
+pnpm stage-release --native
 ```
 
 Go to the folder where the release is staged and verify that it works as intended. If so, run the following from the temp folder:
@@ -665,7 +685,9 @@ Prerequisite: Nix >= 2.4 with flakes enabled (`experimental-features = nix-comma
 Enter a Nix development shell:
 
 ```bash
-nix develop
+# Use either one of the commands according to which implementation you want to work with
+nix develop .#codex-cli # For entering codex-cli specific shell
+nix develop .#codex-rs # For entering codex-rs specific shell
 ```
 
 This shell includes Node.js, installs dependencies, builds the CLI, and provides a `codex` command alias.
@@ -673,14 +695,29 @@ This shell includes Node.js, installs dependencies, builds the CLI, and provides
 Build and run the CLI directly:
 
 ```bash
-nix build
+# Use either one of the commands according to which implementation you want to work with
+nix build .#codex-cli # For building codex-cli
+nix build .#codex-rs # For building codex-rs
 ./result/bin/codex --help
 ```
 
 Run the CLI via the flake app:
 
 ```bash
-nix run .#codex
+# Use either one of the commands according to which implementation you want to work with
+nix run .#codex-cli # For running codex-cli
+nix run .#codex-rs # For running codex-rs
+```
+
+Use direnv with flakes
+
+If you have direnv installed, you can use the following `.envrc` to automatically enter the Nix shell when you `cd` into the project directory:
+
+```bash
+cd codex-rs
+echo "use flake ../flake.nix#codex-cli" >> .envrc && direnv allow
+cd codex-cli
+echo "use flake ../flake.nix#codex-rs" >> .envrc && direnv allow
 ```
 
 ---

codex-cli/.eslintrc.cjs

@@ -1,6 +1,6 @@
 module.exports = {
   root: true,
-  env: { browser: true, es2020: true },
+  env: { browser: true, node: true, es2020: true },
   extends: [
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",

codex-cli/bin/codex.js

@@ -1,17 +1,89 @@
 #!/usr/bin/env node
+// Unified entry point for the Codex CLI.
+/*
+ * Behavior
+ * =========
+ *   1. By default we import the JavaScript implementation located in
+ *      dist/cli.js.
+ *
+ *   2. Developers can opt-in to a pre-compiled Rust binary by setting the
+ *      environment variable CODEX_RUST to a truthy value (`1`, `true`, etc.).
+ *      When that variable is present we resolve the correct binary for the
+ *      current platform / architecture and execute it via child_process.
+ *
+ *      If the CODEX_RUST=1 is specified and there is no native binary for the
+ *      current platform / architecture, an error is thrown.
+ */
 
-// Unified entry point for Codex CLI on all platforms
-// Dynamically loads the compiled ESM bundle in dist/cli.js
+import { spawnSync } from "child_process";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 
-import path from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
+// Determine whether the user explicitly wants the Rust CLI.
+const wantsNative =
+  process.env.CODEX_RUST != null
+    ? ["1", "true", "yes"].includes(process.env.CODEX_RUST.toLowerCase())
+    : false;
+
+// Try native binary if requested.
+if (wantsNative) {
+  const { platform, arch } = process;
+
+  let targetTriple = null;
+  switch (platform) {
+    case "linux":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-unknown-linux-musl";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-unknown-linux-gnu";
+          break;
+        default:
+          break;
+      }
+      break;
+    case "darwin":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-apple-darwin";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-apple-darwin";
+          break;
+        default:
+          break;
+      }
+      break;
+    default:
+      break;
+  }
+
+  if (!targetTriple) {
+    throw new Error(`Unsupported platform: ${platform} (${arch})`);
+  }
+
+  // __dirname equivalent in ESM
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  const binaryPath = path.join(__dirname, "..", "bin", `codex-${targetTriple}`);
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+
+  const exitCode = typeof result.status === "number" ? result.status : 1;
+  process.exit(exitCode);
+}
+
+// Fallback: execute the original JavaScript CLI.
 
 // Determine this script's directory
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Resolve the path to the compiled CLI bundle
-const cliPath = path.resolve(__dirname, '../dist/cli.js');
+const cliPath = path.resolve(__dirname, "../dist/cli.js");
 const cliUrl = pathToFileURL(cliPath).href;
 
 // Load and execute the CLI
@@ -21,7 +93,6 @@ const cliUrl = pathToFileURL(cliPath).href;
   } catch (err) {
     // eslint-disable-next-line no-console
     console.error(err);
-    // eslint-disable-next-line no-undef
     process.exit(1);
   }
 })();

codex-cli/build.mjs

@@ -72,6 +72,9 @@ if (isDevBuild) {
 esbuild
   .build({
     entryPoints: ["src/cli.tsx"],
+    // Do not bundle the contents of package.json at build time: always read it
+    // at runtime.
+    external: ["../package.json"],
     bundle: true,
     format: "esm",
     platform: "node",

codex-cli/default.nix

@@ -0,0 +1,43 @@
+{ pkgs, monorep-deps ? [], ... }:
+let
+  node = pkgs.nodejs_22;
+in
+rec {
+  package = pkgs.buildNpmPackage {
+    pname       = "codex-cli";
+    version     = "0.1.0";
+    src         = ./.;
+    npmDepsHash = "sha256-3tAalmh50I0fhhd7XreM+jvl0n4zcRhqygFNB1Olst8";
+    nodejs      = node;
+    npmInstallFlags = [ "--frozen-lockfile" ];
+    meta = with pkgs.lib; {
+      description = "OpenAI Codex command‑line interface";
+      license     = licenses.asl20;
+      homepage    = "https://github.com/openai/codex";
+    };
+  };
+  devShell = pkgs.mkShell {
+    name        = "codex-cli-dev";
+    buildInputs = monorep-deps ++ [
+      node
+      pkgs.pnpm
+    ];
+    shellHook = ''
+      echo "Entering development shell for codex-cli"
+      # cd codex-cli
+      if [ -f package-lock.json ]; then
+        pnpm ci || echo "npm ci failed"
+      else
+        pnpm install || echo "npm install failed"
+      fi
+      npm run build || echo "npm build failed"
+      export PATH=$PWD/node_modules/.bin:$PATH
+      alias codex="node $PWD/dist/cli.js"
+    '';
+  };
+  app = {
+    type    = "app";
+    program = "${package}/bin/codex";
+  };
+}
+

codex-cli/examples/impossible-pong/task.yaml

@@ -1,7 +1,7 @@
 name: "impossible-pong"
 description: |
   Update index.html with the following features:
-   - Add an overlayed styled popup to start the game on first load
+   - Add an overlaid styled popup to start the game on first load
    - Between each point, show a 3 second countdown (this should be skipped if a player wins)
    - After each game the AI wins, display text at the bottom of the screen with lighthearted insults for the player
    - Add a leaderboard to the right of the court that shows how many games each player has won.

codex-cli/examples/prompt-analyzer/template/prompts.csv

@@ -13,7 +13,7 @@ act,prompt,for_devs
 "Advertiser","I want you to act as an advertiser. You will create a campaign to promote a product or service of your choice. You will choose a target audience, develop key messages and slogans, select the media channels for promotion, and decide on any additional activities needed to reach your goals. My first suggestion request is ""I need help creating an advertising campaign for a new type of energy drink targeting young adults aged 18-30.""",FALSE
 "Storyteller","I want you to act as a storyteller. You will come up with entertaining stories that are engaging, imaginative and captivating for the audience. It can be fairy tales, educational stories or any other type of stories which has the potential to capture people's attention and imagination. Depending on the target audience, you may choose specific themes or topics for your storytelling session e.g., if it's children then you can talk about animals; If it's adults then history-based tales might engage them better etc. My first request is ""I need an interesting story on perseverance.""",FALSE
 "Football Commentator","I want you to act as a football commentator. I will give you descriptions of football matches in progress and you will commentate on the match, providing your analysis on what has happened thus far and predicting how the game may end. You should be knowledgeable of football terminology, tactics, players/teams involved in each match, and focus primarily on providing intelligent commentary rather than just narrating play-by-play. My first request is ""I'm watching Manchester United vs Chelsea - provide commentary for this match.""",FALSE
-"Stand-up Comedian","I want you to act as a stand-up comedian. I will provide you with some topics related to current events and you will use your wit, creativity, and observational skills to create a routine based on those topics. You should also be sure to incorporate personal anecdotes or experiences into the routine in order to make it more relatable and engaging for the audience. My first request is ""I want an humorous take on politics.""",FALSE
+"Stand-up Comedian","I want you to act as a stand-up comedian. I will provide you with some topics related to current events and you will use your with, creativity, and observational skills to create a routine based on those topics. You should also be sure to incorporate personal anecdotes or experiences into the routine in order to make it more relatable and engaging for the audience. My first request is ""I want an humorous take on politics.""",FALSE
 "Motivational Coach","I want you to act as a motivational coach. I will provide you with some information about someone's goals and challenges, and it will be your job to come up with strategies that can help this person achieve their goals. This could involve providing positive affirmations, giving helpful advice or suggesting activities they can do to reach their end goal. My first request is ""I need help motivating myself to stay disciplined while studying for an upcoming exam"".",FALSE
 "Composer","I want you to act as a composer. I will provide the lyrics to a song and you will create music for it. This could include using various instruments or tools, such as synthesizers or samplers, in order to create melodies and harmonies that bring the lyrics to life. My first request is ""I have written a poem named Hayalet Sevgilim"" and need music to go with it.""""""",FALSE
 "Debater","I want you to act as a debater. I will provide you with some topics related to current events and your task is to research both sides of the debates, present valid arguments for each side, refute opposing points of view, and draw persuasive conclusions based on evidence. Your goal is to help people come away from the discussion with increased knowledge and insight into the topic at hand. My first request is ""I want an opinion piece about Deno.""",FALSE
@@ -23,7 +23,7 @@ act,prompt,for_devs
 "Movie Critic","I want you to act as a movie critic. You will develop an engaging and creative movie review. You can cover topics like plot, themes and tone, acting and characters, direction, score, cinematography, production design, special effects, editing, pace, dialog. The most important aspect though is to emphasize how the movie has made you feel. What has really resonated with you. You can also be critical about the movie. Please avoid spoilers. My first request is ""I need to write a movie review for the movie Interstellar""",FALSE
 "Relationship Coach","I want you to act as a relationship coach. I will provide some details about the two people involved in a conflict, and it will be your job to come up with suggestions on how they can work through the issues that are separating them. This could include advice on communication techniques or different strategies for improving their understanding of one another's perspectives. My first request is ""I need help solving conflicts between my spouse and myself.""",FALSE
 "Poet","I want you to act as a poet. You will create poems that evoke emotions and have the power to stir people's soul. Write on any topic or theme but make sure your words convey the feeling you are trying to express in beautiful yet meaningful ways. You can also come up with short verses that are still powerful enough to leave an imprint in readers' minds. My first request is ""I need a poem about love.""",FALSE
-"Rapper","I want you to act as a rapper. You will come up with powerful and meaningful lyrics, beats and rhythm that can 'wow' the audience. Your lyrics should have an intriguing meaning and message which people can relate too. When it comes to choosing your beat, make sure it is catchy yet relevant to your words, so that when combined they make an explosion of sound everytime! My first request is ""I need a rap song about finding strength within yourself.""",FALSE
+"Rapper","I want you to act as a rapper. You will come up with powerful and meaningful lyrics, beats and rhythm that can 'wow' the audience. Your lyrics should have an intriguing meaning and message which people can relate too. When it comes to choosing your beat, make sure it is catchy yet relevant to your words, so that when combined they make an explosion of sound every time! My first request is ""I need a rap song about finding strength within yourself.""",FALSE
 "Motivational Speaker","I want you to act as a motivational speaker. Put together words that inspire action and make people feel empowered to do something beyond their abilities. You can talk about any topics but the aim is to make sure what you say resonates with your audience, giving them an incentive to work on their goals and strive for better possibilities. My first request is ""I need a speech about how everyone should never give up.""",FALSE
 "Philosophy Teacher","I want you to act as a philosophy teacher. I will provide some topics related to the study of philosophy, and it will be your job to explain these concepts in an easy-to-understand manner. This could include providing examples, posing questions or breaking down complex ideas into smaller pieces that are easier to comprehend. My first request is ""I need help understanding how different philosophical theories can be applied in everyday life.""",FALSE
 "Philosopher","I want you to act as a philosopher. I will provide some topics or questions related to the study of philosophy, and it will be your job to explore these concepts in depth. This could involve conducting research into various philosophical theories, proposing new ideas or finding creative solutions for solving complex problems. My first request is ""I need help developing an ethical framework for decision making.""",FALSE

codex-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openai/codex",
-  "version": "0.1.2504301751",
+  "version": "0.0.0-dev",
   "license": "Apache-2.0",
   "bin": {
     "codex": "bin/codex.js"
@@ -23,6 +23,7 @@
     "stage-release": "./scripts/stage_release.sh"
   },
   "files": [
+    "bin",
     "dist"
   ],
   "dependencies": {
@@ -30,6 +31,7 @@
     "chalk": "^5.2.0",
     "diff": "^7.0.0",
     "dotenv": "^16.1.4",
+    "express": "^5.1.0",
     "fast-deep-equal": "^3.1.3",
     "fast-npm-meta": "^0.4.2",
     "figures": "^6.1.0",
@@ -53,6 +55,7 @@
   "devDependencies": {
     "@eslint/js": "^9.22.0",
     "@types/diff": "^7.0.2",
+    "@types/express": "^5.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/marked-terminal": "^6.1.1",
     "@types/react": "^18.0.32",

codex-cli/scripts/install_native_deps.sh

@@ -1,20 +1,44 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-# Copy the Linux sandbox native binaries into the bin/ subfolder of codex-cli/.
+# Install native runtime dependencies for codex-cli.
 #
-# Usage:
-#   ./scripts/install_native_deps.sh [CODEX_CLI_ROOT]
+# By default the script copies the sandbox binaries that are required at
+# runtime. When called with the --full-native flag, it additionally
+# bundles pre-built Rust CLI binaries so that the resulting npm package can run
+# the native implementation when users set CODEX_RUST=1.
 #
-# Arguments
-#   [CODEX_CLI_ROOT] – Optional.  If supplied, it should be the codex-cli
-#                      folder that contains the package.json for @openai/codex.
+# Usage
+#   install_native_deps.sh [RELEASE_ROOT] [--full-native]
 #
-# When no argument is given we assume the script is being run directly from a
-# development checkout. In that case we install the binaries into the
-# repository’s own `bin/` directory so that the CLI can run locally.
+# The optional RELEASE_ROOT is the path that contains package.json.  Omitting
+# it installs the binaries into the repository's own bin/ folder to support
+# local development.
 
 set -euo pipefail
 
+# ------------------
+# Parse arguments
+# ------------------
+
+DEST_DIR=""
+INCLUDE_RUST=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --full-native)
+      INCLUDE_RUST=1
+      ;;
+    *)
+      if [[ -z "$DEST_DIR" ]]; then
+        DEST_DIR="$arg"
+      else
+        echo "Unexpected argument: $arg" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
 # ----------------------------------------------------------------------------
 # Determine where the binaries should be installed.
 # ----------------------------------------------------------------------------
@@ -41,7 +65,7 @@ mkdir -p "$BIN_DIR"
 # Until we start publishing stable GitHub releases, we have to grab the binaries
 # from the GitHub Action that created them. Update the URL below to point to the
 # appropriate workflow run:
-WORKFLOW_URL="https://github.com/openai/codex/actions/runs/14763725716"
+WORKFLOW_URL="https://github.com/openai/codex/actions/runs/15087655786"
 WORKFLOW_ID="${WORKFLOW_URL##*/}"
 
 ARTIFACTS_DIR="$(mktemp -d)"
@@ -50,12 +74,26 @@ trap 'rm -rf "$ARTIFACTS_DIR"' EXIT
 # NB: The GitHub CLI `gh` must be installed and authenticated.
 gh run download --dir "$ARTIFACTS_DIR" --repo openai/codex "$WORKFLOW_ID"
 
-# Decompress the two target architectures.
+# Decompress the artifacts for Linux sandboxing.
 zstd -d "$ARTIFACTS_DIR/x86_64-unknown-linux-musl/codex-linux-sandbox-x86_64-unknown-linux-musl.zst" \
      -o "$BIN_DIR/codex-linux-sandbox-x64"
 
 zstd -d "$ARTIFACTS_DIR/aarch64-unknown-linux-gnu/codex-linux-sandbox-aarch64-unknown-linux-gnu.zst" \
      -o "$BIN_DIR/codex-linux-sandbox-arm64"
 
-echo "Installed native dependencies into $BIN_DIR"
+if [[ "$INCLUDE_RUST" -eq 1 ]]; then
+  # x64 Linux
+  zstd -d "$ARTIFACTS_DIR/x86_64-unknown-linux-musl/codex-x86_64-unknown-linux-musl.zst" \
+      -o "$BIN_DIR/codex-x86_64-unknown-linux-musl"
+  # ARM64 Linux
+  zstd -d "$ARTIFACTS_DIR/aarch64-unknown-linux-gnu/codex-aarch64-unknown-linux-gnu.zst" \
+      -o "$BIN_DIR/codex-aarch64-unknown-linux-gnu"
+  # x64 macOS
+  zstd -d "$ARTIFACTS_DIR/x86_64-apple-darwin/codex-x86_64-apple-darwin.zst" \
+      -o "$BIN_DIR/codex-x86_64-apple-darwin"
+  # ARM64 macOS
+  zstd -d "$ARTIFACTS_DIR/aarch64-apple-darwin/codex-aarch64-apple-darwin.zst" \
+      -o "$BIN_DIR/codex-aarch64-apple-darwin"
+fi
 
+echo "Installed native dependencies into $BIN_DIR"

codex-cli/scripts/stage_release.sh

@@ -1,28 +1,145 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# stage_release.sh
+# -----------------------------------------------------------------------------
+# Stages an npm release for @openai/codex.
+#
+# The script used to accept a single optional positional argument that indicated
+# the temporary directory in which to stage the package.  We now support a
+# flag-based interface so that we can extend the command with further options
+# without breaking the call-site contract.
+#
+#   --tmp <dir>  : Use <dir> instead of a freshly created temp directory.
+#   --native     : Bundle the pre-built Rust CLI binaries for Linux alongside
+#                  the JavaScript implementation (a so-called "fat" package).
+#   -h|--help    : Print usage.
+#
+# When --native is supplied we copy the linux-sandbox binaries (as before) and
+# additionally fetch / unpack the two Rust targets that we currently support:
+#   - x86_64-unknown-linux-musl
+#   - aarch64-unknown-linux-gnu
+#
+# NOTE: This script is intended to be run from the repository root via
+#       `pnpm --filter codex-cli stage-release ...` or inside codex-cli with the
+#       helper script entry in package.json (`pnpm stage-release ...`).
+# -----------------------------------------------------------------------------
 
 set -euo pipefail
 
-# Change to the codex-cli directory.
-cd "$(dirname "${BASH_SOURCE[0]}")/.."
+# Helper - usage / flag parsing
 
-# First argument is where to stage the release. Creates a temporary directory
-# if not provided.
-RELEASE_DIR="${1:-$(mktemp -d)}"
-[ -n "${1-}" ] && shift
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [--tmp DIR] [--native]
+
+Options
+  --tmp DIR   Use DIR to stage the release (defaults to a fresh mktemp dir)
+  --native    Bundle Rust binaries for Linux (fat package)
+  -h, --help  Show this help
+
+Legacy positional argument: the first non-flag argument is still interpreted
+as the temporary directory (for backwards compatibility) but is deprecated.
+EOF
+  exit "${1:-0}"
+}
+
+TMPDIR=""
+INCLUDE_NATIVE=0
+
+# Manual flag parser - Bash getopts does not handle GNU long options well.
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --tmp)
+      shift || { echo "--tmp requires an argument"; usage 1; }
+      TMPDIR="$1"
+      ;;
+    --tmp=*)
+      TMPDIR="${1#*=}"
+      ;;
+    --native)
+      INCLUDE_NATIVE=1
+      ;;
+    -h|--help)
+      usage 0
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage 1
+      ;;
+    *)
+      echo "Unexpected extra argument: $1" >&2
+      usage 1
+      ;;
+  esac
+  shift
+done
+
+# Fallback when the caller did not specify a directory.
+# If no directory was specified create a fresh temporary one.
+if [[ -z "$TMPDIR" ]]; then
+  TMPDIR="$(mktemp -d)"
+fi
+
+# Ensure the directory exists, then resolve to an absolute path.
+mkdir -p "$TMPDIR"
+TMPDIR="$(cd "$TMPDIR" && pwd)"
+
+# Main build logic
+
+echo "Staging release in $TMPDIR"
+
+# The script lives in codex-cli/scripts/ - change into codex-cli root so that
+# relative paths keep working.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CODEX_CLI_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+pushd "$CODEX_CLI_ROOT" >/dev/null
+
+# 1. Build the JS artifacts ---------------------------------------------------
 
-# Compile the JavaScript.
 pnpm install
 pnpm build
-mkdir "$RELEASE_DIR/bin"
-cp -r bin/codex.js "$RELEASE_DIR/bin/codex.js"
-cp -r dist "$RELEASE_DIR/dist"
-cp -r src "$RELEASE_DIR/src" # important if we want sourcemaps to continue to work
-cp ../README.md "$RELEASE_DIR"
-# TODO: Derive version from Git tag.
-VERSION=$(printf '0.1.%d' "$(date +%y%m%d%H%M)")
-jq --arg version "$VERSION" '.version = $version' package.json > "$RELEASE_DIR/package.json"
 
-# Copy the native dependencies.
-./scripts/install_native_deps.sh "$RELEASE_DIR"
+# Paths inside the staged package
+mkdir -p "$TMPDIR/bin"
 
-echo "Staged version $VERSION for release in $RELEASE_DIR"
+cp -r bin/codex.js "$TMPDIR/bin/codex.js"
+cp -r dist "$TMPDIR/dist"
+cp -r src "$TMPDIR/src" # keep source for TS sourcemaps
+cp ../README.md "$TMPDIR" || true # README is one level up - ignore if missing
+
+# Derive a timestamp-based version (keep same scheme as before)
+VERSION="$(printf '0.1.%d' "$(date +%y%m%d%H%M)")"
+
+# Modify package.json - bump version and optionally add the native directory to
+# the files array so that the binaries are published to npm.
+
+jq --arg version "$VERSION" \
+    '.version = $version' \
+    package.json > "$TMPDIR/package.json"
+
+# 2. Native runtime deps (sandbox plus optional Rust binaries)
+
+if [[ "$INCLUDE_NATIVE" -eq 1 ]]; then
+  ./scripts/install_native_deps.sh "$TMPDIR" --full-native
+else
+  ./scripts/install_native_deps.sh "$TMPDIR"
+fi
+
+popd >/dev/null
+
+echo "Staged version $VERSION for release in $TMPDIR"
+
+echo "Test Node:"
+echo "    node ${TMPDIR}/bin/codex.js --help"
+if [[ "$INCLUDE_NATIVE" -eq 1 ]]; then
+  echo "Test Rust:"
+  echo "    CODEX_RUST=1 node ${TMPDIR}/bin/codex.js --help"
+fi
+
+# Print final hint for convenience
+if [[ "$INCLUDE_NATIVE" -eq 1 ]]; then
+  echo "Next:  cd \"$TMPDIR\" && npm publish --tag native"
+else
+  echo "Next:  cd \"$TMPDIR\" && npm publish"
+fi

codex-cli/src/app.tsx

@@ -1,12 +1,13 @@
 import type { ApprovalPolicy } from "./approvals";
 import type { AppConfig } from "./utils/config";
+import type { TerminalChatSession } from "./utils/session.js";
 import type { ResponseItem } from "openai/resources/responses/responses";
 
 import TerminalChat from "./components/chat/terminal-chat";
 import TerminalChatPastRollout from "./components/chat/terminal-chat-past-rollout";
 import { checkInGit } from "./utils/check-in-git";
-import { CLI_VERSION, type TerminalChatSession } from "./utils/session.js";
 import { onExit } from "./utils/terminal";
+import { CLI_VERSION } from "./version";
 import { ConfirmInput } from "@inkjs/ui";
 import { Box, Text, useApp, useStdin } from "ink";
 import React, { useMemo, useState } from "react";
@@ -49,6 +50,7 @@ export default function App({
       <TerminalChatPastRollout
         session={rollout.session}
         items={rollout.items}
+        fileOpener={config.fileOpener}
       />
     );
   }

codex-cli/src/approvals.ts

@@ -281,12 +281,14 @@ export function resolvePathAgainstWorkdir(
   candidatePath: string,
   workdir: string | undefined,
 ): string {
-  if (path.isAbsolute(candidatePath)) {
-    return candidatePath;
+  // Normalize candidatePath to prevent path traversal attacks
+  const normalizedCandidatePath = path.normalize(candidatePath);
+  if (path.isAbsolute(normalizedCandidatePath)) {
+    return normalizedCandidatePath;
   } else if (workdir != null) {
-    return path.resolve(workdir, candidatePath);
+    return path.resolve(workdir, normalizedCandidatePath);
   } else {
-    return path.resolve(candidatePath);
+    return path.resolve(normalizedCandidatePath);
   }
 }
 
@@ -363,6 +365,11 @@ export function isSafeCommand(
         reason: "View file contents",
         group: "Reading files",
       };
+    case "nl":
+      return {
+        reason: "View file with line numbers",
+        group: "Reading files",
+      };
     case "rg":
       return {
         reason: "Ripgrep search",
@@ -446,11 +453,15 @@ export function isSafeCommand(
       }
       break;
     case "sed":
+      // We allow two types of sed invocations:
+      // 1. `sed -n 1,200p FILE`
+      // 2. `sed -n 1,200p` because the file is passed via stdin, e.g.,
+      //    `nl -ba README.md | sed -n '1,200p'`
       if (
         cmd1 === "-n" &&
         isValidSedNArg(cmd2) &&
-        typeof cmd3 === "string" &&
-        command.length === 4
+        (command.length === 3 ||
+          (typeof cmd3 === "string" && command.length === 4))
       ) {
         return {
           reason: "Sed print subset",

codex-cli/src/cli.tsx

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 import "dotenv/config";
 
+// Exit early if on an older version of Node.js (< 22)
+const major = process.versions.node.split(".").map(Number)[0]!;
+if (major < 22) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "\n" +
+      "Codex CLI requires Node.js version 22 or newer.\n" +
+      `You are running Node.js v${process.versions.node}.\n` +
+      "Please upgrade Node.js: https://nodejs.org/en/download/\n",
+  );
+  process.exit(1);
+}
+
 // Hack to suppress deprecation warnings (punycode)
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (process as any).noDeprecation = true;
@@ -14,16 +27,20 @@ import type { ReasoningEffort } from "openai/resources.mjs";
 
 import App from "./app";
 import { runSinglePass } from "./cli-singlepass";
+import SessionsOverlay from "./components/sessions-overlay.js";
 import { AgentLoop } from "./utils/agent/agent-loop";
 import { ReviewDecision } from "./utils/agent/review";
 import { AutoApprovalMode } from "./utils/auto-approval-mode";
 import { checkForUpdates } from "./utils/check-updates";
 import {
-  getApiKey,
   loadConfig,
   PRETTY_PRINT,
   INSTRUCTIONS_FILEPATH,
 } from "./utils/config";
+import {
+  getApiKey as fetchApiKey,
+  maybeRedeemCredits,
+} from "./utils/get-api-key";
 import { createInputItem } from "./utils/input-utils";
 import { initLogger } from "./utils/logger/log";
 import { isModelSupportedForResponses } from "./utils/model-utils.js";
@@ -34,6 +51,7 @@ import { spawnSync } from "child_process";
 import fs from "fs";
 import { render } from "ink";
 import meow from "meow";
+import os from "os";
 import path from "path";
 import React from "react";
 
@@ -56,10 +74,13 @@ const cli = meow(
     --version                       Print version and exit
 
     -h, --help                      Show usage and exit
-    -m, --model <model>             Model to use for completions (default: o4-mini)
+    -m, --model <model>             Model to use for completions (default: codex-mini-latest)
     -p, --provider <provider>       Provider to use for completions (default: openai)
     -i, --image <path>              Path(s) to image files to include as input
     -v, --view <rollout>            Inspect a previously saved rollout instead of starting a session
+    --history                       Browse previous sessions
+    --login                         Start a new sign in flow
+    --free                          Retry redeeming free credits
     -q, --quiet                     Non-interactive mode that only prints the assistant's final output
     -c, --config                    Open the instructions file in your editor
     -w, --writable-root <path>      Writable folder for sandbox in full-auto mode (can be specified multiple times)
@@ -68,7 +89,7 @@ const cli = meow(
     --auto-edit                Automatically approve file edits; still prompt for commands
     --full-auto                Automatically approve edits and commands when executed in the sandbox
 
-    --no-project-doc           Do not automatically include the repository's 'codex.md'
+    --no-project-doc           Do not automatically include the repository's 'AGENTS.md'
     --project-doc <file>       Include an additional markdown file at <file> as context
     --full-stdout              Do not truncate stdout/stderr from command outputs
     --notify                   Enable desktop notifications for responses
@@ -79,6 +100,8 @@ const cli = meow(
     --flex-mode               Use "flex-mode" processing mode for the request (only supported
                               with models o3 and o4-mini)
 
+    --reasoning <effort>      Set the reasoning effort level (low, medium, high) (default: high)
+
   Dangerous options
     --dangerously-auto-approve-everything
                                Skip all confirmation prompts and execute commands without
@@ -102,6 +125,9 @@ const cli = meow(
       help: { type: "boolean", aliases: ["h"] },
       version: { type: "boolean", description: "Print version and exit" },
       view: { type: "string" },
+      history: { type: "boolean", description: "Browse previous sessions" },
+      login: { type: "boolean", description: "Force a new sign in flow" },
+      free: { type: "boolean", description: "Retry redeeming free credits" },
       model: { type: "string", aliases: ["m"] },
       provider: { type: "string", aliases: ["p"] },
       image: { type: "string", isMultiple: true, aliases: ["i"] },
@@ -144,7 +170,7 @@ const cli = meow(
       },
       noProjectDoc: {
         type: "boolean",
-        description: "Disable automatic inclusion of project-level codex.md",
+        description: "Disable automatic inclusion of project-level AGENTS.md",
       },
       projectDoc: {
         type: "string",
@@ -259,11 +285,82 @@ let config = loadConfig(undefined, undefined, {
   isFullContext: fullContextMode,
 });
 
-const prompt = cli.input[0];
+// `prompt` can be updated later when the user resumes a previous session
+// via the `--history` flag. Therefore it must be declared with `let` rather
+// than `const`.
+let prompt = cli.input[0];
 const model = cli.flags.model ?? config.model;
 const imagePaths = cli.flags.image;
 const provider = cli.flags.provider ?? config.provider ?? "openai";
-const apiKey = getApiKey(provider);
+
+const client = {
+  issuer: "https://auth.openai.com",
+  client_id: "app_EMoamEEZ73f0CkXaXp7hrann",
+};
+
+let apiKey = "";
+let savedTokens:
+  | {
+      id_token?: string;
+      access_token?: string;
+      refresh_token: string;
+    }
+  | undefined;
+
+// Try to load existing auth file if present
+try {
+  const home = os.homedir();
+  const authDir = path.join(home, ".codex");
+  const authFile = path.join(authDir, "auth.json");
+  if (fs.existsSync(authFile)) {
+    const data = JSON.parse(fs.readFileSync(authFile, "utf-8"));
+    savedTokens = data.tokens;
+    const lastRefreshTime = data.last_refresh
+      ? new Date(data.last_refresh).getTime()
+      : 0;
+    const expired = Date.now() - lastRefreshTime > 28 * 24 * 60 * 60 * 1000;
+    if (data.OPENAI_API_KEY && !expired) {
+      apiKey = data.OPENAI_API_KEY;
+    }
+  }
+} catch {
+  // ignore errors
+}
+
+if (cli.flags.login) {
+  apiKey = await fetchApiKey(client.issuer, client.client_id);
+  try {
+    const home = os.homedir();
+    const authDir = path.join(home, ".codex");
+    const authFile = path.join(authDir, "auth.json");
+    if (fs.existsSync(authFile)) {
+      const data = JSON.parse(fs.readFileSync(authFile, "utf-8"));
+      savedTokens = data.tokens;
+    }
+  } catch {
+    /* ignore */
+  }
+} else if (!apiKey) {
+  apiKey = await fetchApiKey(client.issuer, client.client_id);
+}
+// Ensure the API key is available as an environment variable for legacy code
+process.env["OPENAI_API_KEY"] = apiKey;
+
+if (cli.flags.free) {
+  // eslint-disable-next-line no-console
+  console.log(`${chalk.bold("codex --free")} attempting to redeem credits...`);
+  if (!savedTokens?.refresh_token) {
+    apiKey = await fetchApiKey(client.issuer, client.client_id, true);
+    // fetchApiKey includes credit redemption as the end of the flow
+  } else {
+    await maybeRedeemCredits(
+      client.issuer,
+      client.client_id,
+      savedTokens.refresh_token,
+      savedTokens.id_token,
+    );
+  }
+}
 
 // Set of providers that don't require API keys
 const NO_API_KEY_REQUIRED = new Set(["ollama"]);
@@ -306,8 +403,8 @@ config = {
   model: model ?? config.model,
   notify: Boolean(cli.flags.notify),
   reasoningEffort:
-    (cli.flags.reasoning as ReasoningEffort | undefined) ?? "high",
-  flexMode: Boolean(cli.flags.flexMode),
+    (cli.flags.reasoning as ReasoningEffort | undefined) ?? "medium",
+  flexMode: cli.flags.flexMode || (config.flexMode ?? false),
   provider,
   disableResponseStorage,
 };
@@ -321,15 +418,19 @@ try {
 }
 
 // For --flex-mode, validate and exit if incorrect.
-if (cli.flags.flexMode) {
+if (config.flexMode) {
   const allowedFlexModels = new Set(["o3", "o4-mini"]);
   if (!allowedFlexModels.has(config.model)) {
-    // eslint-disable-next-line no-console
-    console.error(
-      `The --flex-mode option is only supported when using the 'o3' or 'o4-mini' models. ` +
-        `Current model: '${config.model}'.`,
-    );
-    process.exit(1);
+    if (cli.flags.flexMode) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `The --flex-mode option is only supported when using the 'o3' or 'o4-mini' models. ` +
+          `Current model: '${config.model}'.`,
+      );
+      process.exit(1);
+    } else {
+      config.flexMode = false;
+    }
   }
 }
 
@@ -349,6 +450,46 @@ if (
 
 let rollout: AppRollout | undefined;
 
+// For --history, show session selector and optionally update prompt or rollout.
+if (cli.flags.history) {
+  const result: { path: string; mode: "view" | "resume" } | null =
+    await new Promise((resolve) => {
+      const instance = render(
+        React.createElement(SessionsOverlay, {
+          onView: (p: string) => {
+            instance.unmount();
+            resolve({ path: p, mode: "view" });
+          },
+          onResume: (p: string) => {
+            instance.unmount();
+            resolve({ path: p, mode: "resume" });
+          },
+          onExit: () => {
+            instance.unmount();
+            resolve(null);
+          },
+        }),
+      );
+    });
+
+  if (!result) {
+    process.exit(0);
+  }
+
+  if (result.mode === "view") {
+    try {
+      const content = fs.readFileSync(result.path, "utf-8");
+      rollout = JSON.parse(content) as AppRollout;
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error("Error reading session file:", error);
+      process.exit(1);
+    }
+  } else {
+    prompt = `Resume this session: ${result.path}`;
+  }
+}
+
 // For --view, optionally load an existing rollout from disk, display it and exit.
 if (cli.flags.view) {
   const viewPath = cli.flags.view;

codex-cli/src/components/chat/message-history.tsx

@@ -1,6 +1,7 @@
 import type { TerminalHeaderProps } from "./terminal-header.js";
 import type { GroupedResponseItem } from "./use-message-grouping.js";
 import type { ResponseItem } from "openai/resources/responses/responses.mjs";
+import type { FileOpenerScheme } from "src/utils/config.js";
 
 import TerminalChatResponseItem from "./terminal-chat-response-item.js";
 import TerminalHeader from "./terminal-header.js";
@@ -19,11 +20,13 @@ type MessageHistoryProps = {
   confirmationPrompt: React.ReactNode;
   loading: boolean;
   headerProps: TerminalHeaderProps;
+  fileOpener: FileOpenerScheme | undefined;
 };
 
 const MessageHistory: React.FC<MessageHistoryProps> = ({
   batch,
   headerProps,
+  fileOpener,
 }) => {
   const messages = batch.map(({ item }) => item!);
 
@@ -68,7 +71,10 @@ const MessageHistory: React.FC<MessageHistoryProps> = ({
                 message.type === "message" && message.role === "user" ? 0 : 1
               }
             >
-              <TerminalChatResponseItem item={message} />
+              <TerminalChatResponseItem
+                item={message}
+                fileOpener={fileOpener}
+              />
             </Box>
           );
         }}

codex-cli/src/components/chat/terminal-chat-input.tsx

@@ -54,6 +54,7 @@ export default function TerminalChatInput({
   openApprovalOverlay,
   openHelpOverlay,
   openDiffOverlay,
+  openSessionsOverlay,
   onCompact,
   interruptAgent,
   active,
@@ -77,6 +78,7 @@ export default function TerminalChatInput({
   openApprovalOverlay: () => void;
   openHelpOverlay: () => void;
   openDiffOverlay: () => void;
+  openSessionsOverlay: () => void;
   onCompact: () => void;
   interruptAgent: () => void;
   active: boolean;
@@ -280,6 +282,9 @@ export default function TerminalChatInput({
                 case "/history":
                   openOverlay();
                   break;
+                case "/sessions":
+                  openSessionsOverlay();
+                  break;
                 case "/help":
                   openHelpOverlay();
                   break;
@@ -484,6 +489,10 @@ export default function TerminalChatInput({
         setInput("");
         openOverlay();
         return;
+      } else if (inputValue === "/sessions") {
+        setInput("");
+        openSessionsOverlay();
+        return;
       } else if (inputValue === "/help") {
         setInput("");
         openHelpOverlay();
@@ -584,7 +593,7 @@ export default function TerminalChatInput({
 
         try {
           const os = await import("node:os");
-          const { CLI_VERSION } = await import("../../utils/session.js");
+          const { CLI_VERSION } = await import("../../version.js");
           const { buildBugReportUrl } = await import(
             "../../utils/bug-report.js"
           );
@@ -728,6 +737,7 @@ export default function TerminalChatInput({
       openModelOverlay,
       openHelpOverlay,
       openDiffOverlay,
+      openSessionsOverlay,
       history,
       onCompact,
       skipNextSubmit,

codex-cli/src/components/chat/terminal-chat-past-rollout.tsx

@@ -1,5 +1,6 @@
 import type { TerminalChatSession } from "../../utils/session.js";
 import type { ResponseItem } from "openai/resources/responses/responses";
+import type { FileOpenerScheme } from "src/utils/config.js";
 
 import TerminalChatResponseItem from "./terminal-chat-response-item";
 import { Box, Text } from "ink";
@@ -8,9 +9,11 @@ import React from "react";
 export default function TerminalChatPastRollout({
   session,
   items,
+  fileOpener,
 }: {
   session: TerminalChatSession;
   items: Array<ResponseItem>;
+  fileOpener: FileOpenerScheme | undefined;
 }): React.ReactElement {
   const { version, id: sessionId, model } = session;
   return (
@@ -51,9 +54,13 @@ export default function TerminalChatPastRollout({
         {React.useMemo(
           () =>
             items.map((item, key) => (
-              <TerminalChatResponseItem key={key} item={item} />
+              <TerminalChatResponseItem
+                key={key}
+                item={item}
+                fileOpener={fileOpener}
+              />
             )),
-          [items],
+          [items, fileOpener],
         )}
       </Box>
     </Box>

codex-cli/src/components/chat/terminal-chat-response-item.tsx

@@ -8,6 +8,7 @@ import type {
   ResponseOutputMessage,
   ResponseReasoningItem,
 } from "openai/resources/responses/responses";
+import type { FileOpenerScheme } from "src/utils/config";
 
 import { useTerminalSize } from "../../hooks/use-terminal-size";
 import { collapseXmlBlocks } from "../../utils/file-tag-utils";
@@ -16,16 +17,21 @@ import chalk, { type ForegroundColorName } from "chalk";
 import { Box, Text } from "ink";
 import { parse, setOptions } from "marked";
 import TerminalRenderer from "marked-terminal";
+import path from "path";
 import React, { useEffect, useMemo } from "react";
+import { formatCommandForDisplay } from "src/format-command.js";
+import supportsHyperlinks from "supports-hyperlinks";
 
 export default function TerminalChatResponseItem({
   item,
   fullStdout = false,
   setOverlayMode,
+  fileOpener,
 }: {
   item: ResponseItem;
   fullStdout?: boolean;
   setOverlayMode?: React.Dispatch<React.SetStateAction<OverlayModeType>>;
+  fileOpener: FileOpenerScheme | undefined;
 }): React.ReactElement {
   switch (item.type) {
     case "message":
@@ -33,10 +39,15 @@ export default function TerminalChatResponseItem({
         <TerminalChatResponseMessage
           setOverlayMode={setOverlayMode}
           message={item}
+          fileOpener={fileOpener}
         />
       );
+    // @ts-expect-error new item types aren't in SDK yet
+    case "local_shell_call":
     case "function_call":
       return <TerminalChatResponseToolCall message={item} />;
+    // @ts-expect-error new item types aren't in SDK yet
+    case "local_shell_call_output":
     case "function_call_output":
       return (
         <TerminalChatResponseToolCallOutput
@@ -50,7 +61,9 @@ export default function TerminalChatResponseItem({
 
   // @ts-expect-error `reasoning` is not in the responses API yet
   if (item.type === "reasoning") {
-    return <TerminalChatResponseReasoning message={item} />;
+    return (
+      <TerminalChatResponseReasoning message={item} fileOpener={fileOpener} />
+    );
   }
 
   return <TerminalChatResponseGenericMessage message={item} />;
@@ -78,8 +91,10 @@ export default function TerminalChatResponseItem({
 
 export function TerminalChatResponseReasoning({
   message,
+  fileOpener,
 }: {
   message: ResponseReasoningItem & { duration_ms?: number };
+  fileOpener: FileOpenerScheme | undefined;
 }): React.ReactElement | null {
   // Only render when there is a reasoning summary
   if (!message.summary || message.summary.length === 0) {
@@ -92,7 +107,7 @@ export function TerminalChatResponseReasoning({
         return (
           <Box key={key} flexDirection="column">
             {s.headline && <Text bold>{s.headline}</Text>}
-            <Markdown>{s.text}</Markdown>
+            <Markdown fileOpener={fileOpener}>{s.text}</Markdown>
           </Box>
         );
       })}
@@ -108,9 +123,11 @@ const colorsByRole: Record<string, ForegroundColorName> = {
 function TerminalChatResponseMessage({
   message,
   setOverlayMode,
+  fileOpener,
 }: {
   message: ResponseInputMessageItem | ResponseOutputMessage;
   setOverlayMode?: React.Dispatch<React.SetStateAction<OverlayModeType>>;
+  fileOpener: FileOpenerScheme | undefined;
 }) {
   // auto switch to model mode if the system message contains "has been deprecated"
   useEffect(() => {
@@ -129,7 +146,7 @@ function TerminalChatResponseMessage({
       <Text bold color={colorsByRole[message.role] || "gray"}>
         {message.role === "assistant" ? "codex" : message.role}
       </Text>
-      <Markdown>
+      <Markdown fileOpener={fileOpener}>
         {message.content
           .map(
             (c) =>
@@ -154,16 +171,28 @@ function TerminalChatResponseMessage({
 function TerminalChatResponseToolCall({
   message,
 }: {
-  message: ResponseFunctionToolCallItem;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  message: ResponseFunctionToolCallItem | any;
 }) {
-  const details = parseToolCall(message);
+  let workdir: string | undefined;
+  let cmdReadableText: string | undefined;
+  if (message.type === "function_call") {
+    const details = parseToolCall(message);
+    workdir = details?.workdir;
+    cmdReadableText = details?.cmdReadableText;
+  } else if (message.type === "local_shell_call") {
+    const action = message.action;
+    workdir = action.working_directory;
+    cmdReadableText = formatCommandForDisplay(action.command);
+  }
   return (
     <Box flexDirection="column" gap={1}>
       <Text color="magentaBright" bold>
         command
+        {workdir ? <Text dimColor>{` (${workdir})`}</Text> : ""}
       </Text>
       <Text>
-        <Text dimColor>$</Text> {details?.cmdReadableText}
+        <Text dimColor>$</Text> {cmdReadableText}
       </Text>
     </Box>
   );
@@ -173,7 +202,8 @@ function TerminalChatResponseToolCallOutput({
   message,
   fullStdout,
 }: {
-  message: ResponseFunctionToolCallOutputItem;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  message: ResponseFunctionToolCallOutputItem | any;
   fullStdout: boolean;
 }) {
   const { output, metadata } = parseToolCallOutput(message.output);
@@ -240,26 +270,91 @@ export function TerminalChatResponseGenericMessage({
 
 export type MarkdownProps = TerminalRendererOptions & {
   children: string;
+  fileOpener: FileOpenerScheme | undefined;
+  /** Base path for resolving relative file citation paths. */
+  cwd?: string;
 };
 
 export function Markdown({
   children,
+  fileOpener,
+  cwd,
   ...options
 }: MarkdownProps): React.ReactElement {
   const size = useTerminalSize();
 
   const rendered = React.useMemo(() => {
+    const linkifiedMarkdown = rewriteFileCitations(children, fileOpener, cwd);
+
     // Configure marked for this specific render
     setOptions({
       // @ts-expect-error missing parser, space props
       renderer: new TerminalRenderer({ ...options, width: size.columns }),
     });
-    const parsed = parse(children, { async: false }).trim();
+    const parsed = parse(linkifiedMarkdown, { async: false }).trim();
 
     // Remove the truncation logic
     return parsed;
     // eslint-disable-next-line react-hooks/exhaustive-deps -- options is an object of primitives
-  }, [children, size.columns, size.rows]);
+  }, [
+    children,
+    size.columns,
+    size.rows,
+    fileOpener,
+    supportsHyperlinks.stdout,
+    chalk.level,
+  ]);
 
   return <Text>{rendered}</Text>;
 }
+
+/** Regex to match citations for source files (hence the `F:` prefix). */
+const citationRegex = new RegExp(
+  [
+    // Opening marker
+    "【",
+
+    // Capture group 1: file ID or name (anything except '†')
+    "F:([^†]+)",
+
+    // Field separator
+    "†",
+
+    // Capture group 2: start line (digits)
+    "L(\\d+)",
+
+    // Non-capturing group for optional end line
+    "(?:",
+
+    // Capture group 3: end line (digits or '?')
+    "-L(\\d+|\\?)",
+
+    // End of optional group (may not be present)
+    ")?",
+
+    // Closing marker
+    "】",
+  ].join(""),
+  "g", // Global flag
+);
+
+function rewriteFileCitations(
+  markdown: string,
+  fileOpener: FileOpenerScheme | undefined,
+  cwd: string = process.cwd(),
+): string {
+  citationRegex.lastIndex = 0;
+  return markdown.replace(citationRegex, (_match, file, start, _end) => {
+    const absPath = path.resolve(cwd, file);
+    if (!fileOpener) {
+      return `[${file}](${absPath})`;
+    }
+    const uri = `${fileOpener}://file${absPath}:${start}`;
+    const label = `${file}:${start}`;
+    // In practice, sometimes multiple citations for the same file, but with a
+    // different line number, are shown sequentially, so we:
+    // - include the line number in the label to disambiguate them
+    // - add a space after the link to make it easier to read
+    return `[${label}](${uri}) `;
+  });
+}

codex-cli/src/components/chat/terminal-chat.tsx

@@ -1,3 +1,4 @@
+import type { AppRollout } from "../../app.js";
 import type { ApplyPatchCommand, ApprovalPolicy } from "../../approvals.js";
 import type { CommandConfirmation } from "../../utils/agent/agent-loop.js";
 import type { AppConfig } from "../../utils/config.js";
@@ -5,6 +6,7 @@ import type { ColorName } from "chalk";
 import type { ResponseItem } from "openai/resources/responses/responses.mjs";
 
 import TerminalChatInput from "./terminal-chat-input.js";
+import TerminalChatPastRollout from "./terminal-chat-past-rollout.js";
 import { TerminalChatToolCallCommand } from "./terminal-chat-tool-call-command.js";
 import TerminalMessageHistory from "./terminal-message-history.js";
 import { formatCommandForDisplay } from "../../format-command.js";
@@ -13,7 +15,7 @@ import { useTerminalSize } from "../../hooks/use-terminal-size.js";
 import { AgentLoop } from "../../utils/agent/agent-loop.js";
 import { ReviewDecision } from "../../utils/agent/review.js";
 import { generateCompactSummary } from "../../utils/compact-summary.js";
-import { getBaseUrl, getApiKey, saveConfig } from "../../utils/config.js";
+import { saveConfig } from "../../utils/config.js";
 import { extractAppliedPatches as _extractAppliedPatches } from "../../utils/extract-applied-patches.js";
 import { getGitDiff } from "../../utils/get-diff.js";
 import { createInputItem } from "../../utils/input-utils.js";
@@ -23,24 +25,27 @@ import {
   calculateContextPercentRemaining,
   uniqueById,
 } from "../../utils/model-utils.js";
-import { CLI_VERSION } from "../../utils/session.js";
+import { createOpenAIClient } from "../../utils/openai-client.js";
 import { shortCwd } from "../../utils/short-path.js";
 import { saveRollout } from "../../utils/storage/save-rollout.js";
+import { CLI_VERSION } from "../../version.js";
 import ApprovalModeOverlay from "../approval-mode-overlay.js";
 import DiffOverlay from "../diff-overlay.js";
 import HelpOverlay from "../help-overlay.js";
 import HistoryOverlay from "../history-overlay.js";
 import ModelOverlay from "../model-overlay.js";
+import SessionsOverlay from "../sessions-overlay.js";
 import chalk from "chalk";
+import fs from "fs/promises";
 import { Box, Text } from "ink";
 import { spawn } from "node:child_process";
-import OpenAI from "openai";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import { inspect } from "util";
 
 export type OverlayModeType =
   | "none"
   | "history"
+  | "sessions"
   | "model"
   | "approval"
   | "help"
@@ -78,10 +83,7 @@ async function generateCommandExplanation(
 ): Promise<string> {
   try {
     // Create a temporary OpenAI client
-    const oai = new OpenAI({
-      apiKey: getApiKey(config.provider),
-      baseURL: getBaseUrl(config.provider),
-    });
+    const oai = createOpenAIClient(config);
 
     // Format the command for display
     const commandForDisplay = formatCommandForDisplay(command);
@@ -194,6 +196,7 @@ export default function TerminalChat({
     submitConfirmation,
   } = useConfirmation();
   const [overlayMode, setOverlayMode] = useState<OverlayModeType>("none");
+  const [viewRollout, setViewRollout] = useState<AppRollout | null>(null);
 
   // Store the diff text when opening the diff overlay so the view isn’t
   // recomputed on every re‑render while it is open.
@@ -457,6 +460,16 @@ export default function TerminalChat({
     [items, model],
   );
 
+  if (viewRollout) {
+    return (
+      <TerminalChatPastRollout
+        fileOpener={config.fileOpener}
+        session={viewRollout.session}
+        items={viewRollout.items}
+      />
+    );
+  }
+
   return (
     <Box flexDirection="column">
       <Box flexDirection="column">
@@ -483,6 +496,7 @@ export default function TerminalChat({
               initialImagePaths,
               flexModeEnabled: Boolean(config.flexMode),
             }}
+            fileOpener={config.fileOpener}
           />
         ) : (
           <Box>
@@ -511,6 +525,7 @@ export default function TerminalChat({
             openModelOverlay={() => setOverlayMode("model")}
             openApprovalOverlay={() => setOverlayMode("approval")}
             openHelpOverlay={() => setOverlayMode("help")}
+            openSessionsOverlay={() => setOverlayMode("sessions")}
             openDiffOverlay={() => {
               const { isGitRepo, diff } = getGitDiff();
               let text: string;
@@ -570,6 +585,25 @@ export default function TerminalChat({
         {overlayMode === "history" && (
           <HistoryOverlay items={items} onExit={() => setOverlayMode("none")} />
         )}
+        {overlayMode === "sessions" && (
+          <SessionsOverlay
+            onView={async (p) => {
+              try {
+                const txt = await fs.readFile(p, "utf-8");
+                const data = JSON.parse(txt) as AppRollout;
+                setViewRollout(data);
+                setOverlayMode("none");
+              } catch {
+                setOverlayMode("none");
+              }
+            }}
+            onResume={(p) => {
+              setOverlayMode("none");
+              setInitialPrompt(`Resume this session: ${p}`);
+            }}
+            onExit={() => setOverlayMode("none")}
+          />
+        )}
         {overlayMode === "model" && (
           <ModelOverlay
             currentModel={model}

codex-cli/src/components/chat/terminal-message-history.tsx

@@ -2,6 +2,7 @@ import type { OverlayModeType } from "./terminal-chat.js";
 import type { TerminalHeaderProps } from "./terminal-header.js";
 import type { GroupedResponseItem } from "./use-message-grouping.js";
 import type { ResponseItem } from "openai/resources/responses/responses.mjs";
+import type { FileOpenerScheme } from "src/utils/config.js";
 
 import TerminalChatResponseItem from "./terminal-chat-response-item.js";
 import TerminalHeader from "./terminal-header.js";
@@ -23,6 +24,7 @@ type TerminalMessageHistoryProps = {
   headerProps: TerminalHeaderProps;
   fullStdout: boolean;
   setOverlayMode: React.Dispatch<React.SetStateAction<OverlayModeType>>;
+  fileOpener: FileOpenerScheme | undefined;
 };
 
 const TerminalMessageHistory: React.FC<TerminalMessageHistoryProps> = ({
@@ -33,6 +35,7 @@ const TerminalMessageHistory: React.FC<TerminalMessageHistoryProps> = ({
   thinkingSeconds: _thinkingSeconds,
   fullStdout,
   setOverlayMode,
+  fileOpener,
 }) => {
   // Flatten batch entries to response items.
   const messages = useMemo(() => batch.map(({ item }) => item!), [batch]);
@@ -59,16 +62,25 @@ const TerminalMessageHistory: React.FC<TerminalMessageHistoryProps> = ({
               key={`${message.id}-${index}`}
               flexDirection="column"
               marginLeft={
-                message.type === "message" && message.role === "user" ? 0 : 4
+                message.type === "message" &&
+                (message.role === "user" || message.role === "assistant")
+                  ? 0
+                  : 4
               }
               marginTop={
                 message.type === "message" && message.role === "user" ? 0 : 1
               }
+              marginBottom={
+                message.type === "message" && message.role === "assistant"
+                  ? 1
+                  : 0
+              }
             >
               <TerminalChatResponseItem
                 item={message}
                 fullStdout={fullStdout}
                 setOverlayMode={setOverlayMode}
+                fileOpener={fileOpener}
               />
             </Box>
           );

codex-cli/src/components/sessions-overlay.tsx

@@ -0,0 +1,130 @@
+import type { TypeaheadItem } from "./typeahead-overlay.js";
+
+import TypeaheadOverlay from "./typeahead-overlay.js";
+import fs from "fs/promises";
+import { Box, Text, useInput } from "ink";
+import os from "os";
+import path from "path";
+import React, { useEffect, useState } from "react";
+
+const SESSIONS_ROOT = path.join(os.homedir(), ".codex", "sessions");
+
+export type SessionMeta = {
+  path: string;
+  timestamp: string;
+  userMessages: number;
+  toolCalls: number;
+  firstMessage: string;
+};
+
+async function loadSessions(): Promise<Array<SessionMeta>> {
+  try {
+    const entries = await fs.readdir(SESSIONS_ROOT);
+    const sessions: Array<SessionMeta> = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) {
+        continue;
+      }
+      const filePath = path.join(SESSIONS_ROOT, entry);
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const content = await fs.readFile(filePath, "utf-8");
+        const data = JSON.parse(content) as {
+          session?: { timestamp?: string };
+          items?: Array<{
+            type: string;
+            role: string;
+            content: Array<{ text: string }>;
+          }>;
+        };
+        const items = Array.isArray(data.items) ? data.items : [];
+        const firstUser = items.find(
+          (i) => i?.type === "message" && i.role === "user",
+        );
+        const firstText =
+          firstUser?.content?.[0]?.text?.replace(/\n/g, " ").slice(0, 16) ?? "";
+        const userMessages = items.filter(
+          (i) => i?.type === "message" && i.role === "user",
+        ).length;
+        const toolCalls = items.filter(
+          (i) => i?.type === "function_call",
+        ).length;
+        sessions.push({
+          path: filePath,
+          timestamp: data.session?.timestamp || "",
+          userMessages,
+          toolCalls,
+          firstMessage: firstText,
+        });
+      } catch {
+        /* ignore invalid session */
+      }
+    }
+    sessions.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return sessions;
+  } catch {
+    return [];
+  }
+}
+
+type Props = {
+  onView: (sessionPath: string) => void;
+  onResume: (sessionPath: string) => void;
+  onExit: () => void;
+};
+
+export default function SessionsOverlay({
+  onView,
+  onResume,
+  onExit,
+}: Props): JSX.Element {
+  const [items, setItems] = useState<Array<TypeaheadItem>>([]);
+  const [mode, setMode] = useState<"view" | "resume">("view");
+
+  useEffect(() => {
+    (async () => {
+      const sessions = await loadSessions();
+      const formatted = sessions.map((s) => {
+        const ts = s.timestamp
+          ? new Date(s.timestamp).toLocaleString(undefined, {
+              dateStyle: "short",
+              timeStyle: "short",
+            })
+          : "";
+        const first = s.firstMessage?.slice(0, 50);
+        const label = `${ts} · ${s.userMessages} msgs/${s.toolCalls} tools · ${first}`;
+        return { label, value: s.path } as TypeaheadItem;
+      });
+      setItems(formatted);
+    })();
+  }, []);
+
+  useInput((_input, key) => {
+    if (key.tab) {
+      setMode((m) => (m === "view" ? "resume" : "view"));
+    }
+  });
+
+  return (
+    <TypeaheadOverlay
+      title={mode === "view" ? "View session" : "Resume session"}
+      description={
+        <Box flexDirection="column">
+          <Text>
+            {mode === "view" ? "press enter to view" : "press enter to resume"}
+          </Text>
+          <Text dimColor>tab to toggle mode · esc to cancel</Text>
+        </Box>
+      }
+      initialItems={items}
+      onSelect={(value) => {
+        if (mode === "view") {
+          onView(value);
+        } else {
+          onResume(value);
+        }
+      }}
+      onExit={onExit}
+    />
+  );
+}

codex-cli/src/components/singlepass-cli-app.tsx

@@ -5,13 +5,7 @@ import type { FileOperation } from "../utils/singlepass/file_ops";
 
 import Spinner from "./vendor/ink-spinner"; // Third‑party / vendor components
 import TextInput from "./vendor/ink-text-input";
-import {
-  OPENAI_TIMEOUT_MS,
-  OPENAI_ORGANIZATION,
-  OPENAI_PROJECT,
-  getBaseUrl,
-  getApiKey,
-} from "../utils/config";
+import { createOpenAIClient } from "../utils/openai-client";
 import {
   generateDiffSummary,
   generateEditSummary,
@@ -26,7 +20,6 @@ import { EditedFilesSchema } from "../utils/singlepass/file_ops";
 import * as fsSync from "fs";
 import * as fsPromises from "fs/promises";
 import { Box, Text, useApp, useInput } from "ink";
-import OpenAI from "openai";
 import { zodResponseFormat } from "openai/helpers/zod";
 import path from "path";
 import React, { useEffect, useState, useRef } from "react";
@@ -399,20 +392,7 @@ export function SinglePassApp({
         files,
       });
 
-      const headers: Record<string, string> = {};
-      if (OPENAI_ORGANIZATION) {
-        headers["OpenAI-Organization"] = OPENAI_ORGANIZATION;
-      }
-      if (OPENAI_PROJECT) {
-        headers["OpenAI-Project"] = OPENAI_PROJECT;
-      }
-
-      const openai = new OpenAI({
-        apiKey: getApiKey(config.provider),
-        baseURL: getBaseUrl(config.provider),
-        timeout: OPENAI_TIMEOUT_MS,
-        defaultHeaders: headers,
-      });
+      const openai = createOpenAIClient(config);
       const chatResp = await openai.beta.chat.completions.parse({
         model: config.model,
         ...(config.flexMode ? { service_tier: "flex" } : {}),

codex-cli/src/utils/agent/agent-loop.ts

@@ -8,30 +8,34 @@ import type {
   ResponseItem,
   ResponseCreateParams,
   FunctionTool,
+  Tool,
 } from "openai/resources/responses/responses.mjs";
 import type { Reasoning } from "openai/resources.mjs";
 
+import { CLI_VERSION } from "../../version.js";
 import {
   OPENAI_TIMEOUT_MS,
   OPENAI_ORGANIZATION,
   OPENAI_PROJECT,
-  getApiKey,
   getBaseUrl,
+  AZURE_OPENAI_API_VERSION,
 } from "../config.js";
 import { log } from "../logger/log.js";
 import { parseToolCallArguments } from "../parsers.js";
 import { responsesCreateViaChatCompletions } from "../responses.js";
 import {
   ORIGIN,
-  CLI_VERSION,
   getSessionId,
   setCurrentModel,
   setSessionId,
 } from "../session.js";
+import { applyPatchToolInstructions } from "./apply-patch.js";
 import { handleExecCommand } from "./handle-exec-command.js";
 import { HttpsProxyAgent } from "https-proxy-agent";
+import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import OpenAI, { APIConnectionTimeoutError } from "openai";
+import OpenAI, { APIConnectionTimeoutError, AzureOpenAI } from "openai";
+import os from "os";
 
 // Wait time before retrying after rate limit errors (ms).
 const RATE_LIMIT_RETRY_WAIT_MS = parseInt(
@@ -80,7 +84,7 @@ type AgentLoopParams = {
   onLastResponseId: (lastResponseId: string) => void;
 };
 
-const shellTool: FunctionTool = {
+const shellFunctionTool: FunctionTool = {
   type: "function",
   name: "shell",
   description: "Runs a shell command, and returns its output.",
@@ -104,6 +108,11 @@ const shellTool: FunctionTool = {
   },
 };
 
+const localShellTool: Tool = {
+  //@ts-expect-error - waiting on sdk
+  type: "local_shell",
+};
+
 export class AgentLoop {
   private model: string;
   private provider: string;
@@ -297,7 +306,7 @@ export class AgentLoop {
     this.sessionId = getSessionId() || randomUUID().replaceAll("-", "");
     // Configure OpenAI client with optional timeout (ms) from environment
     const timeoutMs = OPENAI_TIMEOUT_MS;
-    const apiKey = getApiKey(this.provider);
+    const apiKey = this.config.apiKey ?? process.env["OPENAI_API_KEY"] ?? "";
     const baseURL = getBaseUrl(this.provider);
 
     this.oai = new OpenAI({
@@ -322,6 +331,25 @@ export class AgentLoop {
       ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
     });
 
+    if (this.provider.toLowerCase() === "azure") {
+      this.oai = new AzureOpenAI({
+        apiKey,
+        baseURL,
+        apiVersion: AZURE_OPENAI_API_VERSION,
+        defaultHeaders: {
+          originator: ORIGIN,
+          version: CLI_VERSION,
+          session_id: this.sessionId,
+          ...(OPENAI_ORGANIZATION
+            ? { "OpenAI-Organization": OPENAI_ORGANIZATION }
+            : {}),
+          ...(OPENAI_PROJECT ? { "OpenAI-Project": OPENAI_PROJECT } : {}),
+        },
+        httpAgent: PROXY_URL ? new HttpsProxyAgent(PROXY_URL) : undefined,
+        ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
+      });
+    }
+
     setSessionId(this.sessionId);
     setCurrentModel(this.model);
 
@@ -438,6 +466,73 @@ export class AgentLoop {
     return [outputItem, ...additionalItems];
   }
 
+  private async handleLocalShellCall(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    item: any,
+  ): Promise<Array<ResponseInputItem>> {
+    // If the agent has been canceled in the meantime we should not perform any
+    // additional work. Returning an empty array ensures that we neither execute
+    // the requested tool call nor enqueue any follow‑up input items. This keeps
+    // the cancellation semantics intuitive for users – once they interrupt a
+    // task no further actions related to that task should be taken.
+    if (this.canceled) {
+      return [];
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const outputItem: any = {
+      type: "local_shell_call_output",
+      // `call_id` is mandatory – ensure we never send `undefined` which would
+      // trigger the "No tool output found…" 400 from the API.
+      call_id: item.call_id,
+      output: "no function found",
+    };
+
+    // We intentionally *do not* remove this `callId` from the `pendingAborts`
+    // set right away.  The output produced below is only queued up for the
+    // *next* request to the OpenAI API – it has not been delivered yet.  If
+    // the user presses ESC‑ESC (i.e. invokes `cancel()`) in the small window
+    // between queuing the result and the actual network call, we need to be
+    // able to surface a synthetic `function_call_output` marked as
+    // "aborted".  Keeping the ID in the set until the run concludes
+    // successfully lets the next `run()` differentiate between an aborted
+    // tool call (needs the synthetic output) and a completed one (cleared
+    // below in the `flush()` helper).
+
+    // used to tell model to stop if needed
+    const additionalItems: Array<ResponseInputItem> = [];
+
+    if (item.action.type !== "exec") {
+      throw new Error("Invalid action type");
+    }
+
+    const args = {
+      cmd: item.action.command,
+      workdir: item.action.working_directory,
+      timeoutInMillis: item.action.timeout_ms,
+    };
+
+    const {
+      outputText,
+      metadata,
+      additionalItems: additionalItemsFromExec,
+    } = await handleExecCommand(
+      args,
+      this.config,
+      this.approvalPolicy,
+      this.additionalWritableRoots,
+      this.getCommandConfirmation,
+      this.execAbortController?.signal,
+    );
+    outputItem.output = JSON.stringify({ output: outputText, metadata });
+
+    if (additionalItemsFromExec) {
+      additionalItems.push(...additionalItemsFromExec);
+    }
+
+    return [outputItem, ...additionalItems];
+  }
+
   public async run(
     input: Array<ResponseInputItem>,
     previousResponseId: string = "",
@@ -522,6 +617,11 @@ export class AgentLoop {
       // `disableResponseStorage === true`.
       let transcriptPrefixLen = 0;
 
+      let tools: Array<Tool> = [shellFunctionTool];
+      if (this.model.startsWith("codex")) {
+        tools = [localShellTool];
+      }
+
       const stripInternalFields = (
         item: ResponseInputItem,
       ): ResponseInputItem => {
@@ -625,6 +725,8 @@ export class AgentLoop {
                 if (
                   (item as ResponseInputItem).type === "function_call" ||
                   (item as ResponseInputItem).type === "reasoning" ||
+                  //@ts-expect-error - waiting on sdk
+                  (item as ResponseInputItem).type === "local_shell_call" ||
                   ((item as ResponseInputItem).type === "message" &&
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     (item as any).role === "user")
@@ -663,7 +765,7 @@ export class AgentLoop {
         // prompts) and so that freshly generated `function_call_output`s are
         // shown immediately.
         // Figure out what subset of `turnInput` constitutes *new* information
-        // for the UI so that we don’t spam the interface with repeats of the
+        // for the UI so that we don't spam the interface with repeats of the
         // entire transcript on every iteration when response storage is
         // disabled.
         const deltaInput = this.disableResponseStorage
@@ -680,13 +782,19 @@ export class AgentLoop {
         for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
           try {
             let reasoning: Reasoning | undefined;
-            if (this.model.startsWith("o")) {
-              reasoning = { effort: this.config.reasoningEffort ?? "high" };
-              if (this.model === "o3" || this.model === "o4-mini") {
-                reasoning.summary = "auto";
-              }
+            let modelSpecificInstructions: string | undefined;
+            if (this.model.startsWith("o") || this.model.startsWith("codex")) {
+              reasoning = { effort: this.config.reasoningEffort ?? "medium" };
+              reasoning.summary = "auto";
             }
-            const mergedInstructions = [prefix, this.instructions]
+            if (this.model.startsWith("gpt-4.1")) {
+              modelSpecificInstructions = applyPatchToolInstructions;
+            }
+            const mergedInstructions = [
+              prefix,
+              modelSpecificInstructions,
+              this.instructions,
+            ]
               .filter(Boolean)
               .join("\n");
 
@@ -719,7 +827,7 @@ export class AgentLoop {
                     store: true,
                     previous_response_id: lastResponseId || undefined,
                   }),
-              tools: [shellTool],
+              tools: tools,
               // Explicitly tell the model it is allowed to pick whatever
               // tool it deems appropriate.  Omitting this sometimes leads to
               // the model ignoring the available tools and responding with
@@ -744,7 +852,13 @@ export class AgentLoop {
             const errCtx = error as any;
             const status =
               errCtx?.status ?? errCtx?.httpStatus ?? errCtx?.statusCode;
-            const isServerError = typeof status === "number" && status >= 500;
+            // Treat classical 5xx *and* explicit OpenAI `server_error` types
+            // as transient server-side failures that qualify for a retry. The
+            // SDK often omits the numeric status for these, reporting only
+            // the `type` field.
+            const isServerError =
+              (typeof status === "number" && status >= 500) ||
+              errCtx?.type === "server_error";
             if (
               (isTimeout || isServerError || isConnectionError) &&
               attempt < MAX_RETRIES
@@ -933,7 +1047,10 @@ export class AgentLoop {
                 if (maybeReasoning.type === "reasoning") {
                   maybeReasoning.duration_ms = Date.now() - thinkingStart;
                 }
-                if (item.type === "function_call") {
+                if (
+                  item.type === "function_call" ||
+                  item.type === "local_shell_call"
+                ) {
                   // Track outstanding tool call so we can abort later if needed.
                   // The item comes from the streaming response, therefore it has
                   // either `id` (chat) or `call_id` (responses) – we normalise
@@ -1056,7 +1173,11 @@ export class AgentLoop {
               let reasoning: Reasoning | undefined;
               if (this.model.startsWith("o")) {
                 reasoning = { effort: "high" };
-                if (this.model === "o3" || this.model === "o4-mini") {
+                if (
+                  this.model === "o3" ||
+                  this.model === "o4-mini" ||
+                  this.model === "codex-mini-latest"
+                ) {
                   reasoning.summary = "auto";
                 }
               }
@@ -1095,7 +1216,7 @@ export class AgentLoop {
                       store: true,
                       previous_response_id: lastResponseId || undefined,
                     }),
-                tools: [shellTool],
+                tools: tools,
                 tool_choice: "auto",
               });
 
@@ -1457,6 +1578,17 @@ export class AgentLoop {
         // eslint-disable-next-line no-await-in-loop
         const result = await this.handleFunctionCall(item);
         turnInput.push(...result);
+        //@ts-expect-error - waiting on sdk
+      } else if (item.type === "local_shell_call") {
+        //@ts-expect-error - waiting on sdk
+        if (alreadyProcessedResponses.has(item.id)) {
+          continue;
+        }
+        //@ts-expect-error - waiting on sdk
+        alreadyProcessedResponses.add(item.id);
+        // eslint-disable-next-line no-await-in-loop
+        const result = await this.handleLocalShellCall(item);
+        turnInput.push(...result);
       }
       emitItem(item as ResponseItem);
     }
@@ -1464,6 +1596,19 @@ export class AgentLoop {
   }
 }
 
+// Dynamic developer message prefix: includes user, workdir, and rg suggestion.
+const userName = os.userInfo().username;
+const workdir = process.cwd();
+const dynamicLines: Array<string> = [
+  `User: ${userName}`,
+  `Workdir: ${workdir}`,
+];
+if (spawnSync("rg", ["--version"], { stdio: "ignore" }).status === 0) {
+  dynamicLines.push(
+    "- Always use rg instead of grep/ls -R because it is much faster and respects gitignore",
+  );
+}
+const dynamicPrefix = dynamicLines.join("\n");
 const prefix = `You are operating as and within the Codex CLI, a terminal-based agentic coding assistant built by OpenAI. It wraps OpenAI models to enable natural language interaction with a local codebase. You are expected to be precise, safe, and helpful.
 
 You can:
@@ -1499,7 +1644,6 @@ You MUST adhere to the following criteria when executing the task:
         - If there is a .pre-commit-config.yaml, use \`pre-commit run --files ...\` to check that your changes pass the pre-commit checks. However, do not fix pre-existing errors on lines you didn't touch.
             - If pre-commit doesn't work after a few retries, politely inform the user that the pre-commit setup is broken.
         - Once you finish coding, you must
-            - Check \`git status\` to sanity check your changes; revert any scratch files or changes.
             - Remove all inline comments you added as much as possible, even if they look normal. Check using \`git diff\`. Inline comments must be generally avoided, unless active maintainers of the repo, after long careful study of the code and the issue, will still misinterpret the code without the comments.
             - Check if you accidentally add copyright or license headers. If so, remove them.
             - Try to run pre-commit if it is available.
@@ -1509,7 +1653,9 @@ You MUST adhere to the following criteria when executing the task:
     - Respond in a friendly tone as a remote teammate, who is knowledgeable, capable and eager to help with coding.
 - When your task involves writing or modifying files:
     - Do NOT tell the user to "save the file" or "copy the code into a file" if you already created or modified the file using \`apply_patch\`. Instead, reference the file as already saved.
-    - Do NOT show the full contents of large files you have already written, unless the user explicitly asks for them.`;
+    - Do NOT show the full contents of large files you have already written, unless the user explicitly asks for them.
+
+${dynamicPrefix}`;
 
 function filterToApiMessages(
   items: Array<ResponseInputItem>,

codex-cli/src/utils/agent/apply-patch.ts

@@ -550,7 +550,15 @@ export function text_to_patch(
     !(lines[0] ?? "").startsWith(PATCH_PREFIX.trim()) ||
     lines[lines.length - 1] !== PATCH_SUFFIX.trim()
   ) {
-    throw new DiffError("Invalid patch text");
+    let reason = "Invalid patch text: ";
+    if (lines.length < 2) {
+      reason += "Patch text must have at least two lines.";
+    } else if (!(lines[0] ?? "").startsWith(PATCH_PREFIX.trim())) {
+      reason += "Patch text must start with the correct patch prefix.";
+    } else if (lines[lines.length - 1] !== PATCH_SUFFIX.trim()) {
+      reason += "Patch text must end with the correct patch suffix.";
+    }
+    throw new DiffError(reason);
   }
   const parser = new Parser(orig, lines);
   parser.index = 1;
@@ -762,3 +770,46 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     }
   });
 }
+
+export const applyPatchToolInstructions = `
+To edit files, ALWAYS use the \`shell\` tool with \`apply_patch\` CLI.  \`apply_patch\` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the \`apply_patch\` CLI, you should call the shell tool with the following structure:
+
+\`\`\`bash
+{"cmd": ["apply_patch", "<<'EOF'\\n*** Begin Patch\\n[YOUR_PATCH]\\n*** End Patch\\nEOF\\n"], "workdir": "..."}
+\`\`\`
+
+Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
+
+*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
+For each snippet of code that needs to be changed, repeat the following:
+[context_before] -> See below for further instructions on context.
+- [old_code] -> Precede the old code with a minus sign.
++ [new_code] -> Precede the new, replacement code with a plus sign.
+[context_after] -> See below for further instructions on context.
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single \`@@\` statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple \`@@\` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
+
+\`\`\`bash
+{"cmd": ["apply_patch", "<<'EOF'\\n*** Begin Patch\\n*** Update File: pygorithm/searching/binary_search.py\\n@@ class BaseClass\\n@@     def search():\\n-        pass\\n+        raise NotImplementedError()\\n@@ class Subclass\\n@@     def search():\\n-        pass\\n+        raise NotImplementedError()\\n*** End Patch\\nEOF\\n"], "workdir": "..."}
+\`\`\`
+
+File references can only be relative, NEVER ABSOLUTE. After the apply_patch command is run, it will always say "Done!", regardless of whether the patch was successfully applied or not. However, you can determine if there are issue and errors by looking at any warnings or logging lines printed BEFORE the "Done!" is output.
+`;

codex-cli/src/utils/agent/exec.ts

@@ -9,11 +9,13 @@ import { execWithLandlock } from "./sandbox/landlock.js";
 import { execWithSeatbelt } from "./sandbox/macos-seatbelt.js";
 import { exec as rawExec } from "./sandbox/raw-exec.js";
 import { formatCommandForDisplay } from "../../format-command.js";
+import { log } from "../logger/log.js";
 import fs from "fs";
 import os from "os";
 import path from "path";
 import { parse } from "shell-quote";
 import { resolvePathAgainstWorkdir } from "src/approvals.js";
+import { PATCH_SUFFIX } from "src/parse-apply-patch.js";
 
 const DEFAULT_TIMEOUT_MS = 10_000; // 10 seconds
 
@@ -81,12 +83,22 @@ export function execApplyPatch(
   patchText: string,
   workdir: string | undefined = undefined,
 ): ExecResult {
-  // This is a temporary measure to understand what are the common base commands
-  // until we start persisting and uploading rollouts
+  // This find/replace is required from some models like 4.1 where the patch
+  // text is wrapped in quotes that breaks the apply_patch command.
+  let applyPatchInput = patchText
+    .replace(/('|")?<<('|")EOF('|")/, "")
+    .replace(/\*\*\* End Patch\nEOF('|")?/, "*** End Patch")
+    .trim();
+
+  if (!applyPatchInput.endsWith(PATCH_SUFFIX)) {
+    applyPatchInput += "\n" + PATCH_SUFFIX;
+  }
+
+  log(`Applying patch: \`\`\`${applyPatchInput}\`\`\`\n\n`);
 
   try {
     const result = process_patch(
-      patchText,
+      applyPatchInput,
       (p) => fs.readFileSync(resolvePathAgainstWorkdir(p, workdir), "utf8"),
       (p, c) => {
         const resolvedPath = resolvePathAgainstWorkdir(p, workdir);

codex-cli/src/utils/check-updates.ts

@@ -1,7 +1,7 @@
 import type { AgentName } from "package-manager-detector";
 
 import { detectInstallerByPath } from "./package-manager-detector";
-import { CLI_VERSION } from "./session";
+import { CLI_VERSION } from "../version";
 import boxen from "boxen";
 import chalk from "chalk";
 import { getLatestVersion } from "fast-npm-meta";

codex-cli/src/utils/compact-summary.ts

@@ -1,12 +1,14 @@
 import type { AppConfig } from "./config.js";
 import type { ResponseItem } from "openai/resources/responses/responses.mjs";
 
-import { getBaseUrl, getApiKey } from "./config.js";
-import OpenAI from "openai";
+import { createOpenAIClient } from "./openai-client.js";
+
 /**
  * Generate a condensed summary of the conversation items.
  * @param items The list of conversation items to summarize
  * @param model The model to use for generating the summary
+ * @param flexMode Whether to use the flex-mode service tier
+ * @param config The configuration object
  * @returns A concise structured summary string
  */
 /**
@@ -23,10 +25,7 @@ export async function generateCompactSummary(
   flexMode = false,
   config: AppConfig,
 ): Promise<string> {
-  const oai = new OpenAI({
-    apiKey: getApiKey(config.provider),
-    baseURL: getBaseUrl(config.provider),
-  });
+  const oai = createOpenAIClient(config);
 
   const conversationText = items
     .filter(

codex-cli/src/utils/config.ts

@@ -43,7 +43,7 @@ if (!isVitest) {
   loadDotenv({ path: USER_WIDE_CONFIG_PATH });
 }
 
-export const DEFAULT_AGENTIC_MODEL = "o4-mini";
+export const DEFAULT_AGENTIC_MODEL = "codex-mini-latest";
 export const DEFAULT_FULL_CONTEXT_MODEL = "gpt-4.1";
 export const DEFAULT_APPROVAL_MODE = AutoApprovalMode.SUGGEST;
 export const DEFAULT_INSTRUCTIONS = "";
@@ -68,12 +68,15 @@ export const OPENAI_TIMEOUT_MS =
 export const OPENAI_BASE_URL = process.env["OPENAI_BASE_URL"] || "";
 export let OPENAI_API_KEY = process.env["OPENAI_API_KEY"] || "";
 
+export const AZURE_OPENAI_API_VERSION =
+  process.env["AZURE_OPENAI_API_VERSION"] || "2025-03-01-preview";
+
 export const DEFAULT_REASONING_EFFORT = "high";
 export const OPENAI_ORGANIZATION = process.env["OPENAI_ORGANIZATION"] || "";
 export const OPENAI_PROJECT = process.env["OPENAI_PROJECT"] || "";
 
 // Can be set `true` when Codex is running in an environment that is marked as already
-// considered sufficiently locked-down so that we allow running wihtout an explicit sandbox.
+// considered sufficiently locked-down so that we allow running without an explicit sandbox.
 export const CODEX_UNSAFE_ALLOW_NO_SANDBOX = Boolean(
   process.env["CODEX_UNSAFE_ALLOW_NO_SANDBOX"] || "",
 );
@@ -117,7 +120,7 @@ export function getApiKey(provider: string = "openai"): string | undefined {
     return process.env[providerInfo.envKey];
   }
 
-  // Checking `PROVIDER_API_KEY feels more intuitive with a custom provider.
+  // Checking `PROVIDER_API_KEY` feels more intuitive with a custom provider.
   const customApiKey = process.env[`${provider.toUpperCase()}_API_KEY`];
   if (customApiKey) {
     return customApiKey;
@@ -132,6 +135,8 @@ export function getApiKey(provider: string = "openai"): string | undefined {
   return undefined;
 }
 
+export type FileOpenerScheme = "vscode" | "cursor" | "windsurf";
+
 // Represents config as persisted in config.json.
 export type StoredConfig = {
   model?: string;
@@ -143,6 +148,7 @@ export type StoredConfig = {
   notify?: boolean;
   /** Disable server-side response storage (send full transcript each request) */
   disableResponseStorage?: boolean;
+  flexMode?: boolean;
   providers?: Record<string, { name: string; baseURL: string; envKey: string }>;
   history?: {
     maxSize?: number;
@@ -158,6 +164,12 @@ export type StoredConfig = {
   /** User-defined safe commands */
   safeCommands?: Array<string>;
   reasoningEffort?: ReasoningEffort;
+
+  /**
+   * URI-based file opener. This is used when linking code references in
+   * terminal output.
+   */
+  fileOpener?: FileOpenerScheme;
 };
 
 // Minimal config written on first run.  An *empty* model string ensures that
@@ -202,18 +214,29 @@ export type AppConfig = {
       maxLines: number;
     };
   };
+  fileOpener?: FileOpenerScheme;
 };
 
 // Formatting (quiet mode-only).
 export const PRETTY_PRINT = Boolean(process.env["PRETTY_PRINT"] || "");
 
 // ---------------------------------------------------------------------------
-// Project doc support (codex.md)
+// Project doc support (AGENTS.md / codex.md)
 // ---------------------------------------------------------------------------
 
 export const PROJECT_DOC_MAX_BYTES = 32 * 1024; // 32 kB
 
-const PROJECT_DOC_FILENAMES = ["codex.md", ".codex.md", "CODEX.md"];
+// We support multiple filenames for project-level agent instructions.  As of
+// 2025 the recommended convention is to use `AGENTS.md`, however we keep
+// the legacy `codex.md` variants for backwards-compatibility so that existing
+// repositories continue to work without changes.  The list is ordered so that
+// the first match wins – newer conventions first, older fallbacks later.
+const PROJECT_DOC_FILENAMES = [
+  "AGENTS.md", // preferred
+  "codex.md", // legacy
+  ".codex.md",
+  "CODEX.md",
+];
 const PROJECT_DOC_SEPARATOR = "\n\n--- project-doc ---\n\n";
 
 export function discoverProjectDocPath(startDir: string): string | null {
@@ -254,7 +277,8 @@ export function discoverProjectDocPath(startDir: string): string | null {
 }
 
 /**
- * Load the project documentation markdown (codex.md) if present. If the file
+ * Load the project documentation markdown (`AGENTS.md` – or the legacy
+ * `codex.md`) if present. If the file
  * exceeds {@link PROJECT_DOC_MAX_BYTES} it will be truncated and a warning is
  * logged.
  *
@@ -414,6 +438,7 @@ export const loadConfig = (
     },
     disableResponseStorage: storedConfig.disableResponseStorage === true,
     reasoningEffort: storedConfig.reasoningEffort,
+    fileOpener: storedConfig.fileOpener,
   };
 
   // -----------------------------------------------------------------------
@@ -475,6 +500,10 @@ export const loadConfig = (
   }
   // Notification setting: enable desktop notifications when set in config
   config.notify = storedConfig.notify === true;
+  // Flex-mode setting: enable the flex-mode service tier when set in config
+  if (storedConfig.flexMode !== undefined) {
+    config.flexMode = storedConfig.flexMode;
+  }
 
   // Add default history config if not provided
   if (storedConfig.history !== undefined) {
@@ -529,6 +558,7 @@ export const saveConfig = (
     providers: config.providers,
     approvalMode: config.approvalMode,
     disableResponseStorage: config.disableResponseStorage,
+    flexMode: config.flexMode,
     reasoningEffort: config.reasoningEffort,
   };
 

codex-cli/src/utils/get-api-key-components.tsx

@@ -0,0 +1,75 @@
+import SelectInput from "../components/select-input/select-input.js";
+import Spinner from "../components/vendor/ink-spinner.js";
+import TextInput from "../components/vendor/ink-text-input.js";
+import { Box, Text } from "ink";
+import React, { useState } from "react";
+
+export type Choice = { type: "signin" } | { type: "apikey"; key: string };
+
+export function ApiKeyPrompt({
+  onDone,
+}: {
+  onDone: (choice: Choice) => void;
+}): JSX.Element {
+  const [step, setStep] = useState<"select" | "paste">("select");
+  const [apiKey, setApiKey] = useState("");
+
+  if (step === "select") {
+    return (
+      <Box flexDirection="column" gap={1}>
+        <Box flexDirection="column">
+          <Text>
+            Sign in with ChatGPT to generate an API key or paste one you already
+            have.
+          </Text>
+          <Text dimColor>[use arrows to move, enter to select]</Text>
+        </Box>
+        <SelectInput
+          items={[
+            { label: "Sign in with ChatGPT", value: "signin" },
+            {
+              label: "Paste an API key (or set as OPENAI_API_KEY)",
+              value: "paste",
+            },
+          ]}
+          onSelect={(item: { value: string }) => {
+            if (item.value === "signin") {
+              onDone({ type: "signin" });
+            } else {
+              setStep("paste");
+            }
+          }}
+        />
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column">
+      <Text>Paste your OpenAI API key and press &lt;Enter&gt;:</Text>
+      <TextInput
+        value={apiKey}
+        onChange={setApiKey}
+        onSubmit={(value: string) => {
+          if (value.trim() !== "") {
+            onDone({ type: "apikey", key: value.trim() });
+          }
+        }}
+        placeholder="sk-..."
+        mask="*"
+      />
+    </Box>
+  );
+}
+
+export function WaitingForAuth(): JSX.Element {
+  return (
+    <Box flexDirection="row" marginTop={1}>
+      <Spinner type="ball" />
+      <Text>
+        {" "}
+        Waiting for authentication… <Text dimColor>ctrl + c to quit</Text>
+      </Text>
+    </Box>
+  );
+}

codex-cli/src/utils/get-api-key.tsx

@@ -0,0 +1,764 @@
+import type { Choice } from "./get-api-key-components";
+import type { Request, Response } from "express";
+
+import { ApiKeyPrompt, WaitingForAuth } from "./get-api-key-components";
+import chalk from "chalk";
+import express from "express";
+import fs from "fs/promises";
+import { render } from "ink";
+import crypto from "node:crypto";
+import { URL } from "node:url";
+import open from "open";
+import os from "os";
+import path from "path";
+import React from "react";
+
+function promptUserForChoice(): Promise<Choice> {
+  return new Promise<Choice>((resolve) => {
+    const instance = render(
+      <ApiKeyPrompt
+        onDone={(choice: Choice) => {
+          resolve(choice);
+          instance.unmount();
+        }}
+      />,
+    );
+  });
+}
+
+interface OidcConfiguration {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+}
+
+async function getOidcConfiguration(
+  issuer: string,
+): Promise<OidcConfiguration> {
+  const discoveryUrl = new URL(issuer);
+  discoveryUrl.pathname = "/.well-known/openid-configuration";
+
+  if (issuer === "https://auth.openai.com") {
+    // Account for legacy quirk in production tenant
+    discoveryUrl.pathname = "/v2.0" + discoveryUrl.pathname;
+  }
+
+  const res = await fetch(discoveryUrl.toString());
+  if (!res.ok) {
+    throw new Error("Failed to fetch OIDC configuration");
+  }
+  return (await res.json()) as OidcConfiguration;
+}
+
+interface IDTokenClaims {
+  "exp": number;
+  "https://api.openai.com/auth": {
+    organization_id: string;
+    project_id: string;
+    completed_platform_onboarding: boolean;
+    is_org_owner: boolean;
+    chatgpt_subscription_active_start: string;
+    chatgpt_subscription_active_until: string;
+    chatgpt_plan_type: string;
+  };
+}
+
+interface AccessTokenClaims {
+  "https://api.openai.com/auth": {
+    chatgpt_plan_type: string;
+  };
+}
+
+function generatePKCECodes(): {
+  code_verifier: string;
+  code_challenge: string;
+} {
+  const code_verifier = crypto.randomBytes(64).toString("hex");
+  const code_challenge = crypto
+    .createHash("sha256")
+    .update(code_verifier)
+    .digest("base64url");
+  return { code_verifier, code_challenge };
+}
+
+async function maybeRedeemCredits(
+  issuer: string,
+  clientId: string,
+  refreshToken: string,
+  idToken?: string,
+): Promise<void> {
+  try {
+    let currentIdToken = idToken;
+    let idClaims: IDTokenClaims | undefined;
+
+    if (
+      currentIdToken &&
+      typeof currentIdToken === "string" &&
+      currentIdToken.split(".")[1]
+    ) {
+      idClaims = JSON.parse(
+        Buffer.from(currentIdToken.split(".")[1]!, "base64url").toString(
+          "utf8",
+        ),
+      ) as IDTokenClaims;
+    } else {
+      currentIdToken = "";
+    }
+
+    // Validate idToken expiration
+    // if expired, attempt token-exchange for a fresh idToken
+    if (!idClaims || !idClaims.exp || Date.now() >= idClaims.exp * 1000) {
+      // eslint-disable-next-line no-console
+      console.log(chalk.dim("Refreshing credentials..."));
+      try {
+        const refreshRes = await fetch("https://auth.openai.com/oauth/token", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            client_id: clientId,
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            scope: "openid profile email",
+          }),
+        });
+        if (!refreshRes.ok) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `Failed to refresh credentials: ${refreshRes.status} ${refreshRes.statusText}\n${chalk.dim(await refreshRes.text())}`,
+          );
+          // eslint-disable-next-line no-console
+          console.warn(
+            `Please sign in again to redeem credits: ${chalk.bold("codex --login")}`,
+          );
+          return;
+        }
+        const refreshData = (await refreshRes.json()) as {
+          id_token: string;
+          refresh_token?: string;
+        };
+        currentIdToken = refreshData.id_token;
+        idClaims = JSON.parse(
+          Buffer.from(currentIdToken.split(".")[1]!, "base64url").toString(
+            "utf8",
+          ),
+        ) as IDTokenClaims;
+        if (refreshData.refresh_token) {
+          try {
+            const home = os.homedir();
+            const authDir = path.join(home, ".codex");
+            const authFile = path.join(authDir, "auth.json");
+            const existingJson = JSON.parse(
+              await fs.readFile(authFile, "utf-8"),
+            );
+            existingJson.tokens.id_token = currentIdToken;
+            existingJson.tokens.refresh_token = refreshData.refresh_token;
+            existingJson.last_refresh = new Date().toISOString();
+            await fs.writeFile(
+              authFile,
+              JSON.stringify(existingJson, null, 2),
+              { mode: 0o600 },
+            );
+          } catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn("Unable to update refresh token in auth file:", err);
+          }
+        }
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("Unable to refresh ID token via token-exchange:", err);
+        return;
+      }
+    }
+
+    // Confirm the subscription is active for more than 7 days
+    const subStart =
+      idClaims["https://api.openai.com/auth"]
+        ?.chatgpt_subscription_active_start;
+    if (
+      typeof subStart === "string" &&
+      Date.now() - new Date(subStart).getTime() < 7 * 24 * 60 * 60 * 1000
+    ) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "Sorry, your subscription must be active for more than 7 days to redeem credits.\nMore info: " +
+          chalk.dim("https://help.openai.com/en/articles/11381614") +
+          chalk.bold(
+            "\nPlease try again on " +
+              new Date(
+                new Date(subStart).getTime() + 7 * 24 * 60 * 60 * 1000,
+              ).toLocaleDateString() +
+              " " +
+              new Date(
+                new Date(subStart).getTime() + 7 * 24 * 60 * 60 * 1000,
+              ).toLocaleTimeString(),
+          ),
+      );
+      return;
+    }
+
+    const completed = Boolean(
+      idClaims["https://api.openai.com/auth"]?.completed_platform_onboarding,
+    );
+    const isOwner = Boolean(
+      idClaims["https://api.openai.com/auth"]?.is_org_owner,
+    );
+    const needsSetup = !completed && isOwner;
+
+    const planType = idClaims["https://api.openai.com/auth"]
+      ?.chatgpt_plan_type as string | undefined;
+
+    if (needsSetup || !(planType === "plus" || planType === "pro")) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "Users with Plus or Pro subscriptions can redeem free API credits.\nMore info: " +
+          chalk.dim("https://help.openai.com/en/articles/11381614"),
+      );
+      return;
+    }
+
+    const apiHost =
+      issuer === "https://auth.openai.com"
+        ? "https://api.openai.com"
+        : "https://api.openai.org";
+
+    const redeemRes = await fetch(`${apiHost}/v1/billing/redeem_credits`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id_token: currentIdToken }),
+    });
+
+    if (!redeemRes.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `Credit redemption request failed: ${redeemRes.status} ${redeemRes.statusText}`,
+      );
+      return;
+    }
+
+    try {
+      const redeemData = (await redeemRes.json()) as {
+        granted_chatgpt_subscriber_api_credits?: number;
+      };
+      const granted = redeemData?.granted_chatgpt_subscriber_api_credits ?? 0;
+      if (granted > 0) {
+        // eslint-disable-next-line no-console
+        console.log(
+          chalk.green(
+            `${chalk.bold(
+              `Thanks for being a ChatGPT ${
+                planType === "plus" ? "Plus" : "Pro"
+              } subscriber!`,
+            )}\nIf you haven't already redeemed, you should receive ${
+              planType === "plus" ? "$5" : "$50"
+            } in API credits\nCredits: ${chalk.dim(chalk.underline("https://platform.openai.com/settings/organization/billing/credit-grants"))}\nMore info: ${chalk.dim(chalk.underline("https://help.openai.com/en/articles/11381614"))}`,
+          ),
+        );
+      } else {
+        // eslint-disable-next-line no-console
+        console.log(
+          chalk.green(
+            `It looks like no credits were granted:\n${JSON.stringify(
+              redeemData,
+              null,
+              2,
+            )}\nCredits: ${chalk.dim(
+              chalk.underline(
+                "https://platform.openai.com/settings/organization/billing/credit-grants",
+              ),
+            )}\nMore info: ${chalk.dim(
+              chalk.underline("https://help.openai.com/en/articles/11381614"),
+            )}`,
+          ),
+        );
+      }
+    } catch (parseErr) {
+      // eslint-disable-next-line no-console
+      console.warn("Unable to parse credit redemption response:", parseErr);
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("Unable to redeem ChatGPT subscriber API credits:", err);
+  }
+}
+
+async function handleCallback(
+  req: Request,
+  issuer: string,
+  oidcConfig: OidcConfiguration,
+  codeVerifier: string,
+  clientId: string,
+  redirectUri: string,
+  expectedState: string,
+): Promise<{ access_token: string; success_url: string }> {
+  const state = (req.query as Record<string, string>)["state"] as
+    | string
+    | undefined;
+  if (!state || state !== expectedState) {
+    throw new Error("Invalid state parameter");
+  }
+
+  const code = (req.query as Record<string, string>)["code"] as
+    | string
+    | undefined;
+  if (!code) {
+    throw new Error("Missing authorization code");
+  }
+
+  const params = new URLSearchParams();
+  params.append("grant_type", "authorization_code");
+  params.append("code", code);
+  params.append("redirect_uri", redirectUri);
+  params.append("client_id", clientId);
+  params.append("code_verifier", codeVerifier);
+
+  oidcConfig.token_endpoint = `${issuer}/oauth/token`;
+  const tokenRes = await fetch(oidcConfig.token_endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: params.toString(),
+  });
+
+  if (!tokenRes.ok) {
+    throw new Error("Failed to exchange authorization code for tokens");
+  }
+
+  const tokenData = (await tokenRes.json()) as {
+    id_token: string;
+    access_token: string;
+    refresh_token: string;
+  };
+
+  const idTokenParts = tokenData.id_token.split(".");
+  if (idTokenParts.length !== 3) {
+    throw new Error("Invalid ID token");
+  }
+  const accessTokenParts = tokenData.access_token.split(".");
+  if (accessTokenParts.length !== 3) {
+    throw new Error("Invalid access token");
+  }
+
+  const idTokenClaims = JSON.parse(
+    Buffer.from(idTokenParts[1]!, "base64url").toString("utf8"),
+  ) as IDTokenClaims;
+
+  const accessTokenClaims = JSON.parse(
+    Buffer.from(accessTokenParts[1]!, "base64url").toString("utf8"),
+  ) as AccessTokenClaims;
+
+  const org_id = idTokenClaims["https://api.openai.com/auth"]?.organization_id;
+
+  if (!org_id) {
+    throw new Error("Missing organization in id_token claims");
+  }
+  const project_id = idTokenClaims["https://api.openai.com/auth"]?.project_id;
+
+  if (!project_id) {
+    throw new Error("Missing project in id_token claims");
+  }
+
+  const randomId = crypto.randomBytes(6).toString("hex");
+  const exchangeParams = new URLSearchParams({
+    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+    client_id: clientId,
+    requested_token: "openai-api-key",
+    subject_token: tokenData.id_token,
+    subject_token_type: "urn:ietf:params:oauth:token-type:id_token",
+    name: `Codex CLI [auto-generated] (${new Date().toISOString().slice(0, 10)}) [${
+      randomId
+    }]`,
+  });
+  const exchangeRes = await fetch(oidcConfig.token_endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: exchangeParams.toString(),
+  });
+  if (!exchangeRes.ok) {
+    throw new Error(`Failed to create API key: ${await exchangeRes.text()}`);
+  }
+
+  const exchanged = (await exchangeRes.json()) as {
+    access_token: string;
+    key: string;
+  };
+
+  // Determine whether the organization still requires additional
+  // setup (e.g., adding a payment method) based on the ID-token
+  // claim provided by the auth service.
+  const completedOnboarding = Boolean(
+    idTokenClaims["https://api.openai.com/auth"]?.completed_platform_onboarding,
+  );
+  const chatgptPlanType =
+    accessTokenClaims["https://api.openai.com/auth"]?.chatgpt_plan_type;
+  const isOrgOwner = Boolean(
+    idTokenClaims["https://api.openai.com/auth"]?.is_org_owner,
+  );
+  const needsSetup = !completedOnboarding && isOrgOwner;
+
+  // Build the success URL on the same host/port as the callback and
+  // include the required query parameters for the front-end page.
+  // console.log("Redirecting to success page");
+  const successUrl = new URL("/success", redirectUri);
+  if (issuer === "https://auth.openai.com") {
+    successUrl.searchParams.set("platform_url", "https://platform.openai.com");
+  } else {
+    successUrl.searchParams.set(
+      "platform_url",
+      "https://platform.api.openai.org",
+    );
+  }
+  successUrl.searchParams.set("id_token", tokenData.id_token);
+  successUrl.searchParams.set("needs_setup", needsSetup ? "true" : "false");
+  successUrl.searchParams.set("org_id", org_id);
+  successUrl.searchParams.set("project_id", project_id);
+  successUrl.searchParams.set("plan_type", chatgptPlanType);
+
+  try {
+    const home = os.homedir();
+    const authDir = path.join(home, ".codex");
+    await fs.mkdir(authDir, { recursive: true });
+    const authFile = path.join(authDir, "auth.json");
+    const authData = {
+      tokens: tokenData,
+      last_refresh: new Date().toISOString(),
+      OPENAI_API_KEY: exchanged.access_token,
+    };
+    await fs.writeFile(authFile, JSON.stringify(authData, null, 2), {
+      mode: 0o600,
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("Unable to save auth file:", err);
+  }
+
+  await maybeRedeemCredits(
+    issuer,
+    clientId,
+    tokenData.refresh_token,
+    tokenData.id_token,
+  );
+
+  return {
+    access_token: exchanged.access_token,
+    success_url: successUrl.toString(),
+  };
+}
+
+const LOGIN_SUCCESS_HTML = String.raw`
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Sign into Codex CLI</title>
+    <link rel="icon" href='data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none" viewBox="0 0 32 32"%3E%3Cpath stroke="%23000" stroke-linecap="round" stroke-width="2.484" d="M22.356 19.797H17.17M9.662 12.29l1.979 3.576a.511.511 0 0 1-.005.504l-1.974 3.409M30.758 16c0 8.15-6.607 14.758-14.758 14.758-8.15 0-14.758-6.607-14.758-14.758C1.242 7.85 7.85 1.242 16 1.242c8.15 0 14.758 6.608 14.758 14.758Z"/%3E%3C/svg%3E' type="image/svg+xml">
+    <style>
+      .container {
+        margin: auto;
+        height: 100%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        position: relative;
+        background: white;
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+      }
+      .inner-container {
+        width: 400px;
+        flex-direction: column;
+        justify-content: flex-start;
+        align-items: center;
+        gap: 20px;
+        display: inline-flex;
+      }
+      .content {
+        align-self: stretch;
+        flex-direction: column;
+        justify-content: flex-start;
+        align-items: center;
+        gap: 20px;
+        display: flex;
+      }
+      .svg-wrapper {
+        position: relative;
+      }
+      .title {
+        text-align: center;
+        color: var(--text-primary, #0D0D0D);
+        font-size: 28px;
+        font-weight: 400;
+        line-height: 36.40px;
+        word-wrap: break-word;
+      }
+      .setup-box {
+        width: 600px;
+        padding: 16px 20px;
+        background: var(--bg-primary, white);
+        box-shadow: 0px 4px 16px rgba(0, 0, 0, 0.05);
+        border-radius: 16px;
+        outline: 1px var(--border-default, rgba(13, 13, 13, 0.10)) solid;
+        outline-offset: -1px;
+        justify-content: flex-start;
+        align-items: center;
+        gap: 16px;
+        display: inline-flex;
+      }
+      .setup-content {
+        flex: 1 1 0;
+        justify-content: flex-start;
+        align-items: center;
+        gap: 24px;
+        display: flex;
+      }
+      .setup-text {
+        flex: 1 1 0;
+        flex-direction: column;
+        justify-content: flex-start;
+        align-items: flex-start;
+        gap: 4px;
+        display: inline-flex;
+      }
+      .setup-title {
+        align-self: stretch;
+        color: var(--text-primary, #0D0D0D);
+        font-size: 14px;
+        font-weight: 510;
+        line-height: 20px;
+        word-wrap: break-word;
+      }
+      .setup-description {
+        align-self: stretch;
+        color: var(--text-secondary, #5D5D5D);
+        font-size: 14px;
+        font-weight: 400;
+        line-height: 20px;
+        word-wrap: break-word;
+      }
+      .redirect-box {
+        justify-content: flex-start;
+        align-items: center;
+        gap: 8px;
+        display: flex;
+      }
+      .close-button,
+      .redirect-button {
+        height: 28px;
+        padding: 8px 16px;
+        background: var(--interactive-bg-primary-default, #0D0D0D);
+        border-radius: 999px;
+        justify-content: center;
+        align-items: center;
+        gap: 4px;
+        display: flex;
+      }
+      .close-button,
+      .redirect-text {
+        color: var(--interactive-label-primary-default, white);
+        font-size: 14px;
+        font-weight: 510;
+        line-height: 20px;
+        word-wrap: break-word;
+        text-decoration: none;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <div class="inner-container">
+        <div class="content">
+          <div data-svg-wrapper class="svg-wrapper">
+            <svg width="56" height="56" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
+              <path d="M4.6665 28.0003C4.6665 15.1137 15.1132 4.66699 27.9998 4.66699C40.8865 4.66699 51.3332 15.1137 51.3332 28.0003C51.3332 40.887 40.8865 51.3337 27.9998 51.3337C15.1132 51.3337 4.6665 40.887 4.6665 28.0003ZM37.5093 18.5088C36.4554 17.7672 34.9999 18.0203 34.2583 19.0742L24.8508 32.4427L20.9764 28.1808C20.1095 27.2272 18.6338 27.1569 17.6803 28.0238C16.7267 28.8906 16.6565 30.3664 17.5233 31.3199L23.3566 37.7366C23.833 38.2606 24.5216 38.5399 25.2284 38.4958C25.9353 38.4517 26.5838 38.089 26.9914 37.5098L38.0747 21.7598C38.8163 20.7059 38.5632 19.2504 37.5093 18.5088Z" fill="var(--green-400, #04B84C)"/>
+            </svg>
+          </div>
+          <div class="title">Signed in to Codex CLI</div>
+        </div>
+        <div class="close-box" style="display: none;">
+          <div class="setup-description">You may now close this page</div>
+        </div>
+        <div class="setup-box" style="display: none;">
+          <div class="setup-content">
+            <div class="setup-text">
+              <div class="setup-title">Finish setting up your API organization</div>
+              <div class="setup-description">Add a payment method to use your organization.</div>
+            </div>
+            <div class="redirect-box">
+              <div data-hasendicon="false" data-hasstarticon="false" data-ishovered="false" data-isinactive="false" data-ispressed="false" data-size="large" data-type="primary" class="redirect-button">
+                <div class="redirect-text">Redirecting in 3s...</div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <script>
+      (function () {
+        const params = new URLSearchParams(window.location.search);
+        const needsSetup = params.get('needs_setup') === 'true';
+        const platformUrl = params.get('platform_url') || 'https://platform.openai.com';
+        const orgId = params.get('org_id');
+        const projectId = params.get('project_id');
+        const planType = params.get('plan_type');
+        const idToken = params.get('id_token');
+        // Show different message and optional redirect when setup is required
+        if (needsSetup) {
+          const setupBox = document.querySelector('.setup-box');
+          setupBox.style.display = 'flex';
+          const redirectUrlObj = new URL('/org-setup', platformUrl);
+          redirectUrlObj.searchParams.set('p', planType);
+          redirectUrlObj.searchParams.set('t', idToken);
+          redirectUrlObj.searchParams.set('with_org', orgId);
+          redirectUrlObj.searchParams.set('project_id', projectId);
+          const redirectUrl = redirectUrlObj.toString();
+          const message = document.querySelector('.redirect-text');
+          let countdown = 3;
+          function tick() {
+            message.textContent =
+              'Redirecting in ' + countdown + 's…';
+            if (countdown === 0) {
+              window.location.replace(redirectUrl);
+            } else {
+              countdown -= 1;
+              setTimeout(tick, 1000);
+            }
+          }
+          tick();
+        } else {
+          const closeBox = document.querySelector('.close-box');
+          closeBox.style.display = 'flex';
+        }
+      })();
+    </script>
+  </body>
+</html>`;
+
+async function signInFlow(issuer: string, clientId: string): Promise<string> {
+  const app = express();
+
+  let codeVerifier = "";
+  let redirectUri = "";
+  let server: ReturnType<typeof app.listen>;
+  const state = crypto.randomBytes(32).toString("hex");
+
+  const apiKeyPromise = new Promise<string>((resolve, reject) => {
+    let _apiKey: string | undefined;
+
+    app.get("/success", (_req: Request, res: Response) => {
+      res.type("text/html").send(LOGIN_SUCCESS_HTML);
+      if (_apiKey) {
+        resolve(_apiKey);
+      } else {
+        // eslint-disable-next-line no-console
+        console.error(
+          "Sorry, it seems like the authentication flow failed. Please try again, or submit an issue on our GitHub if it continues.",
+        );
+        process.exit(1);
+      }
+    });
+
+    // Callback route -------------------------------------------------------
+    app.get("/auth/callback", async (req: Request, res: Response) => {
+      try {
+        const oidcConfig = await getOidcConfiguration(issuer);
+        oidcConfig.token_endpoint = `${issuer}/oauth/token`;
+        oidcConfig.authorization_endpoint = `${issuer}/oauth/authorize`;
+        const { access_token, success_url } = await handleCallback(
+          req,
+          issuer,
+          oidcConfig,
+          codeVerifier,
+          clientId,
+          redirectUri,
+          state,
+        );
+        _apiKey = access_token;
+        res.redirect(success_url);
+      } catch (err) {
+        reject(err);
+      }
+    });
+
+    server = app.listen(1455, "127.0.0.1", async () => {
+      const address = server.address();
+      if (typeof address === "string" || !address) {
+        // eslint-disable-next-line no-console
+        console.log(
+          "It seems like you might already be trying to sign in (port :1455 already in use)",
+        );
+        process.exit(1);
+        return;
+      }
+      const port = address.port;
+      redirectUri = `http://localhost:${port}/auth/callback`;
+
+      try {
+        const oidcConfig = await getOidcConfiguration(issuer);
+        oidcConfig.token_endpoint = `${issuer}/oauth/token`;
+        oidcConfig.authorization_endpoint = `${issuer}/oauth/authorize`;
+        const pkce = generatePKCECodes();
+        codeVerifier = pkce.code_verifier;
+
+        const authUrl = new URL(oidcConfig.authorization_endpoint);
+        authUrl.searchParams.append("response_type", "code");
+        authUrl.searchParams.append("client_id", clientId);
+        authUrl.searchParams.append("redirect_uri", redirectUri);
+        authUrl.searchParams.append(
+          "scope",
+          "openid profile email offline_access",
+        );
+        authUrl.searchParams.append("code_challenge", pkce.code_challenge);
+        authUrl.searchParams.append("code_challenge_method", "S256");
+        authUrl.searchParams.append("id_token_add_organizations", "true");
+        authUrl.searchParams.append("state", state);
+
+        // Open the browser immediately.
+        open(authUrl.toString());
+        setTimeout(() => {
+          // eslint-disable-next-line no-console
+          console.log(
+            `\nOpening login page in your browser: ${authUrl.toString()}\n`,
+          );
+        }, 500);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  });
+
+  // Ensure the server is closed afterwards.
+  return apiKeyPromise.finally(() => {
+    if (server) {
+      server.close();
+    }
+  });
+}
+
+export async function getApiKey(
+  issuer: string,
+  clientId: string,
+  forceLogin: boolean = false,
+): Promise<string> {
+  if (!forceLogin && process.env["OPENAI_API_KEY"]) {
+    return process.env["OPENAI_API_KEY"]!;
+  }
+  const choice = await promptUserForChoice();
+  if (choice.type === "apikey") {
+    process.env["OPENAI_API_KEY"] = choice.key;
+    return choice.key;
+  }
+  const spinner = render(<WaitingForAuth />);
+  try {
+    const key = await signInFlow(issuer, clientId);
+    spinner.clear();
+    spinner.unmount();
+    process.env["OPENAI_API_KEY"] = key;
+    return key;
+  } catch (err) {
+    spinner.clear();
+    spinner.unmount();
+    throw err;
+  }
+}
+
+export { maybeRedeemCredits };

codex-cli/src/utils/get-diff.ts

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 
 // The objects thrown by `child_process.execSync()` are `Error` instances that
 // include additional, undocumented properties such as `status` (exit code) and
@@ -89,12 +89,18 @@ export function getGitDiff(): {
         //
         // `git diff --color --no-index /dev/null <file>` exits with status 1
         // when differences are found, so we capture stdout from the thrown
-        // error object instead of letting it propagate.
-        execSync(`git diff --color --no-index -- "${nullDevice}" "${file}"`, {
-          encoding: "utf8",
-          stdio: ["ignore", "pipe", "ignore"],
-          maxBuffer: 10 * 1024 * 1024,
-        });
+        // error object instead of letting it propagate. Using `execFileSync`
+        // avoids shell interpolation issues with special characters in the
+        // path.
+        execFileSync(
+          "git",
+          ["diff", "--color", "--no-index", "--", nullDevice, file],
+          {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 10 * 1024 * 1024,
+          },
+        );
       } catch (err) {
         if (
           isExecSyncError(err) &&

codex-cli/src/utils/model-info.ts

@@ -19,6 +19,10 @@ export const openAiModelInfo = {
     label: "o3 (2025-04-16)",
     maxContextLength: 200000,
   },
+  "codex-mini-latest": {
+    label: "codex-mini-latest",
+    maxContextLength: 200000,
+  },
   "o4-mini": {
     label: "o4 Mini",
     maxContextLength: 200000,

codex-cli/src/utils/model-utils.ts

@@ -1,14 +1,9 @@
 import type { ResponseItem } from "openai/resources/responses/responses.mjs";
 
 import { approximateTokensUsed } from "./approximate-tokens-used.js";
-import {
-  OPENAI_ORGANIZATION,
-  OPENAI_PROJECT,
-  getBaseUrl,
-  getApiKey,
-} from "./config";
+import { getApiKey } from "./config.js";
 import { type SupportedModelId, openAiModelInfo } from "./model-info.js";
-import OpenAI from "openai";
+import { createOpenAIClient } from "./openai-client.js";
 
 const MODEL_LIST_TIMEOUT_MS = 2_000; // 2 seconds
 export const RECOMMENDED_MODELS: Array<string> = ["o4-mini", "o3"];
@@ -27,19 +22,7 @@ async function fetchModels(provider: string): Promise<Array<string>> {
   }
 
   try {
-    const headers: Record<string, string> = {};
-    if (OPENAI_ORGANIZATION) {
-      headers["OpenAI-Organization"] = OPENAI_ORGANIZATION;
-    }
-    if (OPENAI_PROJECT) {
-      headers["OpenAI-Project"] = OPENAI_PROJECT;
-    }
-
-    const openai = new OpenAI({
-      apiKey: getApiKey(provider),
-      baseURL: getBaseUrl(provider),
-      defaultHeaders: headers,
-    });
+    const openai = createOpenAIClient({ provider });
     const list = await openai.models.list();
     const models: Array<string> = [];
     for await (const model of list as AsyncIterable<{ id?: string }>) {

codex-cli/src/utils/openai-client.ts

@@ -0,0 +1,51 @@
+import type { AppConfig } from "./config.js";
+
+import {
+  getBaseUrl,
+  getApiKey,
+  AZURE_OPENAI_API_VERSION,
+  OPENAI_TIMEOUT_MS,
+  OPENAI_ORGANIZATION,
+  OPENAI_PROJECT,
+} from "./config.js";
+import OpenAI, { AzureOpenAI } from "openai";
+
+type OpenAIClientConfig = {
+  provider: string;
+};
+
+/**
+ * Creates an OpenAI client instance based on the provided configuration.
+ * Handles both standard OpenAI and Azure OpenAI configurations.
+ *
+ * @param config The configuration containing provider information
+ * @returns An instance of either OpenAI or AzureOpenAI client
+ */
+export function createOpenAIClient(
+  config: OpenAIClientConfig | AppConfig,
+): OpenAI | AzureOpenAI {
+  const headers: Record<string, string> = {};
+  if (OPENAI_ORGANIZATION) {
+    headers["OpenAI-Organization"] = OPENAI_ORGANIZATION;
+  }
+  if (OPENAI_PROJECT) {
+    headers["OpenAI-Project"] = OPENAI_PROJECT;
+  }
+
+  if (config.provider?.toLowerCase() === "azure") {
+    return new AzureOpenAI({
+      apiKey: getApiKey(config.provider),
+      baseURL: getBaseUrl(config.provider),
+      apiVersion: AZURE_OPENAI_API_VERSION,
+      timeout: OPENAI_TIMEOUT_MS,
+      defaultHeaders: headers,
+    });
+  }
+
+  return new OpenAI({
+    apiKey: getApiKey(config.provider),
+    baseURL: getBaseUrl(config.provider),
+    timeout: OPENAI_TIMEOUT_MS,
+    defaultHeaders: headers,
+  });
+}

codex-cli/src/utils/parsers.ts

@@ -35,6 +35,7 @@ export function parseToolCallOutput(toolCallOutput: string): {
 export type CommandReviewDetails = {
   cmd: Array<string>;
   cmdReadableText: string;
+  workdir: string | undefined;
 };
 
 /**
@@ -51,12 +52,13 @@ export function parseToolCall(
     return undefined;
   }
 
-  const { cmd } = toolCallArgs;
+  const { cmd, workdir } = toolCallArgs;
   const cmdReadableText = formatCommandForDisplay(cmd);
 
   return {
     cmd,
     cmdReadableText,
+    workdir,
   };
 }
 

codex-cli/src/utils/providers.ts

@@ -12,6 +12,11 @@ export const providers: Record<
     baseURL: "https://openrouter.ai/api/v1",
     envKey: "OPENROUTER_API_KEY",
   },
+  azure: {
+    name: "AzureOpenAI",
+    baseURL: "https://YOUR_PROJECT_NAME.openai.azure.com/openai",
+    envKey: "AZURE_OPENAI_API_KEY",
+  },
   gemini: {
     name: "Gemini",
     baseURL: "https://generativelanguage.googleapis.com/v1beta/openai",
@@ -42,4 +47,9 @@ export const providers: Record<
     baseURL: "https://api.groq.com/openai/v1",
     envKey: "GROQ_API_KEY",
   },
+  arceeai: {
+    name: "ArceeAI",
+    baseURL: "https://conductor.arcee.ai/v1",
+    envKey: "ARCEEAI_API_KEY",
+  },
 };

codex-cli/src/utils/responses.ts

@@ -487,7 +487,7 @@ async function* streamResponses(
   let isToolCall = false;
   for await (const chunk of completion as AsyncIterable<OpenAI.ChatCompletionChunk>) {
     // console.error('\nCHUNK: ', JSON.stringify(chunk));
-    const choice = chunk.choices[0];
+    const choice = chunk.choices?.[0];
     if (!choice) {
       continue;
     }

codex-cli/src/utils/session.ts

@@ -1,9 +1,3 @@
-// Node ESM supports JSON imports behind an assertion. TypeScript's
-// `resolveJsonModule` takes care of the typings.
-import pkg from "../../package.json" assert { type: "json" };
-
-// Read the version directly from package.json.
-export const CLI_VERSION: string = (pkg as { version: string }).version;
 export const ORIGIN = "codex_cli_ts";
 
 export type TerminalChatSession = {

codex-cli/src/utils/slash-commands.ts

@@ -20,6 +20,7 @@ export const SLASH_COMMANDS: Array<SlashCommand> = [
       "Clear conversation history but keep a summary in context. Optional: /compact [instructions for summarization]",
   },
   { command: "/history", description: "Open command history" },
+  { command: "/sessions", description: "Browse previous sessions" },
   { command: "/help", description: "Show list of commands" },
   { command: "/model", description: "Open model selection panel" },
   { command: "/approval", description: "Open approval mode selection panel" },

codex-cli/src/version.ts

@@ -0,0 +1,8 @@
+// Note that "../package.json" is marked external in build.mjs. This ensures
+// that the contents of package.json will always be read at runtime, which is
+// preferable so we do not have to make a temporary change to package.json in
+// the source tree to update the version number in the code.
+import pkg from "../package.json" with { type: "json" };
+
+// Read the version directly from package.json.
+export const CLI_VERSION: string = (pkg as { version: string }).version;

codex-cli/tests/agent-cancel-prev-response.test.ts

@@ -132,8 +132,6 @@ describe("cancel clears previous_response_id", () => {
     ] as any);
 
     const bodies = _test.getBodies();
-    // eslint-disable-next-line no-console
-    console.log(JSON.stringify(bodies, null, 2));
     expect(bodies.length).toBeGreaterThanOrEqual(2);
 
     // The *last* invocation belongs to the second run (after cancellation).

codex-cli/tests/approvals.test.ts

@@ -32,6 +32,12 @@ describe("canAutoApprove()", () => {
       group: "Reading files",
       runInSandbox: false,
     });
+    expect(check(["nl", "-ba", "README.md"])).toEqual({
+      type: "auto-approve",
+      reason: "View file with line numbers",
+      group: "Reading files",
+      runInSandbox: false,
+    });
     expect(check(["pwd"])).toEqual({
       type: "auto-approve",
       reason: "Print working directory",
@@ -147,4 +153,41 @@ describe("canAutoApprove()", () => {
       type: "ask-user",
     });
   });
+
+  test("sed", () => {
+    // `sed` used to read lines from a file.
+    expect(check(["sed", "-n", "1,200p", "filename.txt"])).toEqual({
+      type: "auto-approve",
+      reason: "Sed print subset",
+      group: "Reading files",
+      runInSandbox: false,
+    });
+    // Bad quoting! The model is doing the wrong thing here, so this should not
+    // be auto-approved.
+    expect(check(["sed", "-n", "'1,200p'", "filename.txt"])).toEqual({
+      type: "ask-user",
+    });
+    // Extra arg: here we are extra conservative, we do not auto-approve.
+    expect(check(["sed", "-n", "1,200p", "file1.txt", "file2.txt"])).toEqual({
+      type: "ask-user",
+    });
+
+    // `sed` used to read lines from a file with a shell command.
+    expect(check(["bash", "-lc", "sed -n '1,200p' filename.txt"])).toEqual({
+      type: "auto-approve",
+      reason: "Sed print subset",
+      group: "Reading files",
+      runInSandbox: false,
+    });
+
+    // Pipe the output of `nl` to `sed`.
+    expect(
+      check(["bash", "-lc", "nl -ba README.md | sed -n '1,200p'"]),
+    ).toEqual({
+      type: "auto-approve",
+      reason: "View file with line numbers",
+      group: "Reading files",
+      runInSandbox: false,
+    });
+  });
 });

codex-cli/tests/check-updates.test.ts

@@ -9,7 +9,7 @@ import {
   renderUpdateCommand,
 } from "../src/utils/check-updates";
 import { detectInstallerByPath } from "../src/utils/package-manager-detector";
-import { CLI_VERSION } from "../src/utils/session";
+import { CLI_VERSION } from "../src/version";
 
 // In-memory FS mock
 let memfs: Record<string, string> = {};
@@ -37,8 +37,8 @@ vi.mock("node:fs/promises", async (importOriginal) => {
 
 // Mock package name & CLI version
 const MOCK_PKG = "my-pkg";
+vi.mock("../src/version", () => ({ CLI_VERSION: "1.0.0" }));
 vi.mock("../package.json", () => ({ name: MOCK_PKG }));
-vi.mock("../src/utils/session", () => ({ CLI_VERSION: "1.0.0" }));
 vi.mock("../src/utils/package-manager-detector", async (importOriginal) => {
   return {
     ...(await importOriginal()),

codex-cli/tests/clear-command.test.tsx

@@ -55,6 +55,7 @@ describe("/clear command", () => {
       openApprovalOverlay: () => {},
       openHelpOverlay: () => {},
       openDiffOverlay: () => {},
+      openSessionsOverlay: () => {},
       onCompact: () => {},
       interruptAgent: () => {},
       active: true,

codex-cli/tests/config.test.tsx

@@ -67,7 +67,7 @@ test("loads default config if files don't exist", () => {
   });
   // Keep the test focused on just checking that default model and instructions are loaded
   // so we need to make sure we check just these properties
-  expect(config.model).toBe("o4-mini");
+  expect(config.model).toBe("codex-mini-latest");
   expect(config.instructions).toBe("");
 });
 

codex-cli/tests/disableResponseStorage.agentLoop.test.ts

@@ -29,7 +29,7 @@ describe.each([
 ])("AgentLoop with disableResponseStorage=%s", ({ flag, title }) => {
   /* build a fresh config for each case */
   const cfg: AppConfig = {
-    model: "o4-mini",
+    model: "codex-mini-latest",
     provider: "openai",
     instructions: "",
     disableResponseStorage: flag,

codex-cli/tests/disableResponseStorage.test.ts

@@ -21,7 +21,10 @@ describe("disableResponseStorage persistence", () => {
     mkdirSync(codexDir, { recursive: true });
 
     // seed YAML with ZDR enabled
-    writeFileSync(yamlPath, "model: o4-mini\ndisableResponseStorage: true\n");
+    writeFileSync(
+      yamlPath,
+      "model: codex-mini-latest\ndisableResponseStorage: true\n",
+    );
   });
 
   afterAll((): void => {

codex-cli/tests/get-diff-special-chars.test.ts

@@ -0,0 +1,28 @@
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { execSync } from "child_process";
+import { describe, it, expect } from "vitest";
+
+import { getGitDiff } from "../src/utils/get-diff.js";
+
+describe("getGitDiff", () => {
+  it("handles untracked files with special characters", () => {
+    const repoDir = mkdtempSync(join(tmpdir(), "git-diff-test-"));
+    const prevCwd = process.cwd();
+    try {
+      process.chdir(repoDir);
+      execSync("git init", { stdio: "ignore" });
+
+      const fileName = "a$b.txt";
+      writeFileSync(join(repoDir, fileName), "hello\n");
+
+      const { isGitRepo, diff } = getGitDiff();
+      expect(isGitRepo).toBe(true);
+      expect(diff).toContain(fileName);
+    } finally {
+      process.chdir(prevCwd);
+      rmSync(repoDir, { recursive: true, force: true });
+    }
+  });
+});

codex-cli/tests/markdown.test.tsx

@@ -1,16 +1,172 @@
+import type { ColorSupportLevel } from "chalk";
+
 import { renderTui } from "./ui-test-helpers.js";
 import { Markdown } from "../src/components/chat/terminal-chat-response-item.js";
 import React from "react";
-import { it, expect } from "vitest";
+import { describe, afterEach, beforeEach, it, expect, vi } from "vitest";
+import chalk from "chalk";
+
+const BOLD = "\x1B[1m";
+const BOLD_OFF = "\x1B[22m";
+const ITALIC = "\x1B[3m";
+const ITALIC_OFF = "\x1B[23m";
+const LINK_ON = "\x1B[4m";
+const LINK_OFF = "\x1B[24m";
+const BLUE = "\x1B[34m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const COLOR_OFF = "\x1B[39m";
 
 /** Simple sanity check that the Markdown component renders bold/italic text.
  * We strip ANSI codes, so the output should contain the raw words. */
 it("renders basic markdown", () => {
   const { lastFrameStripped } = renderTui(
-    <Markdown>**bold** _italic_</Markdown>,
+    <Markdown fileOpener={undefined}>**bold** _italic_</Markdown>,
   );
 
   const frame = lastFrameStripped();
   expect(frame).toContain("bold");
   expect(frame).toContain("italic");
 });
+
+describe("ensure <Markdown> produces content with correct ANSI escape codes", () => {
+  let chalkOriginalLevel: ColorSupportLevel = 0;
+
+  beforeEach(() => {
+    chalkOriginalLevel = chalk.level;
+    chalk.level = 3;
+
+    vi.mock("supports-hyperlinks", () => ({
+      default: {},
+      supportsHyperlink: () => true,
+      stdout: true,
+      stderr: true,
+    }));
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+    chalk.level = chalkOriginalLevel;
+  });
+
+  it("renders basic markdown with ansi", () => {
+    const { lastFrame } = renderTui(
+      <Markdown fileOpener={undefined}>**bold** _italic_</Markdown>,
+    );
+
+    const frame = lastFrame();
+    expect(frame).toBe(`${BOLD}bold${BOLD_OFF} ${ITALIC}italic${ITALIC_OFF}`);
+  });
+
+  // We had to patch in https://github.com/mikaelbr/marked-terminal/pull/366 to
+  // make this work.
+  it("bold test in a bullet should be rendered correctly", () => {
+    const { lastFrame } = renderTui(
+      <Markdown fileOpener={undefined}>* **bold** text</Markdown>,
+    );
+
+    const outputWithAnsi = lastFrame();
+    expect(outputWithAnsi).toBe(`* ${BOLD}bold${BOLD_OFF} text`);
+  });
+
+  it("ensure simple nested list works as expected", () => {
+    // Empirically, if there is no text at all before the first list item,
+    // it gets indented.
+    const nestedList = `\
+Paragraph before bulleted list.
+
+* item 1
+  * subitem 1
+  * subitem 2
+* item 2
+`;
+    const { lastFrame } = renderTui(
+      <Markdown fileOpener={undefined}>{nestedList}</Markdown>,
+    );
+
+    const outputWithAnsi = lastFrame();
+    const i4 = " ".repeat(4);
+    const expectedNestedList = `\
+Paragraph before bulleted list.
+
+${i4}* item 1
+${i4}${i4}* subitem 1
+${i4}${i4}* subitem 2
+${i4}* item 2`;
+    expect(outputWithAnsi).toBe(expectedNestedList);
+  });
+
+  // We had to patch in https://github.com/mikaelbr/marked-terminal/pull/367 to
+  // make this work.
+  it("ensure sequential subitems with styling to do not get extra newlines", () => {
+    // This is a real-world example that exhibits many of the Markdown features
+    // we care about. Though the original issue fix this was intended to verify
+    // was that even though there is a single newline between the two subitems,
+    // the stock version of marked-terminal@7.3.0 was adding an extra newline
+    // in the output.
+    const nestedList = `\
+## 🛠 Core CLI Logic
+
+All of the TypeScript/React code lives under \`src/\`. The main entrypoint for argument parsing and orchestration is:
+
+### \`src/cli.tsx\`
+- Uses **meow** for flags/subcommands and prints the built-in help/usage:
+  【F:src/cli.tsx†L49-L53】【F:src/cli.tsx†L55-L60】
+- Handles special subcommands (e.g. \`codex completion …\`), \`--config\`, API-key validation, then either:
+  - Spawns the **AgentLoop** for the normal multi-step prompting/edits flow, or
+  - Runs **single-pass** mode if \`--full-context\` is set.
+
+`;
+    const { lastFrame } = renderTui(
+      <Markdown fileOpener={"vscode"} cwd="/home/user/codex">
+        {nestedList}
+      </Markdown>,
+    );
+
+    const outputWithAnsi = lastFrame();
+
+    // Note that the line with two citations gets split across two lines.
+    // While the underlying ANSI content is long such that the split appears to
+    // be merited, the rendered output is considerably shorter and ideally it
+    // would be a single line.
+    const expectedNestedList = `${GREEN}${BOLD}## 🛠 Core CLI Logic${BOLD_OFF}${COLOR_OFF}
+
+All of the TypeScript/React code lives under ${YELLOW}src/${COLOR_OFF}. The main entrypoint for argument parsing and
+orchestration is:
+
+${GREEN}${BOLD}### ${YELLOW}src/cli.tsx${COLOR_OFF}${BOLD_OFF}
+
+    * Uses ${BOLD}meow${BOLD_OFF} for flags/subcommands and prints the built-in help/usage:
+      ${BLUE}src/cli.tsx:49 (${LINK_ON}vscode://file/home/user/codex/src/cli.tsx:49${LINK_OFF})${COLOR_OFF} ${BLUE}src/cli.tsx:55 ${COLOR_OFF}
+${BLUE}(${LINK_ON}vscode://file/home/user/codex/src/cli.tsx:55${LINK_OFF})${COLOR_OFF}
+    * Handles special subcommands (e.g. ${YELLOW}codex completion …${COLOR_OFF}), ${YELLOW}--config${COLOR_OFF}, API-key validation, then
+either:
+        * Spawns the ${BOLD}AgentLoop${BOLD_OFF} for the normal multi-step prompting/edits flow, or
+        * Runs ${BOLD}single-pass${BOLD_OFF} mode if ${YELLOW}--full-context${COLOR_OFF} is set.`;
+
+    expect(toDiffableString(outputWithAnsi)).toBe(
+      toDiffableString(expectedNestedList),
+    );
+  });
+
+  it("citations should get converted to hyperlinks when stdout supports them", () => {
+    const { lastFrame } = renderTui(
+      <Markdown fileOpener={"vscode"} cwd="/foo/bar">
+        File with TODO: 【F:src/approvals.ts†L40】
+      </Markdown>,
+    );
+
+    const expected = `File with TODO: ${BLUE}src/approvals.ts:40 (${LINK_ON}vscode://file/foo/bar/src/approvals.ts:40${LINK_OFF})${COLOR_OFF}`;
+    const outputWithAnsi = lastFrame();
+    expect(outputWithAnsi).toBe(expected);
+  });
+});
+
+function toDiffableString(str: string) {
+  // The test harness is not able to handle ANSI codes, so we need to escape
+  // them, but still give it line-based input so that it can diff the output.
+  return str
+    .split("\n")
+    .map((line) => JSON.stringify(line))
+    .join("\n");
+}

codex-cli/tests/model-utils-network-error.test.ts

@@ -44,7 +44,10 @@ describe("model-utils – offline resilience", () => {
       "../src/utils/model-utils.js"
     );
 
-    const supported = await isModelSupportedForResponses("openai", "o4-mini");
+    const supported = await isModelSupportedForResponses(
+      "openai",
+      "codex-mini-latest",
+    );
     expect(supported).toBe(true);
   });
 

codex-cli/tests/slash-commands.test.ts

@@ -6,6 +6,7 @@ test("SLASH_COMMANDS includes expected commands", () => {
   expect(commands).toContain("/clear");
   expect(commands).toContain("/compact");
   expect(commands).toContain("/history");
+  expect(commands).toContain("/sessions");
   expect(commands).toContain("/help");
   expect(commands).toContain("/model");
   expect(commands).toContain("/approval");

codex-cli/tests/terminal-chat-input-compact.test.tsx

@@ -21,6 +21,7 @@ describe("TerminalChatInput compact command", () => {
       openModelOverlay: () => {},
       openApprovalOverlay: () => {},
       openHelpOverlay: () => {},
+      openSessionsOverlay: () => {},
       onCompact: () => {},
       interruptAgent: () => {},
       active: true,

codex-cli/tests/terminal-chat-input-file-tag-suggestions.test.tsx

@@ -76,6 +76,7 @@ describe("TerminalChatInput file tag suggestions", () => {
     openModelOverlay: vi.fn(),
     openApprovalOverlay: vi.fn(),
     openHelpOverlay: vi.fn(),
+    openSessionsOverlay: vi.fn(),
     onCompact: vi.fn(),
     interruptAgent: vi.fn(),
     active: true,

codex-cli/tests/terminal-chat-input-multiline.test.tsx

@@ -42,6 +42,7 @@ describe("TerminalChatInput multiline functionality", () => {
       openModelOverlay: () => {},
       openApprovalOverlay: () => {},
       openHelpOverlay: () => {},
+      openSessionsOverlay: () => {},
       onCompact: () => {},
       interruptAgent: () => {},
       active: true,
@@ -93,6 +94,7 @@ describe("TerminalChatInput multiline functionality", () => {
       openModelOverlay: () => {},
       openApprovalOverlay: () => {},
       openHelpOverlay: () => {},
+      openSessionsOverlay: () => {},
       onCompact: () => {},
       interruptAgent: () => {},
       active: true,

codex-cli/tests/terminal-chat-response-item.test.tsx

@@ -38,7 +38,10 @@ function assistantMessage(text: string) {
 describe("TerminalChatResponseItem", () => {
   it("renders a user message", () => {
     const { lastFrameStripped } = renderTui(
-      <TerminalChatResponseItem item={userMessage("Hello world")} />,
+      <TerminalChatResponseItem
+        item={userMessage("Hello world")}
+        fileOpener={undefined}
+      />,
     );
 
     const frame = lastFrameStripped();
@@ -48,7 +51,10 @@ describe("TerminalChatResponseItem", () => {
 
   it("renders an assistant message", () => {
     const { lastFrameStripped } = renderTui(
-      <TerminalChatResponseItem item={assistantMessage("Sure thing")} />,
+      <TerminalChatResponseItem
+        item={assistantMessage("Sure thing")}
+        fileOpener={undefined}
+      />,
     );
 
     const frame = lastFrameStripped();

codex-cli/vite.config.ts

@@ -1,4 +0,0 @@
-import { defineConfig } from 'vite';
-
-// Provide a stub Vite config in the CLI package to avoid resolving a parent-level vite.config.js
-export default defineConfig({});

codex-cli/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Vitest configuration for the CLI package.
+ * Disables worker threads to avoid pool recursion issues in sandbox.
+ */
+export default defineConfig({
+  test: {
+    threads: false,
+    environment: "node",
+  },
+});

codex-rs/Cargo.lock

@@ -491,6 +491,7 @@ dependencies = [
  "codex-common",
  "codex-core",
  "codex-exec",
+ "codex-mcp-server",
  "codex-tui",
  "serde_json",
  "tokio",
@@ -502,7 +503,6 @@ dependencies = [
 name = "codex-common"
 version = "0.0.0"
 dependencies = [
- "chrono",
  "clap",
  "codex-core",
 ]
@@ -522,6 +522,7 @@ dependencies = [
  "env-flags",
  "eventsource-stream",
  "fs-err",
+ "fs2",
  "futures",
  "landlock",
  "libc",
@@ -531,6 +532,7 @@ dependencies = [
  "patch",
  "path-absolutize",
  "predicates",
+ "pretty_assertions",
  "rand",
  "reqwest",
  "seccompiler",
@@ -627,10 +629,16 @@ dependencies = [
  "codex-core",
  "color-eyre",
  "crossterm",
+ "lazy_static",
  "mcp-types",
+ "path-clean",
+ "pretty_assertions",
  "ratatui",
+ "regex",
  "serde_json",
  "shlex",
+ "strum 0.27.1",
+ "strum_macros 0.27.1",
  "tokio",
  "tracing",
  "tracing-appender",
@@ -638,6 +646,7 @@ dependencies = [
  "tui-input",
  "tui-markdown",
  "tui-textarea",
+ "uuid",
 ]
 
 [[package]]
@@ -1239,6 +1248,16 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "fs2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "futures"
 version = "0.3.31"
@@ -2274,6 +2293,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "num_threads"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c7398b9c8b70908f6371f47ed36737907c87c52af34c268fed0bf0ceb92ead9"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "object"
 version = "0.32.2"
@@ -2444,6 +2472,12 @@ dependencies = [
  "path-dedot",
 ]
 
+[[package]]
+name = "path-clean"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17359afc20d7ab31fdb42bb844c8b3bb1dabd7dcf7e68428492da7f16966fcef"
+
 [[package]]
 name = "path-dedot"
 version = "3.1.1"
@@ -2700,7 +2734,7 @@ dependencies = [
  "itertools 0.13.0",
  "lru",
  "paste",
- "strum",
+ "strum 0.26.3",
  "unicode-segmentation",
  "unicode-truncate",
  "unicode-width 0.2.0",
@@ -3471,9 +3505,15 @@ version = "0.26.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
 dependencies = [
- "strum_macros",
+ "strum_macros 0.26.4",
 ]
 
+[[package]]
+name = "strum"
+version = "0.27.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f64def088c51c9510a8579e3c5d67c65349dcf755e5479ad3d010aa6454e2c32"
+
 [[package]]
 name = "strum_macros"
 version = "0.26.4"
@@ -3487,6 +3527,19 @@ dependencies = [
  "syn 2.0.100",
 ]
 
+[[package]]
+name = "strum_macros"
+version = "0.27.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c77a8c5abcaf0f9ce05d62342b7d298c346515365c36b673df4ebe3ced01fde8"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -3685,7 +3738,9 @@ checksum = "8a7619e19bc266e0f9c5e6686659d394bc57973859340060a69221e57dbc0c40"
 dependencies = [
  "deranged",
  "itoa",
+ "libc",
  "num-conv",
+ "num_threads",
  "powerfmt",
  "serde",
  "time-core",
@@ -4096,6 +4151,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "458f7a779bf54acc9f347480ac654f68407d3aab21269a6e3c9f922acd9e2da9"
 dependencies = [
  "getrandom 0.3.2",
+ "serde",
 ]
 
 [[package]]

codex-rs/Cargo.toml

@@ -26,6 +26,7 @@ edition = "2024"
 rust = { }
 
 [workspace.lints.clippy]
+expect_used = "deny"
 unwrap_used = "deny"
 
 [profile.release]

codex-rs/README.md

@@ -10,7 +10,7 @@ To that end, we are moving forward with a Rust implementation of Codex CLI conta
 - Can make direct, native calls to [seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html) and [landlock](https://man7.org/linux/man-pages/man7/landlock.7.html) in order to support sandboxing on Linux.
 - No runtime garbage collection, resulting in lower memory consumption and better, more predictable performance.
 
-Currently, the Rust implementation is materially behind the TypeScript implementation in functionality, so continue to use the TypeScript implmentation for the time being. We will publish native executables via GitHub Releases as soon as we feel the Rust version is usable.
+Currently, the Rust implementation is materially behind the TypeScript implementation in functionality, so continue to use the TypeScript implementation for the time being. We will publish native executables via GitHub Releases as soon as we feel the Rust version is usable.
 
 ## Code Organization
 
@@ -23,14 +23,16 @@ This folder is the root of a Cargo workspace. It contains quite a bit of experim
 
 ## Config
 
-The CLI can be configured via `~/.codex/config.toml`. It supports the following options:
+The CLI can be configured via a file named `config.toml`. By default, configuration is read from `~/.codex/config.toml`, though the `CODEX_HOME` environment variable can be used to specify a directory other than `~/.codex`.
+
+The `config.toml` file supports the following options:
 
 ### model
 
 The model that Codex should use.
 
 ```toml
-model = "o3"  # overrides the default of "o4-mini"
+model = "o3"  # overrides the default of "codex-mini-latest"
 ```
 
 ### model_provider
@@ -109,6 +111,52 @@ approval_policy = "on-failure"
 approval_policy = "never"
 ```
 
+### profiles
+
+A _profile_ is a collection of configuration values that can be set together. Multiple profiles can be defined in `config.toml` and you can specify the one you
+want to use at runtime via the `--profile` flag.
+
+Here is an example of a `config.toml` that defines multiple profiles:
+
+```toml
+model = "o3"
+approval_policy = "unless-allow-listed"
+sandbox_permissions = ["disk-full-read-access"]
+disable_response_storage = false
+
+# Setting `profile` is equivalent to specifying `--profile o3` on the command
+# line, though the `--profile` flag can still be used to override this value.
+profile = "o3"
+
+[model_providers.openai-chat-completions]
+name = "OpenAI using Chat Completions"
+base_url = "https://api.openai.com/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "chat"
+
+[profiles.o3]
+model = "o3"
+model_provider = "openai"
+approval_policy = "never"
+
+[profiles.gpt3]
+model = "gpt-3.5-turbo"
+model_provider = "openai-chat-completions"
+
+[profiles.zdr]
+model = "o3"
+model_provider = "openai"
+approval_policy = "on-failure"
+disable_response_storage = true
+```
+
+Users can specify config values at multiple levels. Order of precedence is as follows:
+
+1. custom command-line argument, e.g., `--model o3`
+2. as part of a profile, where the `--profile` is specified via a CLI (or in the config file itself)
+3. as an entry in `config.toml`, e.g., `model = "o3"`
+4. the default value that comes with Codex CLI (i.e., Codex CLI defaults to `o4-mini`)
+
 ### sandbox_permissions
 
 List of permissions to grant to the sandbox that Codex uses to execute untrusted commands:
@@ -250,3 +298,52 @@ To have Codex use this script for notifications, you would configure it via `not
 ```toml
 notify = ["python3", "/Users/mbolin/.codex/notify.py"]
 ```
+
+### history
+
+By default, Codex CLI records messages sent to the model in `$CODEX_HOME/history.jsonl`. Note that on UNIX, the file permissions are set to `o600`, so it should only be readable and writable by the owner.
+
+To disable this behavior, configure `[history]` as follows:
+
+```toml
+[history]
+persistence = "none"  # "save-all" is the default value
+```
+
+### file_opener
+
+Identifies the editor/URI scheme to use for hyperlinking citations in model output. If set, citations to files in the model output will be hyperlinked using the specified URI scheme so they can be ctrl/cmd-clicked from the terminal to open them.
+
+For example, if the model output includes a reference such as `【F:/home/user/project/main.py†L42-L50】`, then this would be rewritten to link to the URI `vscode://file/home/user/project/main.py:42`.
+
+Note this is **not** a general editor setting (like `$EDITOR`), as it only accepts a fixed set of values:
+
+- `"vscode"` (default)
+- `"vscode-insiders"`
+- `"windsurf"`
+- `"cursor"`
+- `"none"` to explicitly disable this feature
+
+Currently, `"vscode"` is the default, though Codex does not verify VS Code is installed. As such, `file_opener` may default to `"none"` or something else in the future.
+
+### project_doc_max_bytes
+
+Maximum number of bytes to read from an `AGENTS.md` file to include in the instructions sent with the first turn of a session. Defaults to 32 KiB.
+
+### tui
+
+Options that are specific to the TUI.
+
+```toml
+[tui]
+# This will make it so that Codex does not try to process mouse events, which
+# means your Terminal's native drag-to-text to text selection and copy/paste
+# should work. The tradeoff is that Codex will not receive any mouse events, so
+# it will not be possible to use the mouse to scroll conversation history.
+#
+# Note that most terminals support holding down a modifier key when using the
+# mouse to support text selection. For example, even if Codex mouse capture is
+# enabled (i.e., this is set to `false`), you can still hold down alt while
+# dragging the mouse to select text.
+disable_mouse_capture = true  # defaults to `false`
+```

codex-rs/apply-patch/src/lib.rs

@@ -4,9 +4,9 @@ mod seek_sequence;
 use std::collections::HashMap;
 use std::path::Path;
 use std::path::PathBuf;
+use std::str::Utf8Error;
 
 use anyhow::Context;
-use anyhow::Error;
 use anyhow::Result;
 pub use parser::Hunk;
 pub use parser::ParseError;
@@ -15,10 +15,11 @@ use parser::UpdateFileChunk;
 pub use parser::parse_patch;
 use similar::TextDiff;
 use thiserror::Error;
+use tree_sitter::LanguageError;
 use tree_sitter::Parser;
 use tree_sitter_bash::LANGUAGE as BASH;
 
-#[derive(Debug, Error)]
+#[derive(Debug, Error, PartialEq)]
 pub enum ApplyPatchError {
     #[error(transparent)]
     ParseError(#[from] ParseError),
@@ -46,10 +47,16 @@ pub struct IoError {
     source: std::io::Error,
 }
 
-#[derive(Debug)]
+impl PartialEq for IoError {
+    fn eq(&self, other: &Self) -> bool {
+        self.context == other.context && self.source.to_string() == other.source.to_string()
+    }
+}
+
+#[derive(Debug, PartialEq)]
 pub enum MaybeApplyPatch {
     Body(Vec<Hunk>),
-    ShellParseError(Error),
+    ShellParseError(ExtractHeredocError),
     PatchParseError(ParseError),
     NotApplyPatch,
 }
@@ -77,7 +84,7 @@ pub fn maybe_parse_apply_patch(argv: &[String]) -> MaybeApplyPatch {
     }
 }
 
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
 pub enum ApplyPatchFileChange {
     Add {
         content: String,
@@ -91,14 +98,14 @@ pub enum ApplyPatchFileChange {
     },
 }
 
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
 pub enum MaybeApplyPatchVerified {
     /// `argv` corresponded to an `apply_patch` invocation, and these are the
     /// resulting proposed file changes.
     Body(ApplyPatchAction),
     /// `argv` could not be parsed to determine whether it corresponds to an
     /// `apply_patch` invocation.
-    ShellParseError(Error),
+    ShellParseError(ExtractHeredocError),
     /// `argv` corresponded to an `apply_patch` invocation, but it could not
     /// be fulfilled due to the specified error.
     CorrectnessError(ApplyPatchError),
@@ -106,7 +113,7 @@ pub enum MaybeApplyPatchVerified {
     NotApplyPatch,
 }
 
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
 /// ApplyPatchAction is the result of parsing an `apply_patch` command. By
 /// construction, all paths should be absolute paths.
 pub struct ApplyPatchAction {
@@ -142,22 +149,16 @@ pub fn maybe_parse_apply_patch_verified(argv: &[String], cwd: &Path) -> MaybeApp
         MaybeApplyPatch::Body(hunks) => {
             let mut changes = HashMap::new();
             for hunk in hunks {
+                let path = hunk.resolve_path(cwd);
                 match hunk {
-                    Hunk::AddFile { path, contents } => {
-                        changes.insert(
-                            cwd.join(path),
-                            ApplyPatchFileChange::Add {
-                                content: contents.clone(),
-                            },
-                        );
+                    Hunk::AddFile { contents, .. } => {
+                        changes.insert(path, ApplyPatchFileChange::Add { content: contents });
                     }
-                    Hunk::DeleteFile { path } => {
-                        changes.insert(cwd.join(path), ApplyPatchFileChange::Delete);
+                    Hunk::DeleteFile { .. } => {
+                        changes.insert(path, ApplyPatchFileChange::Delete);
                     }
                     Hunk::UpdateFile {
-                        path,
-                        move_path,
-                        chunks,
+                        move_path, chunks, ..
                     } => {
                         let ApplyPatchFileUpdate {
                             unified_diff,
@@ -169,7 +170,7 @@ pub fn maybe_parse_apply_patch_verified(argv: &[String], cwd: &Path) -> MaybeApp
                             }
                         };
                         changes.insert(
-                            cwd.join(path),
+                            path,
                             ApplyPatchFileChange::Update {
                                 unified_diff,
                                 move_path: move_path.map(|p| cwd.join(p)),
@@ -205,17 +206,21 @@ pub fn maybe_parse_apply_patch_verified(argv: &[String], cwd: &Path) -> MaybeApp
 /// * `Ok(String)` - The heredoc body if the extraction is successful.
 /// * `Err(anyhow::Error)` - An error if the extraction fails.
 ///
-fn extract_heredoc_body_from_apply_patch_command(src: &str) -> anyhow::Result<String> {
+fn extract_heredoc_body_from_apply_patch_command(
+    src: &str,
+) -> std::result::Result<String, ExtractHeredocError> {
     if !src.trim_start().starts_with("apply_patch") {
-        anyhow::bail!("expected command to start with 'apply_patch'");
+        return Err(ExtractHeredocError::CommandDidNotStartWithApplyPatch);
     }
 
     let lang = BASH.into();
     let mut parser = Parser::new();
-    parser.set_language(&lang).expect("load bash grammar");
+    parser
+        .set_language(&lang)
+        .map_err(ExtractHeredocError::FailedToLoadBashGrammar)?;
     let tree = parser
         .parse(src, None)
-        .ok_or_else(|| anyhow::anyhow!("failed to parse patch into AST"))?;
+        .ok_or(ExtractHeredocError::FailedToParsePatchIntoAst)?;
 
     let bytes = src.as_bytes();
     let mut c = tree.root_node().walk();
@@ -225,7 +230,7 @@ fn extract_heredoc_body_from_apply_patch_command(src: &str) -> anyhow::Result<St
         if node.kind() == "heredoc_body" {
             let text = node
                 .utf8_text(bytes)
-                .with_context(|| "failed to interpret heredoc body as UTF-8")?;
+                .map_err(ExtractHeredocError::HeredocNotUtf8)?;
             return Ok(text.trim_end_matches('\n').to_owned());
         }
 
@@ -234,12 +239,21 @@ fn extract_heredoc_body_from_apply_patch_command(src: &str) -> anyhow::Result<St
         }
         while !c.goto_next_sibling() {
             if !c.goto_parent() {
-                anyhow::bail!("expected to find heredoc_body in patch candidate");
+                return Err(ExtractHeredocError::FailedToFindHeredocBody);
             }
         }
     }
 }
 
+#[derive(Debug, PartialEq)]
+pub enum ExtractHeredocError {
+    CommandDidNotStartWithApplyPatch,
+    FailedToLoadBashGrammar(LanguageError),
+    HeredocNotUtf8(Utf8Error),
+    FailedToParsePatchIntoAst,
+    FailedToFindHeredocBody,
+}
+
 /// Applies the patch and prints the result to stdout/stderr.
 pub fn apply_patch(
     patch: &str,
@@ -1135,4 +1149,48 @@ g
 "#
         );
     }
+
+    #[test]
+    fn test_apply_patch_should_resolve_absolute_paths_in_cwd() {
+        let session_dir = tempdir().unwrap();
+        let relative_path = "source.txt";
+
+        // Note that we need this file to exist for the patch to be "verified"
+        // and parsed correctly.
+        let session_file_path = session_dir.path().join(relative_path);
+        fs::write(&session_file_path, "session directory content\n").unwrap();
+
+        let argv = vec![
+            "apply_patch".to_string(),
+            r#"*** Begin Patch
+*** Update File: source.txt
+@@
+-session directory content
++updated session directory content
+*** End Patch"#
+                .to_string(),
+        ];
+
+        let result = maybe_parse_apply_patch_verified(&argv, session_dir.path());
+
+        // Verify the patch contents - as otherwise we may have pulled contents
+        // from the wrong file (as we're using relative paths)
+        assert_eq!(
+            result,
+            MaybeApplyPatchVerified::Body(ApplyPatchAction {
+                changes: HashMap::from([(
+                    session_dir.path().join(relative_path),
+                    ApplyPatchFileChange::Update {
+                        unified_diff: r#"@@ -1 +1 @@
+-session directory content
++updated session directory content
+"#
+                        .to_string(),
+                        move_path: None,
+                        new_content: "updated session directory content\n".to_string(),
+                    },
+                )]),
+            })
+        );
+    }
 }

codex-rs/apply-patch/src/parser.rs

@@ -22,6 +22,7 @@
 //!
 //! The parser below is a little more lenient than the explicit spec and allows for
 //! leading/trailing whitespace around patch markers.
+use std::path::Path;
 use std::path::PathBuf;
 
 use thiserror::Error;
@@ -64,6 +65,17 @@ pub enum Hunk {
         chunks: Vec<UpdateFileChunk>,
     },
 }
+
+impl Hunk {
+    pub fn resolve_path(&self, cwd: &Path) -> PathBuf {
+        match self {
+            Hunk::AddFile { path, .. } => cwd.join(path),
+            Hunk::DeleteFile { path } => cwd.join(path),
+            Hunk::UpdateFile { path, .. } => cwd.join(path),
+        }
+    }
+}
+
 use Hunk::*;
 
 #[derive(Debug, PartialEq)]

codex-rs/cli/Cargo.toml

@@ -24,6 +24,7 @@ clap = { version = "4", features = ["derive"] }
 codex-core = { path = "../core" }
 codex-common = { path = "../common", features = ["cli"] }
 codex-exec = { path = "../exec" }
+codex-mcp-server = { path = "../mcp-server" }
 codex-tui = { path = "../tui" }
 serde_json = "1"
 tokio = { version = "1", features = [

codex-rs/cli/src/exit_status.rs

@@ -0,0 +1,23 @@
+#[cfg(unix)]
+pub(crate) fn handle_exit_status(status: std::process::ExitStatus) -> ! {
+    use std::os::unix::process::ExitStatusExt;
+
+    // Use ExitStatus to derive the exit code.
+    if let Some(code) = status.code() {
+        std::process::exit(code);
+    } else if let Some(signal) = status.signal() {
+        std::process::exit(128 + signal);
+    } else {
+        std::process::exit(1);
+    }
+}
+
+#[cfg(windows)]
+pub(crate) fn handle_exit_status(status: std::process::ExitStatus) -> ! {
+    if let Some(code) = status.code() {
+        std::process::exit(code);
+    } else {
+        // Rare on Windows, but if it happens: use fallback code.
+        std::process::exit(1);
+    }
+}

codex-rs/cli/src/landlock.rs

@@ -3,12 +3,14 @@
 //! On Linux the command is executed inside a Landlock + seccomp sandbox by
 //! calling the low-level `exec_linux` helper from `codex_core::linux`.
 
+use codex_core::exec::StdioPolicy;
+use codex_core::exec::spawn_child_sync;
+use codex_core::exec_linux::apply_sandbox_policy_to_current_thread;
 use codex_core::protocol::SandboxPolicy;
-use std::os::unix::process::ExitStatusExt;
-use std::process;
-use std::process::Command;
 use std::process::ExitStatus;
 
+use crate::exit_status::handle_exit_status;
+
 /// Execute `command` in a Linux sandbox (Landlock + seccomp) the way Codex
 /// would.
 pub fn run_landlock(command: Vec<String>, sandbox_policy: SandboxPolicy) -> anyhow::Result<()> {
@@ -19,20 +21,15 @@ pub fn run_landlock(command: Vec<String>, sandbox_policy: SandboxPolicy) -> anyh
     // Spawn a new thread and apply the sandbox policies there.
     let handle = std::thread::spawn(move || -> anyhow::Result<ExitStatus> {
         let cwd = std::env::current_dir()?;
-        codex_core::linux::apply_sandbox_policy_to_current_thread(sandbox_policy, &cwd)?;
-        let status = Command::new(&command[0]).args(&command[1..]).status()?;
+
+        apply_sandbox_policy_to_current_thread(&sandbox_policy, &cwd)?;
+        let mut child = spawn_child_sync(command, cwd, &sandbox_policy, StdioPolicy::Inherit)?;
+        let status = child.wait()?;
         Ok(status)
     });
     let status = handle
         .join()
         .map_err(|e| anyhow::anyhow!("Failed to join thread: {e:?}"))??;
 
-    // Use ExitStatus to derive the exit code.
-    if let Some(code) = status.code() {
-        process::exit(code);
-    } else if let Some(signal) = status.signal() {
-        process::exit(128 + signal);
-    } else {
-        process::exit(1);
-    }
+    handle_exit_status(status);
 }

codex-rs/cli/src/lib.rs

@@ -1,4 +1,5 @@
-#[cfg(target_os = "linux")]
+mod exit_status;
+#[cfg(unix)]
 pub mod landlock;
 pub mod proto;
 pub mod seatbelt;

codex-rs/cli/src/main.rs

@@ -33,6 +33,9 @@ enum Subcommand {
     #[clap(visible_alias = "e")]
     Exec(ExecCli),
 
+    /// Experimental: run Codex as an MCP server.
+    Mcp,
+
     /// Run the Protocol stream via stdin/stdout
     #[clap(visible_alias = "p")]
     Proto(ProtoCli),
@@ -70,6 +73,9 @@ async fn main() -> anyhow::Result<()> {
         Some(Subcommand::Exec(exec_cli)) => {
             codex_exec::run_main(exec_cli).await?;
         }
+        Some(Subcommand::Mcp) => {
+            codex_mcp_server::run_main().await?;
+        }
         Some(Subcommand::Proto(proto_cli)) => {
             proto::run_main(proto_cli).await?;
         }
@@ -82,7 +88,7 @@ async fn main() -> anyhow::Result<()> {
                 let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
                 seatbelt::run_seatbelt(command, sandbox_policy).await?;
             }
-            #[cfg(target_os = "linux")]
+            #[cfg(unix)]
             DebugCommand::Landlock(LandlockCommand {
                 command,
                 sandbox,
@@ -91,7 +97,7 @@ async fn main() -> anyhow::Result<()> {
                 let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
                 codex_cli::landlock::run_landlock(command, sandbox_policy)?;
             }
-            #[cfg(not(target_os = "linux"))]
+            #[cfg(not(unix))]
             DebugCommand::Landlock(_) => {
                 anyhow::bail!("Landlock is only supported on Linux.");
             }

codex-rs/cli/src/proto.rs

@@ -81,8 +81,13 @@ pub async fn run_main(_opts: ProtoCli) -> anyhow::Result<()> {
             };
             match event {
                 Ok(event) => {
-                    let event_str =
-                        serde_json::to_string(&event).expect("JSON serialization failed");
+                    let event_str = match serde_json::to_string(&event) {
+                        Ok(s) => s,
+                        Err(e) => {
+                            error!("Failed to serialize event: {e}");
+                            continue;
+                        }
+                    };
                     println!("{event_str}");
                 }
                 Err(e) => {

codex-rs/cli/src/seatbelt.rs

@@ -1,18 +1,16 @@
-use codex_core::exec::create_seatbelt_command;
+use codex_core::exec::StdioPolicy;
+use codex_core::exec::spawn_command_under_seatbelt;
 use codex_core::protocol::SandboxPolicy;
 
+use crate::exit_status::handle_exit_status;
+
 pub async fn run_seatbelt(
     command: Vec<String>,
     sandbox_policy: SandboxPolicy,
 ) -> anyhow::Result<()> {
-    let cwd = std::env::current_dir().expect("failed to get cwd");
-    let seatbelt_command = create_seatbelt_command(command, &sandbox_policy, &cwd);
-    let status = tokio::process::Command::new(seatbelt_command[0].clone())
-        .args(&seatbelt_command[1..])
-        .spawn()
-        .map_err(|e| anyhow::anyhow!("Failed to spawn command: {}", e))?
-        .wait()
-        .await
-        .map_err(|e| anyhow::anyhow!("Failed to wait for command: {}", e))?;
-    std::process::exit(status.code().unwrap_or(1));
+    let cwd = std::env::current_dir()?;
+    let mut child =
+        spawn_command_under_seatbelt(command, &sandbox_policy, cwd, StdioPolicy::Inherit).await?;
+    let status = child.wait().await?;
+    handle_exit_status(status);
 }

codex-rs/common/Cargo.toml

@@ -7,11 +7,10 @@ edition = "2024"
 workspace = true
 
 [dependencies]
-chrono = { version = "0.4.40", optional = true }
 clap = { version = "4", features = ["derive", "wrap_help"], optional = true }
 codex-core = { path = "../core" }
 
 [features]
 # Separate feature so that `clap` is not a mandatory dependency.
 cli = ["clap"]
-elapsed = ["chrono"]
+elapsed = []

codex-rs/common/src/elapsed.rs

@@ -1,18 +1,19 @@
-use chrono::Utc;
+use std::time::Duration;
+use std::time::Instant;
 
 /// Returns a string representing the elapsed time since `start_time` like
 /// "1m15s" or "1.50s".
-pub fn format_elapsed(start_time: chrono::DateTime<Utc>) -> String {
-    let elapsed = Utc::now().signed_duration_since(start_time);
-    format_time_delta(elapsed)
+pub fn format_elapsed(start_time: Instant) -> String {
+    format_duration(start_time.elapsed())
 }
 
-fn format_time_delta(elapsed: chrono::TimeDelta) -> String {
-    let millis = elapsed.num_milliseconds();
-    format_elapsed_millis(millis)
-}
-
-pub fn format_duration(duration: std::time::Duration) -> String {
+/// Convert a [`std::time::Duration`] into a human-readable, compact string.
+///
+/// Formatting rules:
+/// * < 1 s  ->  "{milli}ms"
+/// * < 60 s ->  "{sec:.2}s" (two decimal places)
+/// * >= 60 s ->  "{min}m{sec:02}s"
+pub fn format_duration(duration: Duration) -> String {
     let millis = duration.as_millis() as i64;
     format_elapsed_millis(millis)
 }
@@ -32,41 +33,40 @@ fn format_elapsed_millis(millis: i64) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use chrono::Duration;
 
     #[test]
-    fn test_format_time_delta_subsecond() {
+    fn test_format_duration_subsecond() {
         // Durations < 1s should be rendered in milliseconds with no decimals.
-        let dur = Duration::milliseconds(250);
-        assert_eq!(format_time_delta(dur), "250ms");
+        let dur = Duration::from_millis(250);
+        assert_eq!(format_duration(dur), "250ms");
 
         // Exactly zero should still work.
-        let dur_zero = Duration::milliseconds(0);
-        assert_eq!(format_time_delta(dur_zero), "0ms");
+        let dur_zero = Duration::from_millis(0);
+        assert_eq!(format_duration(dur_zero), "0ms");
     }
 
     #[test]
-    fn test_format_time_delta_seconds() {
+    fn test_format_duration_seconds() {
         // Durations between 1s (inclusive) and 60s (exclusive) should be
         // printed with 2-decimal-place seconds.
-        let dur = Duration::milliseconds(1_500); // 1.5s
-        assert_eq!(format_time_delta(dur), "1.50s");
+        let dur = Duration::from_millis(1_500); // 1.5s
+        assert_eq!(format_duration(dur), "1.50s");
 
         // 59.999s rounds to 60.00s
-        let dur2 = Duration::milliseconds(59_999);
-        assert_eq!(format_time_delta(dur2), "60.00s");
+        let dur2 = Duration::from_millis(59_999);
+        assert_eq!(format_duration(dur2), "60.00s");
     }
 
     #[test]
-    fn test_format_time_delta_minutes() {
+    fn test_format_duration_minutes() {
         // Durations ≥ 1 minute should be printed mmss.
-        let dur = Duration::milliseconds(75_000); // 1m15s
-        assert_eq!(format_time_delta(dur), "1m15s");
+        let dur = Duration::from_millis(75_000); // 1m15s
+        assert_eq!(format_duration(dur), "1m15s");
 
-        let dur_exact = Duration::milliseconds(60_000); // 1m0s
-        assert_eq!(format_time_delta(dur_exact), "1m00s");
+        let dur_exact = Duration::from_millis(60_000); // 1m0s
+        assert_eq!(format_duration(dur_exact), "1m00s");
 
-        let dur_long = Duration::milliseconds(3_601_000);
-        assert_eq!(format_time_delta(dur_long), "60m01s");
+        let dur_long = Duration::from_millis(3_601_000);
+        assert_eq!(format_duration(dur_long), "60m01s");
     }
 }

codex-rs/core/Cargo.toml

@@ -20,6 +20,7 @@ codex-mcp-client = { path = "../mcp-client" }
 dirs = "6"
 env-flags = "0.1.1"
 eventsource-stream = "0.2.3"
+fs2 = "0.4.3"
 fs-err = "3.1.0"
 futures = "0.3"
 mcp-types = { path = "../mcp-types" }
@@ -31,7 +32,7 @@ reqwest = { version = "0.12", features = ["json", "stream"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 thiserror = "2.0.12"
-time = { version = "0.3", features = ["formatting", "macros"] }
+time = { version = "0.3", features = ["formatting", "local-offset", "macros"] }
 tokio = { version = "1", features = [
     "io-std",
     "macros",
@@ -44,7 +45,7 @@ toml = "0.8.20"
 tracing = { version = "0.1.41", features = ["log"] }
 tree-sitter = "0.25.3"
 tree-sitter-bash = "0.23.3"
-uuid = { version = "1", features = ["v4"] }
+uuid = { version = "1", features = ["serde", "v4"] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 libc = "0.2.172"
@@ -58,5 +59,6 @@ openssl-sys = { version = "*", features = ["vendored"] }
 [dev-dependencies]
 assert_cmd = "2"
 predicates = "3"
+pretty_assertions = "1.4.1"
 tempfile = "3"
 wiremock = "0.6"

codex-rs/core/src/chat_completions.rs

@@ -38,9 +38,8 @@ pub(crate) async fn stream_chat_completions(
     // Build messages array
     let mut messages = Vec::<serde_json::Value>::new();
 
-    if let Some(instr) = &prompt.instructions {
-        messages.push(json!({"role": "system", "content": instr}));
-    }
+    let full_instructions = prompt.get_full_instructions();
+    messages.push(json!({"role": "system", "content": full_instructions}));
 
     for item in &prompt.input {
         if let ResponseItem::Message { role, content } = item {

codex-rs/core/src/client.rs

@@ -26,7 +26,9 @@ use crate::client_common::Prompt;
 use crate::client_common::Reasoning;
 use crate::client_common::ResponseEvent;
 use crate::client_common::ResponseStream;
+use crate::client_common::Summary;
 use crate::error::CodexErr;
+use crate::error::EnvVarError;
 use crate::error::Result;
 use crate::flags::CODEX_RS_SSE_FIXTURE;
 use crate::flags::OPENAI_REQUEST_MAX_RETRIES;
@@ -38,10 +40,18 @@ use crate::util::backoff;
 
 /// When serialized as JSON, this produces a valid "Tool" in the OpenAI
 /// Responses API.
-#[derive(Debug, Serialize)]
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type")]
+enum OpenAiTool {
+    #[serde(rename = "function")]
+    Function(ResponsesApiTool),
+    #[serde(rename = "local_shell")]
+    LocalShell {},
+}
+
+#[derive(Debug, Clone, Serialize)]
 struct ResponsesApiTool {
     name: &'static str,
-    r#type: &'static str, // "function"
     description: &'static str,
     strict: bool,
     parameters: JsonSchema,
@@ -65,7 +75,7 @@ enum JsonSchema {
 }
 
 /// Tool usage specification
-static DEFAULT_TOOLS: LazyLock<Vec<ResponsesApiTool>> = LazyLock::new(|| {
+static DEFAULT_TOOLS: LazyLock<Vec<OpenAiTool>> = LazyLock::new(|| {
     let mut properties = BTreeMap::new();
     properties.insert(
         "command".to_string(),
@@ -76,9 +86,8 @@ static DEFAULT_TOOLS: LazyLock<Vec<ResponsesApiTool>> = LazyLock::new(|| {
     properties.insert("workdir".to_string(), JsonSchema::String);
     properties.insert("timeout".to_string(), JsonSchema::Number);
 
-    vec![ResponsesApiTool {
+    vec![OpenAiTool::Function(ResponsesApiTool {
         name: "shell",
-        r#type: "function",
         description: "Runs a shell command, and returns its output.",
         strict: false,
         parameters: JsonSchema::Object {
@@ -86,9 +95,12 @@ static DEFAULT_TOOLS: LazyLock<Vec<ResponsesApiTool>> = LazyLock::new(|| {
             required: &["command"],
             additional_properties: false,
         },
-    }]
+    })]
 });
 
+static DEFAULT_CODEX_MODEL_TOOLS: LazyLock<Vec<OpenAiTool>> =
+    LazyLock::new(|| vec![OpenAiTool::LocalShell {}]);
+
 #[derive(Clone)]
 pub struct ModelClient {
     model: String,
@@ -150,10 +162,15 @@ impl ModelClient {
         }
 
         // Assemble tool list: built-in tools + any extra tools from the prompt.
-        let mut tools_json: Vec<serde_json::Value> = DEFAULT_TOOLS
-            .iter()
-            .map(|t| serde_json::to_value(t).expect("serialize builtin tool"))
-            .collect();
+        let default_tools = if self.model.starts_with("codex") {
+            &DEFAULT_CODEX_MODEL_TOOLS
+        } else {
+            &DEFAULT_TOOLS
+        };
+        let mut tools_json = Vec::with_capacity(default_tools.len() + prompt.extra_tools.len());
+        for t in default_tools.iter() {
+            tools_json.push(serde_json::to_value(t)?);
+        }
         tools_json.extend(
             prompt
                 .extra_tools
@@ -164,16 +181,17 @@ impl ModelClient {
 
         debug!("tools_json: {}", serde_json::to_string_pretty(&tools_json)?);
 
+        let full_instructions = prompt.get_full_instructions();
         let payload = Payload {
             model: &self.model,
-            instructions: prompt.instructions.as_ref(),
+            instructions: &full_instructions,
             input: &prompt.input,
             tools: &tools_json,
             tool_choice: "auto",
             parallel_tool_calls: false,
             reasoning: Some(Reasoning {
                 effort: "high",
-                generate_summary: None,
+                summary: Some(Summary::Auto),
             }),
             previous_response_id: prompt.prev_id.clone(),
             store: prompt.store,
@@ -190,10 +208,12 @@ impl ModelClient {
         loop {
             attempt += 1;
 
-            let api_key = self
-                .provider
-                .api_key()?
-                .expect("Repsones API requires an API key");
+            let api_key = self.provider.api_key()?.ok_or_else(|| {
+                CodexErr::EnvVar(EnvVarError {
+                    var: self.provider.env_key.clone().unwrap_or_default(),
+                    instructions: None,
+                })
+            })?;
             let res = self
                 .client
                 .post(&url)

codex-rs/core/src/client_common.rs

@@ -2,12 +2,17 @@ use crate::error::Result;
 use crate::models::ResponseItem;
 use futures::Stream;
 use serde::Serialize;
+use std::borrow::Cow;
 use std::collections::HashMap;
 use std::pin::Pin;
 use std::task::Context;
 use std::task::Poll;
 use tokio::sync::mpsc;
 
+/// The `instructions` field in the payload sent to a model should always start
+/// with this content.
+const BASE_INSTRUCTIONS: &str = include_str!("../prompt.md");
+
 /// API request payload for a single model turn.
 #[derive(Default, Debug, Clone)]
 pub struct Prompt {
@@ -15,7 +20,8 @@ pub struct Prompt {
     pub input: Vec<ResponseItem>,
     /// Optional previous response ID (when storage is enabled).
     pub prev_id: Option<String>,
-    /// Optional initial instructions (only sent on first turn).
+    /// Optional instructions from the user to amend to the built-in agent
+    /// instructions.
     pub instructions: Option<String>,
     /// Whether to store response on server side (disable_response_storage = !store).
     pub store: bool,
@@ -26,6 +32,18 @@ pub struct Prompt {
     pub extra_tools: HashMap<String, mcp_types::Tool>,
 }
 
+impl Prompt {
+    pub(crate) fn get_full_instructions(&self) -> Cow<str> {
+        match &self.instructions {
+            Some(instructions) => {
+                let instructions = format!("{BASE_INSTRUCTIONS}\n{instructions}");
+                Cow::Owned(instructions)
+            }
+            None => Cow::Borrowed(BASE_INSTRUCTIONS),
+        }
+    }
+}
+
 #[derive(Debug)]
 pub enum ResponseEvent {
     OutputItemDone(ResponseItem),
@@ -36,14 +54,25 @@ pub enum ResponseEvent {
 pub(crate) struct Reasoning {
     pub(crate) effort: &'static str,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub(crate) generate_summary: Option<bool>,
+    pub(crate) summary: Option<Summary>,
+}
+
+/// A summary of the reasoning performed by the model. This can be useful for
+/// debugging and understanding the model's reasoning process.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum Summary {
+    Auto,
+    #[allow(dead_code)] // Will go away once this is configurable.
+    Concise,
+    #[allow(dead_code)] // Will go away once this is configurable.
+    Detailed,
 }
 
 #[derive(Debug, Serialize)]
 pub(crate) struct Payload<'a> {
     pub(crate) model: &'a str,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub(crate) instructions: Option<&'a String>,
+    pub(crate) instructions: &'a str,
     // TODO(mbolin): ResponseItem::Other should not be serialized. Currently,
     // we code defensively to avoid this case, but perhaps we should use a
     // separate enum for serialization.

codex-rs/core/src/codex_wrapper.rs

@@ -24,7 +24,7 @@ pub async fn init_codex(config: Config) -> anyhow::Result<(Codex, Event, Arc<Not
             &event,
             Event {
                 id: _id,
-                msg: EventMsg::SessionConfigured { .. },
+                msg: EventMsg::SessionConfigured(_),
             }
         )
     {

codex-rs/core/src/config.rs

@@ -1,5 +1,9 @@
+use crate::config_profile::ConfigProfile;
+use crate::config_types::History;
+use crate::config_types::McpServerConfig;
+use crate::config_types::Tui;
+use crate::config_types::UriBasedFileOpener;
 use crate::flags::OPENAI_DEFAULT_MODEL;
-use crate::mcp_server_config::McpServerConfig;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::built_in_model_providers;
 use crate::protocol::AskForApproval;
@@ -8,15 +12,16 @@ use crate::protocol::SandboxPolicy;
 use dirs::home_dir;
 use serde::Deserialize;
 use std::collections::HashMap;
+use std::path::Path;
 use std::path::PathBuf;
 
-/// Embedded fallback instructions that mirror the TypeScript CLI’s default
-/// system prompt. These are compiled into the binary so a clean install behaves
-/// correctly even if the user has not created `~/.codex/instructions.md`.
-const EMBEDDED_INSTRUCTIONS: &str = include_str!("../prompt.md");
+/// Maximum number of bytes of the documentation that will be embedded. Larger
+/// files are *silently truncated* to this size so we do not take up too much of
+/// the context window.
+pub(crate) const PROJECT_DOC_MAX_BYTES: usize = 32 * 1024; // 32 KiB
 
 /// Application configuration loaded from disk and merged with overrides.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct Config {
     /// Optional override of model selection.
     pub model: String,
@@ -37,7 +42,7 @@ pub struct Config {
     /// who have opted into Zero Data Retention (ZDR).
     pub disable_response_storage: bool,
 
-    /// System instructions.
+    /// User-provided instructions from instructions.md.
     pub instructions: Option<String>,
 
     /// Optional external notifier command. When set, Codex will spawn this
@@ -72,6 +77,23 @@ pub struct Config {
 
     /// Combined provider map (defaults merged with user-defined overrides).
     pub model_providers: HashMap<String, ModelProviderInfo>,
+
+    /// Maximum number of bytes to include from an AGENTS.md project doc file.
+    pub project_doc_max_bytes: usize,
+
+    /// Directory containing all Codex state (defaults to `~/.codex` but can be
+    /// overridden by the `CODEX_HOME` environment variable).
+    pub codex_home: PathBuf,
+
+    /// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
+    pub history: History,
+
+    /// Optional URI-based file opener. If set, citations to files in the model
+    /// output will be hyperlinked using the specified URI scheme.
+    pub file_opener: UriBasedFileOpener,
+
+    /// Collection of settings that are specific to the TUI.
+    pub tui: Tui,
 }
 
 /// Base config deserialized from ~/.codex/config.toml.
@@ -111,14 +133,35 @@ pub struct ConfigToml {
     /// User-defined provider entries that extend/override the built-in list.
     #[serde(default)]
     pub model_providers: HashMap<String, ModelProviderInfo>,
+
+    /// Maximum number of bytes to include from an AGENTS.md project doc file.
+    pub project_doc_max_bytes: Option<usize>,
+
+    /// Profile to use from the `profiles` map.
+    pub profile: Option<String>,
+
+    /// Named profiles to facilitate switching between different configurations.
+    #[serde(default)]
+    pub profiles: HashMap<String, ConfigProfile>,
+
+    /// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
+    #[serde(default)]
+    pub history: Option<History>,
+
+    /// Optional URI-based file opener. If set, citations to files in the model
+    /// output will be hyperlinked using the specified URI scheme.
+    pub file_opener: Option<UriBasedFileOpener>,
+
+    /// Collection of settings that are specific to the TUI.
+    pub tui: Option<Tui>,
 }
 
 impl ConfigToml {
     /// Attempt to parse the file at `~/.codex/config.toml`. If it does not
     /// exist, return a default config. Though if it exists and cannot be
     /// parsed, report that to the user and force them to fix it.
-    fn load_from_toml() -> std::io::Result<Self> {
-        let config_toml_path = codex_dir()?.join("config.toml");
+    fn load_from_toml(codex_home: &Path) -> std::io::Result<Self> {
+        let config_toml_path = codex_home.join("config.toml");
         match std::fs::read_to_string(&config_toml_path) {
             Ok(contents) => toml::from_str::<Self>(&contents).map_err(|e| {
                 tracing::error!("Failed to parse config.toml: {e}");
@@ -146,7 +189,7 @@ where
 
     match permissions {
         Some(raw_permissions) => {
-            let base_path = codex_dir().map_err(serde::de::Error::custom)?;
+            let base_path = find_codex_home().map_err(serde::de::Error::custom)?;
 
             let converted = raw_permissions
                 .into_iter()
@@ -170,7 +213,8 @@ pub struct ConfigOverrides {
     pub approval_policy: Option<AskForApproval>,
     pub sandbox_policy: Option<SandboxPolicy>,
     pub disable_response_storage: Option<bool>,
-    pub provider: Option<String>,
+    pub model_provider: Option<String>,
+    pub config_profile: Option<String>,
 }
 
 impl Config {
@@ -178,18 +222,25 @@ impl Config {
     /// ~/.codex/config.toml, ~/.codex/instructions.md, embedded defaults, and
     /// any values provided in `overrides` (highest precedence).
     pub fn load_with_overrides(overrides: ConfigOverrides) -> std::io::Result<Self> {
-        let cfg: ConfigToml = ConfigToml::load_from_toml()?;
+        // Resolve the directory that stores Codex state (e.g. ~/.codex or the
+        // value of $CODEX_HOME) so we can embed it into the resulting
+        // `Config` instance.
+        let codex_home = find_codex_home()?;
+
+        let cfg: ConfigToml = ConfigToml::load_from_toml(&codex_home)?;
         tracing::warn!("Config parsed from config.toml: {cfg:?}");
-        Self::load_from_base_config_with_overrides(cfg, overrides)
+
+        Self::load_from_base_config_with_overrides(cfg, overrides, codex_home)
     }
 
-    fn load_from_base_config_with_overrides(
+    /// Meant to be used exclusively for tests: `load_with_overrides()` should
+    /// be used in all other cases.
+    pub fn load_from_base_config_with_overrides(
         cfg: ConfigToml,
         overrides: ConfigOverrides,
+        codex_home: PathBuf,
     ) -> std::io::Result<Self> {
-        // Instructions: user-provided instructions.md > embedded default.
-        let instructions =
-            Self::load_instructions().or_else(|| Some(EMBEDDED_INSTRUCTIONS.to_string()));
+        let instructions = Self::load_instructions(Some(&codex_home));
 
         // Destructure ConfigOverrides fully to ensure all overrides are applied.
         let ConfigOverrides {
@@ -198,9 +249,24 @@ impl Config {
             approval_policy,
             sandbox_policy,
             disable_response_storage,
-            provider,
+            model_provider,
+            config_profile: config_profile_key,
         } = overrides;
 
+        let config_profile = match config_profile_key.or(cfg.profile) {
+            Some(key) => cfg
+                .profiles
+                .get(&key)
+                .ok_or_else(|| {
+                    std::io::Error::new(
+                        std::io::ErrorKind::NotFound,
+                        format!("config profile `{key}` not found"),
+                    )
+                })?
+                .clone(),
+            None => ConfigProfile::default(),
+        };
+
         let sandbox_policy = match sandbox_policy {
             Some(sandbox_policy) => sandbox_policy,
             None => {
@@ -222,7 +288,8 @@ impl Config {
             model_providers.entry(key).or_insert(provider);
         }
 
-        let model_provider_id = provider
+        let model_provider_id = model_provider
+            .or(config_profile.model_provider)
             .or(cfg.model_provider)
             .unwrap_or_else(|| "openai".to_string());
         let model_provider = model_providers
@@ -235,56 +302,72 @@ impl Config {
             })?
             .clone();
 
+        let resolved_cwd = {
+            use std::env;
+
+            match cwd {
+                None => {
+                    tracing::info!("cwd not set, using current dir");
+                    env::current_dir()?
+                }
+                Some(p) if p.is_absolute() => p,
+                Some(p) => {
+                    // Resolve relative path against the current working directory.
+                    tracing::info!("cwd is relative, resolving against current dir");
+                    let mut current = env::current_dir()?;
+                    current.push(p);
+                    current
+                }
+            }
+        };
+
+        let history = cfg.history.unwrap_or_default();
+
         let config = Self {
-            model: model.or(cfg.model).unwrap_or_else(default_model),
+            model: model
+                .or(config_profile.model)
+                .or(cfg.model)
+                .unwrap_or_else(default_model),
             model_provider_id,
             model_provider,
-            cwd: cwd.map_or_else(
-                || {
-                    tracing::info!("cwd not set, using current dir");
-                    std::env::current_dir().expect("cannot determine current dir")
-                },
-                |p| {
-                    if p.is_absolute() {
-                        p
-                    } else {
-                        // Resolve relative paths against the current working directory.
-                        tracing::info!("cwd is relative, resolving against current dir");
-                        let mut cwd = std::env::current_dir().expect("cannot determine cwd");
-                        cwd.push(p);
-                        cwd
-                    }
-                },
-            ),
+            cwd: resolved_cwd,
             approval_policy: approval_policy
+                .or(config_profile.approval_policy)
                 .or(cfg.approval_policy)
                 .unwrap_or_else(AskForApproval::default),
             sandbox_policy,
             disable_response_storage: disable_response_storage
+                .or(config_profile.disable_response_storage)
                 .or(cfg.disable_response_storage)
                 .unwrap_or(false),
             notify: cfg.notify,
             instructions,
             mcp_servers: cfg.mcp_servers,
             model_providers,
+            project_doc_max_bytes: cfg.project_doc_max_bytes.unwrap_or(PROJECT_DOC_MAX_BYTES),
+            codex_home,
+            history,
+            file_opener: cfg.file_opener.unwrap_or(UriBasedFileOpener::VsCode),
+            tui: cfg.tui.unwrap_or_default(),
         };
         Ok(config)
     }
 
-    fn load_instructions() -> Option<String> {
-        let mut p = codex_dir().ok()?;
-        p.push("instructions.md");
-        std::fs::read_to_string(&p).ok()
-    }
+    fn load_instructions(codex_dir: Option<&Path>) -> Option<String> {
+        let mut p = match codex_dir {
+            Some(p) => p.to_path_buf(),
+            None => return None,
+        };
 
-    /// Meant to be used exclusively for tests: `load_with_overrides()` should
-    /// be used in all other cases.
-    pub fn load_default_config_for_test() -> Self {
-        Self::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-        )
-        .expect("defaults for test should always succeed")
+        p.push("instructions.md");
+        std::fs::read_to_string(&p).ok().and_then(|s| {
+            let s = s.trim();
+            if s.is_empty() {
+                None
+            } else {
+                Some(s.to_string())
+            }
+        })
     }
 }
 
@@ -292,9 +375,23 @@ fn default_model() -> String {
     OPENAI_DEFAULT_MODEL.to_string()
 }
 
-/// Returns the path to the Codex configuration directory, which is `~/.codex`.
-/// Does not verify that the directory exists.
-pub fn codex_dir() -> std::io::Result<PathBuf> {
+/// Returns the path to the Codex configuration directory, which can be
+/// specified by the `CODEX_HOME` environment variable. If not set, defaults to
+/// `~/.codex`.
+///
+/// - If `CODEX_HOME` is set, the value will be canonicalized and this
+///   function will Err if the path does not exist.
+/// - If `CODEX_HOME` is not set, this function does not verify that the
+///   directory exists.
+fn find_codex_home() -> std::io::Result<PathBuf> {
+    // Honor the `CODEX_HOME` environment variable when it is set to allow users
+    // (and tests) to override the default location.
+    if let Ok(val) = std::env::var("CODEX_HOME") {
+        if !val.is_empty() {
+            return PathBuf::from(val).canonicalize();
+        }
+    }
+
     let mut p = home_dir().ok_or_else(|| {
         std::io::Error::new(
             std::io::ErrorKind::NotFound,
@@ -307,8 +404,8 @@ pub fn codex_dir() -> std::io::Result<PathBuf> {
 
 /// Returns the path to the folder where Codex logs are stored. Does not verify
 /// that the directory exists.
-pub fn log_dir() -> std::io::Result<PathBuf> {
-    let mut p = codex_dir()?;
+pub fn log_dir(cfg: &Config) -> std::io::Result<PathBuf> {
+    let mut p = cfg.codex_home.clone();
     p.push("log");
     Ok(p)
 }
@@ -359,7 +456,12 @@ pub fn parse_sandbox_permission_with_base_path(
 
 #[cfg(test)]
 mod tests {
+    #![allow(clippy::expect_used, clippy::unwrap_used)]
+    use crate::config_types::HistoryPersistence;
+
     use super::*;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
 
     /// Verify that the `sandbox_permissions` field on `ConfigToml` correctly
     /// differentiates between a value that is completely absent in the
@@ -397,6 +499,40 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_toml_parsing() {
+        let history_with_persistence = r#"
+[history]
+persistence = "save-all"
+"#;
+        let history_with_persistence_cfg: ConfigToml =
+            toml::from_str::<ConfigToml>(history_with_persistence)
+                .expect("TOML deserialization should succeed");
+        assert_eq!(
+            Some(History {
+                persistence: HistoryPersistence::SaveAll,
+                max_bytes: None,
+            }),
+            history_with_persistence_cfg.history
+        );
+
+        let history_no_persistence = r#"
+[history]
+persistence = "none"
+"#;
+
+        let history_no_persistence_cfg: ConfigToml =
+            toml::from_str::<ConfigToml>(history_no_persistence)
+                .expect("TOML deserialization should succeed");
+        assert_eq!(
+            Some(History {
+                persistence: HistoryPersistence::None,
+                max_bytes: None,
+            }),
+            history_no_persistence_cfg.history
+        );
+    }
+
     /// Deserializing a TOML string containing an *invalid* permission should
     /// fail with a helpful error rather than silently defaulting or
     /// succeeding.
@@ -412,4 +548,239 @@ mod tests {
         let msg = err.to_string();
         assert!(msg.contains("not-a-real-permission"));
     }
+
+    struct PrecedenceTestFixture {
+        cwd: TempDir,
+        codex_home: TempDir,
+        cfg: ConfigToml,
+        model_provider_map: HashMap<String, ModelProviderInfo>,
+        openai_provider: ModelProviderInfo,
+        openai_chat_completions_provider: ModelProviderInfo,
+    }
+
+    impl PrecedenceTestFixture {
+        fn cwd(&self) -> PathBuf {
+            self.cwd.path().to_path_buf()
+        }
+
+        fn codex_home(&self) -> PathBuf {
+            self.codex_home.path().to_path_buf()
+        }
+    }
+
+    fn create_test_fixture() -> std::io::Result<PrecedenceTestFixture> {
+        let toml = r#"
+model = "o3"
+approval_policy = "unless-allow-listed"
+sandbox_permissions = ["disk-full-read-access"]
+disable_response_storage = false
+
+# Can be used to determine which profile to use if not specified by
+# `ConfigOverrides`.
+profile = "gpt3"
+
+[model_providers.openai-chat-completions]
+name = "OpenAI using Chat Completions"
+base_url = "https://api.openai.com/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "chat"
+
+[profiles.o3]
+model = "o3"
+model_provider = "openai"
+approval_policy = "never"
+
+[profiles.gpt3]
+model = "gpt-3.5-turbo"
+model_provider = "openai-chat-completions"
+
+[profiles.zdr]
+model = "o3"
+model_provider = "openai"
+approval_policy = "on-failure"
+disable_response_storage = true
+"#;
+
+        let cfg: ConfigToml = toml::from_str(toml).expect("TOML deserialization should succeed");
+
+        // Use a temporary directory for the cwd so it does not contain an
+        // AGENTS.md file.
+        let cwd_temp_dir = TempDir::new().unwrap();
+        let cwd = cwd_temp_dir.path().to_path_buf();
+        // Make it look like a Git repo so it does not search for AGENTS.md in
+        // a parent folder, either.
+        std::fs::write(cwd.join(".git"), "gitdir: nowhere")?;
+
+        let codex_home_temp_dir = TempDir::new().unwrap();
+
+        let openai_chat_completions_provider = ModelProviderInfo {
+            name: "OpenAI using Chat Completions".to_string(),
+            base_url: "https://api.openai.com/v1".to_string(),
+            env_key: Some("OPENAI_API_KEY".to_string()),
+            wire_api: crate::WireApi::Chat,
+            env_key_instructions: None,
+        };
+        let model_provider_map = {
+            let mut model_provider_map = built_in_model_providers();
+            model_provider_map.insert(
+                "openai-chat-completions".to_string(),
+                openai_chat_completions_provider.clone(),
+            );
+            model_provider_map
+        };
+
+        let openai_provider = model_provider_map
+            .get("openai")
+            .expect("openai provider should exist")
+            .clone();
+
+        Ok(PrecedenceTestFixture {
+            cwd: cwd_temp_dir,
+            codex_home: codex_home_temp_dir,
+            cfg,
+            model_provider_map,
+            openai_provider,
+            openai_chat_completions_provider,
+        })
+    }
+
+    /// Users can specify config values at multiple levels that have the
+    /// following precedence:
+    ///
+    /// 1. custom command-line argument, e.g. `--model o3`
+    /// 2. as part of a profile, where the `--profile` is specified via a CLI
+    ///    (or in the config file itelf)
+    /// 3. as an entry in `config.toml`, e.g. `model = "o3"`
+    /// 4. the default value for a required field defined in code, e.g.,
+    ///    `crate::flags::OPENAI_DEFAULT_MODEL`
+    ///
+    /// Note that profiles are the recommended way to specify a group of
+    /// configuration options together.
+    #[test]
+    fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> {
+        let fixture = create_test_fixture()?;
+
+        let o3_profile_overrides = ConfigOverrides {
+            config_profile: Some("o3".to_string()),
+            cwd: Some(fixture.cwd()),
+            ..Default::default()
+        };
+        let o3_profile_config: Config = Config::load_from_base_config_with_overrides(
+            fixture.cfg.clone(),
+            o3_profile_overrides,
+            fixture.codex_home(),
+        )?;
+        assert_eq!(
+            Config {
+                model: "o3".to_string(),
+                model_provider_id: "openai".to_string(),
+                model_provider: fixture.openai_provider.clone(),
+                approval_policy: AskForApproval::Never,
+                sandbox_policy: SandboxPolicy::new_read_only_policy(),
+                disable_response_storage: false,
+                instructions: None,
+                notify: None,
+                cwd: fixture.cwd(),
+                mcp_servers: HashMap::new(),
+                model_providers: fixture.model_provider_map.clone(),
+                project_doc_max_bytes: PROJECT_DOC_MAX_BYTES,
+                codex_home: fixture.codex_home(),
+                history: History::default(),
+                file_opener: UriBasedFileOpener::VsCode,
+                tui: Tui::default(),
+            },
+            o3_profile_config
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> {
+        let fixture = create_test_fixture()?;
+
+        let gpt3_profile_overrides = ConfigOverrides {
+            config_profile: Some("gpt3".to_string()),
+            cwd: Some(fixture.cwd()),
+            ..Default::default()
+        };
+        let gpt3_profile_config = Config::load_from_base_config_with_overrides(
+            fixture.cfg.clone(),
+            gpt3_profile_overrides,
+            fixture.codex_home(),
+        )?;
+        let expected_gpt3_profile_config = Config {
+            model: "gpt-3.5-turbo".to_string(),
+            model_provider_id: "openai-chat-completions".to_string(),
+            model_provider: fixture.openai_chat_completions_provider.clone(),
+            approval_policy: AskForApproval::UnlessAllowListed,
+            sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            disable_response_storage: false,
+            instructions: None,
+            notify: None,
+            cwd: fixture.cwd(),
+            mcp_servers: HashMap::new(),
+            model_providers: fixture.model_provider_map.clone(),
+            project_doc_max_bytes: PROJECT_DOC_MAX_BYTES,
+            codex_home: fixture.codex_home(),
+            history: History::default(),
+            file_opener: UriBasedFileOpener::VsCode,
+            tui: Tui::default(),
+        };
+
+        assert_eq!(expected_gpt3_profile_config, gpt3_profile_config);
+
+        // Verify that loading without specifying a profile in ConfigOverrides
+        // uses the default profile from the config file (which is "gpt3").
+        let default_profile_overrides = ConfigOverrides {
+            cwd: Some(fixture.cwd()),
+            ..Default::default()
+        };
+
+        let default_profile_config = Config::load_from_base_config_with_overrides(
+            fixture.cfg.clone(),
+            default_profile_overrides,
+            fixture.codex_home(),
+        )?;
+
+        assert_eq!(expected_gpt3_profile_config, default_profile_config);
+        Ok(())
+    }
+
+    #[test]
+    fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> {
+        let fixture = create_test_fixture()?;
+
+        let zdr_profile_overrides = ConfigOverrides {
+            config_profile: Some("zdr".to_string()),
+            cwd: Some(fixture.cwd()),
+            ..Default::default()
+        };
+        let zdr_profile_config = Config::load_from_base_config_with_overrides(
+            fixture.cfg.clone(),
+            zdr_profile_overrides,
+            fixture.codex_home(),
+        )?;
+        let expected_zdr_profile_config = Config {
+            model: "o3".to_string(),
+            model_provider_id: "openai".to_string(),
+            model_provider: fixture.openai_provider.clone(),
+            approval_policy: AskForApproval::OnFailure,
+            sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            disable_response_storage: true,
+            instructions: None,
+            notify: None,
+            cwd: fixture.cwd(),
+            mcp_servers: HashMap::new(),
+            model_providers: fixture.model_provider_map.clone(),
+            project_doc_max_bytes: PROJECT_DOC_MAX_BYTES,
+            codex_home: fixture.codex_home(),
+            history: History::default(),
+            file_opener: UriBasedFileOpener::VsCode,
+            tui: Tui::default(),
+        };
+
+        assert_eq!(expected_zdr_profile_config, zdr_profile_config);
+
+        Ok(())
+    }
 }

codex-rs/core/src/config_profile.rs

@@ -0,0 +1,15 @@
+use serde::Deserialize;
+
+use crate::protocol::AskForApproval;
+
+/// Collection of common configuration options that a user can define as a unit
+/// in `config.toml`.
+#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
+pub struct ConfigProfile {
+    pub model: Option<String>,
+    /// The key in the `model_providers` map identifying the
+    /// [`ModelProviderInfo`] to use.
+    pub model_provider: Option<String>,
+    pub approval_policy: Option<AskForApproval>,
+    pub disable_response_storage: Option<bool>,
+}

codex-rs/core/src/config_types.rs

@@ -0,0 +1,88 @@
+//! Types used to define the fields of [`crate::config::Config`].
+
+// Note this file should generally be restricted to simple struct/enum
+// definitions that do not contain business logic.
+
+use std::collections::HashMap;
+
+use serde::Deserialize;
+
+#[derive(Deserialize, Debug, Clone, PartialEq)]
+pub struct McpServerConfig {
+    pub command: String,
+
+    #[serde(default)]
+    pub args: Vec<String>,
+
+    #[serde(default)]
+    pub env: Option<HashMap<String, String>>,
+}
+
+#[derive(Deserialize, Debug, Copy, Clone, PartialEq)]
+pub enum UriBasedFileOpener {
+    #[serde(rename = "vscode")]
+    VsCode,
+
+    #[serde(rename = "vscode-insiders")]
+    VsCodeInsiders,
+
+    #[serde(rename = "windsurf")]
+    Windsurf,
+
+    #[serde(rename = "cursor")]
+    Cursor,
+
+    /// Option to disable the URI-based file opener.
+    #[serde(rename = "none")]
+    None,
+}
+
+impl UriBasedFileOpener {
+    pub fn get_scheme(&self) -> Option<&str> {
+        match self {
+            UriBasedFileOpener::VsCode => Some("vscode"),
+            UriBasedFileOpener::VsCodeInsiders => Some("vscode-insiders"),
+            UriBasedFileOpener::Windsurf => Some("windsurf"),
+            UriBasedFileOpener::Cursor => Some("cursor"),
+            UriBasedFileOpener::None => None,
+        }
+    }
+}
+
+/// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
+#[derive(Deserialize, Debug, Clone, PartialEq, Default)]
+pub struct History {
+    /// If true, history entries will not be written to disk.
+    pub persistence: HistoryPersistence,
+
+    /// If set, the maximum size of the history file in bytes.
+    /// TODO(mbolin): Not currently honored.
+    pub max_bytes: Option<usize>,
+}
+
+#[derive(Deserialize, Debug, Copy, Clone, PartialEq, Default)]
+#[serde(rename_all = "kebab-case")]
+pub enum HistoryPersistence {
+    /// Save all history entries to disk.
+    #[default]
+    SaveAll,
+    /// Do not write history to disk.
+    None,
+}
+
+/// Collection of settings that are specific to the TUI.
+#[derive(Deserialize, Debug, Clone, PartialEq, Default)]
+pub struct Tui {
+    /// By default, mouse capture is enabled in the TUI so that it is possible
+    /// to scroll the conversation history with a mouse. This comes at the cost
+    /// of not being able to use the mouse to select text in the TUI.
+    /// (Most terminals support a modifier key to allow this. For example,
+    /// text selection works in iTerm if you hold down the `Option` key while
+    /// clicking and dragging.)
+    ///
+    /// Setting this option to `true` disables mouse capture, so scrolling with
+    /// the mouse is not possible, though the keyboard shortcuts e.g. `b` and
+    /// `space` still work. This allows the user to select text in the TUI
+    /// using the mouse without needing to hold down a modifier key.
+    pub disable_mouse_capture: bool,
+}

codex-rs/core/src/conversation_history.rs

@@ -25,7 +25,8 @@ impl ConversationHistory {
     /// `items` is ordered from oldest to newest.
     pub(crate) fn record_items<I>(&mut self, items: I)
     where
-        I: IntoIterator<Item = ResponseItem>,
+        I: IntoIterator,
+        I::Item: std::ops::Deref<Target = ResponseItem>,
     {
         for item in items {
             if is_api_message(&item) {
@@ -41,8 +42,9 @@ impl ConversationHistory {
 fn is_api_message(message: &ResponseItem) -> bool {
     match message {
         ResponseItem::Message { role, .. } => role.as_str() != "system",
-        ResponseItem::FunctionCall { .. } => true,
-        ResponseItem::FunctionCallOutput { .. } => true,
-        _ => false,
+        ResponseItem::FunctionCallOutput { .. }
+        | ResponseItem::FunctionCall { .. }
+        | ResponseItem::LocalShellCall { .. } => true,
+        ResponseItem::Reasoning { .. } | ResponseItem::Other => false,
     }
 }

codex-rs/core/src/exec.rs

@@ -1,6 +1,7 @@
-use std::io;
-#[cfg(target_family = "unix")]
+#[cfg(unix)]
 use std::os::unix::process::ExitStatusExt;
+
+use std::io;
 use std::path::Path;
 use std::path::PathBuf;
 use std::process::ExitStatus;
@@ -19,6 +20,7 @@ use tokio::sync::Notify;
 use crate::error::CodexErr;
 use crate::error::Result;
 use crate::error::SandboxErr;
+use crate::exec_linux::exec_linux;
 use crate::protocol::SandboxPolicy;
 
 // Maximum we send for each stream, which is either:
@@ -42,6 +44,16 @@ const MACOS_SEATBELT_BASE_POLICY: &str = include_str!("seatbelt_base_policy.sbpl
 /// already has root access.
 const MACOS_PATH_TO_SEATBELT_EXECUTABLE: &str = "/usr/bin/sandbox-exec";
 
+/// Experimental environment variable that will be set to some non-empty value
+/// if both of the following are true:
+///
+/// 1. The process was spawned by Codex as part of a shell tool call.
+/// 2. SandboxPolicy.has_full_network_access() was false for the tool call.
+///
+/// We may try to have just one environment variable for all sandboxing
+/// attributes, so this may change in the future.
+pub const CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR: &str = "CODEX_SANDBOX_NETWORK_DISABLED";
+
 #[derive(Debug, Clone)]
 pub struct ExecParams {
     pub command: Vec<String>,
@@ -60,27 +72,6 @@ pub enum SandboxType {
     LinuxSeccomp,
 }
 
-#[cfg(target_os = "linux")]
-async fn exec_linux(
-    params: ExecParams,
-    ctrl_c: Arc<Notify>,
-    sandbox_policy: &SandboxPolicy,
-) -> Result<RawExecToolCallOutput> {
-    crate::linux::exec_linux(params, ctrl_c, sandbox_policy).await
-}
-
-#[cfg(not(target_os = "linux"))]
-async fn exec_linux(
-    _params: ExecParams,
-    _ctrl_c: Arc<Notify>,
-    _sandbox_policy: &SandboxPolicy,
-) -> Result<RawExecToolCallOutput> {
-    Err(CodexErr::Io(io::Error::new(
-        io::ErrorKind::InvalidInput,
-        "linux sandbox is not supported on this platform",
-    )))
-}
-
 pub async fn process_exec_tool_call(
     params: ExecParams,
     sandbox_type: SandboxType,
@@ -90,25 +81,23 @@ pub async fn process_exec_tool_call(
     let start = Instant::now();
 
     let raw_output_result = match sandbox_type {
-        SandboxType::None => exec(params, ctrl_c).await,
+        SandboxType::None => exec(params, sandbox_policy, ctrl_c).await,
         SandboxType::MacosSeatbelt => {
             let ExecParams {
                 command,
                 cwd,
                 timeout_ms,
             } = params;
-            let seatbelt_command = create_seatbelt_command(command, sandbox_policy, &cwd);
-            exec(
-                ExecParams {
-                    command: seatbelt_command,
-                    cwd,
-                    timeout_ms,
-                },
-                ctrl_c,
+            let child = spawn_command_under_seatbelt(
+                command,
+                sandbox_policy,
+                cwd,
+                StdioPolicy::RedirectForShellTool,
             )
-            .await
+            .await?;
+            consume_truncated_output(child, ctrl_c, timeout_ms).await
         }
-        SandboxType::LinuxSeccomp => exec_linux(params, ctrl_c, sandbox_policy).await,
+        SandboxType::LinuxSeccomp => exec_linux(params, ctrl_c, sandbox_policy),
     };
     let duration = start.elapsed();
     match raw_output_result {
@@ -151,7 +140,17 @@ pub async fn process_exec_tool_call(
     }
 }
 
-pub fn create_seatbelt_command(
+pub async fn spawn_command_under_seatbelt(
+    command: Vec<String>,
+    sandbox_policy: &SandboxPolicy,
+    cwd: PathBuf,
+    stdio_policy: StdioPolicy,
+) -> std::io::Result<Child> {
+    let seatbelt_command = create_seatbelt_command(command, sandbox_policy, &cwd);
+    spawn_child_async(seatbelt_command, cwd, sandbox_policy, stdio_policy).await
+}
+
+fn create_seatbelt_command(
     command: Vec<String>,
     sandbox_policy: &SandboxPolicy,
     cwd: &Path,
@@ -229,57 +228,144 @@ pub struct ExecToolCallOutput {
     pub duration: Duration,
 }
 
-pub async fn exec(
+async fn exec(
     ExecParams {
         command,
         cwd,
         timeout_ms,
     }: ExecParams,
+    sandbox_policy: &SandboxPolicy,
     ctrl_c: Arc<Notify>,
 ) -> Result<RawExecToolCallOutput> {
-    let child = spawn_child(command, cwd).await?;
+    let child = spawn_child_async(
+        command,
+        cwd,
+        sandbox_policy,
+        StdioPolicy::RedirectForShellTool,
+    )
+    .await?;
     consume_truncated_output(child, ctrl_c, timeout_ms).await
 }
 
-/// Spawns the appropriate child process for the ExecParams.
-async fn spawn_child(command: Vec<String>, cwd: PathBuf) -> std::io::Result<Child> {
-    if command.is_empty() {
-        return Err(std::io::Error::new(
-            io::ErrorKind::InvalidInput,
-            "command args are empty",
-        ));
-    }
+#[derive(Debug, Clone, Copy)]
+pub enum StdioPolicy {
+    RedirectForShellTool,
+    Inherit,
+}
 
-    let mut cmd = Command::new(&command[0]);
-    cmd.args(&command[1..]);
-    cmd.current_dir(cwd);
+macro_rules! configure_command {
+    (
+        $cmd_type: path,
+        $command: expr,
+        $cwd: expr,
+        $sandbox_policy: expr,
+        $stdio_policy: expr
+    ) => {{
+        // For now, we take `SandboxPolicy` as a parameter to spawn_child() because
+        // we need to determine whether to set the
+        // `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` environment variable.
+        // Ultimately, we should be stricter about the environment variables that
+        // are set for the command (as we are when spawning an MCP server), so
+        // instead of SandboxPolicy, we should take the exact env to use for the
+        // Command (i.e., `env_clear().envs(env)`).
+        if $command.is_empty() {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "command args are empty",
+            ));
+        }
 
-    // Do not create a file descriptor for stdin because otherwise some
-    // commands may hang forever waiting for input. For example, ripgrep has
-    // a heuristic where it may try to read from stdin as explained here:
-    // https://github.com/BurntSushi/ripgrep/blob/e2362d4d5185d02fa857bf381e7bd52e66fafc73/crates/core/flags/hiargs.rs#L1101-L1103
-    cmd.stdin(Stdio::null());
+        let mut cmd = <$cmd_type>::new(&$command[0]);
+        cmd.args(&$command[1..]);
+        cmd.current_dir($cwd);
 
-    cmd.stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .kill_on_drop(true)
-        .spawn()
+        if !$sandbox_policy.has_full_network_access() {
+            cmd.env(CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR, "1");
+        }
+
+        match $stdio_policy {
+            StdioPolicy::RedirectForShellTool => {
+                // Do not create a file descriptor for stdin because otherwise some
+                // commands may hang forever waiting for input. For example, ripgrep has
+                // a heuristic where it may try to read from stdin as explained here:
+                // https://github.com/BurntSushi/ripgrep/blob/e2362d4d5185d02fa857bf381e7bd52e66fafc73/crates/core/flags/hiargs.rs#L1101-L1103
+                cmd.stdin(Stdio::null());
+
+                cmd.stdout(Stdio::piped()).stderr(Stdio::piped());
+            }
+            StdioPolicy::Inherit => {
+                // Inherit stdin, stdout, and stderr from the parent process.
+                cmd.stdin(Stdio::inherit())
+                    .stdout(Stdio::inherit())
+                    .stderr(Stdio::inherit());
+            }
+        }
+
+        std::io::Result::<$cmd_type>::Ok(cmd)
+    }};
+}
+
+/// Spawns the appropriate child process for the ExecParams and SandboxPolicy,
+/// ensuring the args and environment variables used to create the `Command`
+/// (and `Child`) honor the configuration.
+pub(crate) async fn spawn_child_async(
+    command: Vec<String>,
+    cwd: PathBuf,
+    sandbox_policy: &SandboxPolicy,
+    stdio_policy: StdioPolicy,
+) -> std::io::Result<Child> {
+    let mut cmd = configure_command!(Command, command, cwd, sandbox_policy, stdio_policy)?;
+    cmd.kill_on_drop(true).spawn()
+}
+
+/// Alternative version of `spawn_child_async()` that returns
+/// `std::process::Child` instead of `tokio::process::Child`. This is useful for
+/// spawning a child process in a thread that is not running a Tokio runtime.
+pub fn spawn_child_sync(
+    command: Vec<String>,
+    cwd: PathBuf,
+    sandbox_policy: &SandboxPolicy,
+    stdio_policy: StdioPolicy,
+) -> std::io::Result<std::process::Child> {
+    let mut cmd = configure_command!(
+        std::process::Command,
+        command,
+        cwd,
+        sandbox_policy,
+        stdio_policy
+    )?;
+    cmd.spawn()
 }
 
 /// Consumes the output of a child process, truncating it so it is suitable for
 /// use as the output of a `shell` tool call. Also enforces specified timeout.
-async fn consume_truncated_output(
+pub(crate) async fn consume_truncated_output(
     mut child: Child,
     ctrl_c: Arc<Notify>,
     timeout_ms: Option<u64>,
 ) -> Result<RawExecToolCallOutput> {
+    // Both stdout and stderr were configured with `Stdio::piped()`
+    // above, therefore `take()` should normally return `Some`.  If it doesn't
+    // we treat it as an exceptional I/O error
+
+    let stdout_reader = child.stdout.take().ok_or_else(|| {
+        CodexErr::Io(io::Error::other(
+            "stdout pipe was unexpectedly not available",
+        ))
+    })?;
+    let stderr_reader = child.stderr.take().ok_or_else(|| {
+        CodexErr::Io(io::Error::other(
+            "stderr pipe was unexpectedly not available",
+        ))
+    })?;
+
     let stdout_handle = tokio::spawn(read_capped(
-        BufReader::new(child.stdout.take().expect("stdout is not piped")),
+        BufReader::new(stdout_reader),
         MAX_STREAM_OUTPUT,
         MAX_STREAM_OUTPUT_LINES,
     ));
     let stderr_handle = tokio::spawn(read_capped(
-        BufReader::new(child.stderr.take().expect("stderr is not piped")),
+        BufReader::new(stderr_reader),
         MAX_STREAM_OUTPUT,
         MAX_STREAM_OUTPUT_LINES,
     ));

codex-rs/core/src/exec_linux.rs

@@ -0,0 +1,77 @@
+use std::io;
+use std::path::Path;
+use std::sync::Arc;
+
+use crate::error::CodexErr;
+use crate::error::Result;
+use crate::exec::ExecParams;
+use crate::exec::RawExecToolCallOutput;
+use crate::exec::StdioPolicy;
+use crate::exec::consume_truncated_output;
+use crate::exec::spawn_child_async;
+use crate::protocol::SandboxPolicy;
+
+use tokio::sync::Notify;
+
+pub fn exec_linux(
+    params: ExecParams,
+    ctrl_c: Arc<Notify>,
+    sandbox_policy: &SandboxPolicy,
+) -> Result<RawExecToolCallOutput> {
+    // Allow READ on /
+    // Allow WRITE on /dev/null
+    let ctrl_c_copy = ctrl_c.clone();
+    let sandbox_policy = sandbox_policy.clone();
+
+    // Isolate thread to run the sandbox from
+    let tool_call_output = std::thread::spawn(move || {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()?;
+
+        rt.block_on(async {
+            let ExecParams {
+                command,
+                cwd,
+                timeout_ms,
+            } = params;
+            apply_sandbox_policy_to_current_thread(&sandbox_policy, &cwd)?;
+            let child = spawn_child_async(
+                command,
+                cwd,
+                &sandbox_policy,
+                StdioPolicy::RedirectForShellTool,
+            )
+            .await?;
+            consume_truncated_output(child, ctrl_c_copy, timeout_ms).await
+        })
+    })
+    .join();
+
+    match tool_call_output {
+        Ok(Ok(output)) => Ok(output),
+        Ok(Err(e)) => Err(e),
+        Err(e) => Err(CodexErr::Io(io::Error::other(format!(
+            "thread join failed: {e:?}"
+        )))),
+    }
+}
+
+#[cfg(target_os = "linux")]
+pub fn apply_sandbox_policy_to_current_thread(
+    sandbox_policy: &SandboxPolicy,
+    cwd: &Path,
+) -> Result<()> {
+    crate::landlock::apply_sandbox_policy_to_current_thread(sandbox_policy, cwd)
+}
+
+#[cfg(not(target_os = "linux"))]
+pub fn apply_sandbox_policy_to_current_thread(
+    _sandbox_policy: &SandboxPolicy,
+    _cwd: &Path,
+) -> Result<()> {
+    Err(CodexErr::Io(io::Error::new(
+        io::ErrorKind::InvalidInput,
+        "linux sandbox is not supported on this platform",
+    )))
+}

codex-rs/core/src/flags.rs

@@ -3,7 +3,7 @@ use std::time::Duration;
 use env_flags::env_flags;
 
 env_flags! {
-    pub OPENAI_DEFAULT_MODEL: &str = "o3";
+    pub OPENAI_DEFAULT_MODEL: &str = "codex-mini-latest";
     pub OPENAI_API_BASE: &str = "https://api.openai.com/v1";
 
     /// Fallback when the provider-specific key is not set.

codex-rs/core/src/is_safe_command.rs

@@ -75,6 +75,7 @@ fn is_safe_to_call_with_exec(command: &[String]) -> bool {
 fn try_parse_bash(bash_lc_arg: &str) -> Option<Tree> {
     let lang = BASH.into();
     let mut parser = Parser::new();
+    #[expect(clippy::expect_used)]
     parser.set_language(&lang).expect("load bash grammar");
 
     let old_tree: Option<&Tree> = None;

codex-rs/core/src/landlock.rs

@@ -1,15 +1,10 @@
 use std::collections::BTreeMap;
-use std::io;
 use std::path::Path;
 use std::path::PathBuf;
-use std::sync::Arc;
 
 use crate::error::CodexErr;
 use crate::error::Result;
 use crate::error::SandboxErr;
-use crate::exec::ExecParams;
-use crate::exec::RawExecToolCallOutput;
-use crate::exec::exec;
 use crate::protocol::SandboxPolicy;
 
 use landlock::ABI;
@@ -29,46 +24,11 @@ use seccompiler::SeccompFilter;
 use seccompiler::SeccompRule;
 use seccompiler::TargetArch;
 use seccompiler::apply_filter;
-use tokio::sync::Notify;
-
-pub async fn exec_linux(
-    params: ExecParams,
-    ctrl_c: Arc<Notify>,
-    sandbox_policy: &SandboxPolicy,
-) -> Result<RawExecToolCallOutput> {
-    // Allow READ on /
-    // Allow WRITE on /dev/null
-    let ctrl_c_copy = ctrl_c.clone();
-    let sandbox_policy = sandbox_policy.clone();
-
-    // Isolate thread to run the sandbox from
-    let tool_call_output = std::thread::spawn(move || {
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .expect("Failed to create runtime");
-
-        rt.block_on(async {
-            apply_sandbox_policy_to_current_thread(sandbox_policy, &params.cwd)?;
-            exec(params, ctrl_c_copy).await
-        })
-    })
-    .join();
-
-    match tool_call_output {
-        Ok(Ok(output)) => Ok(output),
-        Ok(Err(e)) => Err(e),
-        Err(e) => Err(CodexErr::Io(io::Error::new(
-            io::ErrorKind::Other,
-            format!("thread join failed: {e:?}"),
-        ))),
-    }
-}
 
 /// Apply sandbox policies inside this thread so only the child inherits
 /// them, not the entire CLI process.
-pub fn apply_sandbox_policy_to_current_thread(
-    sandbox_policy: SandboxPolicy,
+pub(crate) fn apply_sandbox_policy_to_current_thread(
+    sandbox_policy: &SandboxPolicy,
     cwd: &Path,
 ) -> Result<()> {
     if !sandbox_policy.has_full_network_access() {
@@ -180,7 +140,7 @@ fn install_network_seccomp_filter_on_current_thread() -> std::result::Result<(),
 
 #[cfg(test)]
 mod tests {
-    #![allow(clippy::unwrap_used)]
+    #![expect(clippy::unwrap_used, clippy::expect_used)]
 
     use super::*;
     use crate::exec::ExecParams;
@@ -234,7 +194,14 @@ mod tests {
 
     #[tokio::test]
     async fn test_dev_null_write() {
-        run_cmd(&["echo", "blah", ">", "/dev/null"], &[], 200).await;
+        run_cmd(
+            &["bash", "-lc", "echo blah > /dev/null"],
+            &[],
+            // We have seen timeouts when running this test in CI on GitHub,
+            // so we are using a generous timeout until we can diagnose further.
+            1_000,
+        )
+        .await;
     }
 
     #[tokio::test]

codex-rs/core/src/lib.rs

@@ -1,32 +1,35 @@
 //! Root of the `codex-core` library.
 
 // Prevent accidental direct writes to stdout/stderr in library code. All
-// user‑visible output must go through the appropriate abstraction (e.g.,
+// user-visible output must go through the appropriate abstraction (e.g.,
 // the TUI or the tracing stack).
 #![deny(clippy::print_stdout, clippy::print_stderr)]
 
 mod chat_completions;
-
 mod client;
 mod client_common;
 pub mod codex;
 pub use codex::Codex;
 pub mod codex_wrapper;
 pub mod config;
+pub mod config_profile;
+pub mod config_types;
 mod conversation_history;
 pub mod error;
 pub mod exec;
+pub mod exec_linux;
 mod flags;
 mod is_safe_command;
 #[cfg(target_os = "linux")]
-pub mod linux;
+pub mod landlock;
 mod mcp_connection_manager;
-pub mod mcp_server_config;
 mod mcp_tool_call;
+mod message_history;
 mod model_provider_info;
 pub use model_provider_info::ModelProviderInfo;
 pub use model_provider_info::WireApi;
 mod models;
+mod project_doc;
 pub mod protocol;
 mod rollout;
 mod safety;

codex-rs/core/src/mcp_connection_manager.rs

@@ -13,11 +13,13 @@ use anyhow::Context;
 use anyhow::Result;
 use anyhow::anyhow;
 use codex_mcp_client::McpClient;
+use mcp_types::ClientCapabilities;
+use mcp_types::Implementation;
 use mcp_types::Tool;
 use tokio::task::JoinSet;
 use tracing::info;
 
-use crate::mcp_server_config::McpServerConfig;
+use crate::config_types::McpServerConfig;
 
 /// Delimiter used to separate the server name from the tool name in a fully
 /// qualified tool name.
@@ -83,7 +85,33 @@ impl McpConnectionManager {
             join_set.spawn(async move {
                 let McpServerConfig { command, args, env } = cfg;
                 let client_res = McpClient::new_stdio_client(command, args, env).await;
-                (server_name, client_res)
+                match client_res {
+                    Ok(client) => {
+                        // Initialize the client.
+                        let params = mcp_types::InitializeRequestParams {
+                            capabilities: ClientCapabilities {
+                                experimental: None,
+                                roots: None,
+                                sampling: None,
+                            },
+                            client_info: Implementation {
+                                name: "codex-mcp-client".to_owned(),
+                                version: env!("CARGO_PKG_VERSION").to_owned(),
+                            },
+                            protocol_version: mcp_types::MCP_SCHEMA_VERSION.to_owned(),
+                        };
+                        let initialize_notification_params = None;
+                        let timeout = Some(Duration::from_secs(10));
+                        match client
+                            .initialize(params, initialize_notification_params, timeout)
+                            .await
+                        {
+                            Ok(_response) => (server_name, Ok(client)),
+                            Err(e) => (server_name, Err(e)),
+                        }
+                    }
+                    Err(e) => (server_name, Err(e.into())),
+                }
             });
         }
 
@@ -99,7 +127,7 @@ impl McpConnectionManager {
                     clients.insert(server_name, std::sync::Arc::new(client));
                 }
                 Err(e) => {
-                    errors.insert(server_name, e.into());
+                    errors.insert(server_name, e);
                 }
             }
         }

codex-rs/core/src/mcp_server_config.rs

@@ -1,14 +0,0 @@
-use std::collections::HashMap;
-
-use serde::Deserialize;
-
-#[derive(Deserialize, Debug, Clone)]
-pub struct McpServerConfig {
-    pub command: String,
-
-    #[serde(default)]
-    pub args: Vec<String>,
-
-    #[serde(default)]
-    pub env: Option<HashMap<String, String>>,
-}

codex-rs/core/src/mcp_tool_call.rs

@@ -7,6 +7,8 @@ use crate::models::FunctionCallOutputPayload;
 use crate::models::ResponseInputItem;
 use crate::protocol::Event;
 use crate::protocol::EventMsg;
+use crate::protocol::McpToolCallBeginEvent;
+use crate::protocol::McpToolCallEndEvent;
 
 /// Handles the specified tool call dispatches the appropriate
 /// `McpToolCallBegin` and `McpToolCallEnd` events to the `Session`.
@@ -39,12 +41,12 @@ pub(crate) async fn handle_mcp_tool_call(
         }
     };
 
-    let tool_call_begin_event = EventMsg::McpToolCallBegin {
+    let tool_call_begin_event = EventMsg::McpToolCallBegin(McpToolCallBeginEvent {
         call_id: call_id.clone(),
         server: server.clone(),
         tool: tool_name.clone(),
         arguments: arguments_value.clone(),
-    };
+    });
     notify_mcp_tool_call_event(sess, sub_id, tool_call_begin_event).await;
 
     // Perform the tool call.
@@ -53,29 +55,29 @@ pub(crate) async fn handle_mcp_tool_call(
         .await
     {
         Ok(result) => (
-            EventMsg::McpToolCallEnd {
+            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
                 call_id,
                 success: !result.is_error.unwrap_or(false),
                 result: Some(result),
-            },
+            }),
             None,
         ),
         Err(e) => (
-            EventMsg::McpToolCallEnd {
+            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
                 call_id,
                 success: false,
                 result: None,
-            },
+            }),
             Some(e),
         ),
     };
 
     notify_mcp_tool_call_event(sess, sub_id, tool_call_end_event.clone()).await;
-    let EventMsg::McpToolCallEnd {
+    let EventMsg::McpToolCallEnd(McpToolCallEndEvent {
         call_id,
         success,
         result,
-    } = tool_call_end_event
+    }) = tool_call_end_event
     else {
         unimplemented!("unexpected event type");
     };

codex-rs/core/src/message_history.rs

@@ -0,0 +1,297 @@
+//! Persistence layer for the global, append-only *message history* file.
+//!
+//! The history is stored at `~/.codex/history.jsonl` with **one JSON object per
+//! line** so that it can be efficiently appended to and parsed with standard
+//! JSON-Lines tooling. Each record has the following schema:
+//!
+//! ````text
+//! {"session_id":"<uuid>","ts":<unix_seconds>,"text":"<message>"}
+//! ````
+//!
+//! To minimise the chance of interleaved writes when multiple processes are
+//! appending concurrently, callers should *prepare the full line* (record +
+//! trailing `\n`) and write it with a **single `write(2)` system call** while
+//! the file descriptor is opened with the `O_APPEND` flag. POSIX guarantees
+//! that writes up to `PIPE_BUF` bytes are atomic in that case.
+
+use std::fs::File;
+use std::fs::OpenOptions;
+use std::io::Result;
+use std::io::Write;
+use std::path::PathBuf;
+
+use serde::Deserialize;
+use serde::Serialize;
+use std::time::Duration;
+use tokio::fs;
+use tokio::io::AsyncReadExt;
+use uuid::Uuid;
+
+use crate::config::Config;
+use crate::config_types::HistoryPersistence;
+
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+/// Filename that stores the message history inside `~/.codex`.
+const HISTORY_FILENAME: &str = "history.jsonl";
+
+const MAX_RETRIES: usize = 10;
+const RETRY_SLEEP: Duration = Duration::from_millis(100);
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct HistoryEntry {
+    pub session_id: String,
+    pub ts: u64,
+    pub text: String,
+}
+
+fn history_filepath(config: &Config) -> PathBuf {
+    let mut path = config.codex_home.clone();
+    path.push(HISTORY_FILENAME);
+    path
+}
+
+/// Append a `text` entry associated with `session_id` to the history file. Uses
+/// advisory file locking to ensure that concurrent writes do not interleave,
+/// which entails a small amount of blocking I/O internally.
+pub(crate) async fn append_entry(text: &str, session_id: &Uuid, config: &Config) -> Result<()> {
+    match config.history.persistence {
+        HistoryPersistence::SaveAll => {
+            // Save everything: proceed.
+        }
+        HistoryPersistence::None => {
+            // No history persistence requested.
+            return Ok(());
+        }
+    }
+
+    // TODO: check `text` for sensitive patterns
+
+    // Resolve `~/.codex/history.jsonl` and ensure the parent directory exists.
+    let path = history_filepath(config);
+    if let Some(parent) = path.parent() {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+
+    // Compute timestamp (seconds since the Unix epoch).
+    let ts = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_err(|e| std::io::Error::other(format!("system clock before Unix epoch: {e}")))?
+        .as_secs();
+
+    // Construct the JSON line first so we can write it in a single syscall.
+    let entry = HistoryEntry {
+        session_id: session_id.to_string(),
+        ts,
+        text: text.to_string(),
+    };
+    let mut line = serde_json::to_string(&entry)
+        .map_err(|e| std::io::Error::other(format!("failed to serialise history entry: {e}")))?;
+    line.push('\n');
+
+    // Open in append-only mode.
+    let mut options = OpenOptions::new();
+    options.append(true).read(true).create(true);
+    #[cfg(unix)]
+    {
+        options.mode(0o600);
+    }
+
+    let mut history_file = options.open(&path)?;
+
+    // Ensure permissions.
+    ensure_owner_only_permissions(&history_file).await?;
+
+    // Lock file.
+    acquire_exclusive_lock_with_retry(&history_file).await?;
+
+    // We use sync I/O with spawn_blocking() because we are using a
+    // [`std::fs::File`] instead of a [`tokio::fs::File`] to leverage an
+    // advisory file locking API that is not available in the async API.
+    tokio::task::spawn_blocking(move || -> Result<()> {
+        history_file.write_all(line.as_bytes())?;
+        history_file.flush()?;
+        Ok(())
+    })
+    .await??;
+
+    Ok(())
+}
+
+/// Attempt to acquire an exclusive advisory lock on `file`, retrying up to 10
+/// times if the lock is currently held by another process. This prevents a
+/// potential indefinite wait while still giving other writers some time to
+/// finish their operation.
+async fn acquire_exclusive_lock_with_retry(file: &std::fs::File) -> Result<()> {
+    use tokio::time::sleep;
+
+    for _ in 0..MAX_RETRIES {
+        match fs2::FileExt::try_lock_exclusive(file) {
+            Ok(()) => return Ok(()),
+            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+                sleep(RETRY_SLEEP).await;
+            }
+            Err(e) => return Err(e),
+        }
+    }
+
+    Err(std::io::Error::new(
+        std::io::ErrorKind::WouldBlock,
+        "could not acquire exclusive lock on history file after multiple attempts",
+    ))
+}
+
+/// Asynchronously fetch the history file's *identifier* (inode on Unix) and
+/// the current number of entries by counting newline characters.
+pub(crate) async fn history_metadata(config: &Config) -> (u64, usize) {
+    let path = history_filepath(config);
+
+    #[cfg(unix)]
+    let log_id = {
+        use std::os::unix::fs::MetadataExt;
+        // Obtain metadata (async) to get the identifier.
+        let meta = match fs::metadata(&path).await {
+            Ok(m) => m,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return (0, 0),
+            Err(_) => return (0, 0),
+        };
+        meta.ino()
+    };
+    #[cfg(not(unix))]
+    let log_id = 0u64;
+
+    // Open the file.
+    let mut file = match fs::File::open(&path).await {
+        Ok(f) => f,
+        Err(_) => return (log_id, 0),
+    };
+
+    // Count newline bytes.
+    let mut buf = [0u8; 8192];
+    let mut count = 0usize;
+    loop {
+        match file.read(&mut buf).await {
+            Ok(0) => break,
+            Ok(n) => {
+                count += buf[..n].iter().filter(|&&b| b == b'\n').count();
+            }
+            Err(_) => return (log_id, 0),
+        }
+    }
+
+    (log_id, count)
+}
+
+/// Given a `log_id` (on Unix this is the file's inode number) and a zero-based
+/// `offset`, return the corresponding `HistoryEntry` if the identifier matches
+/// the current history file **and** the requested offset exists. Any I/O or
+/// parsing errors are logged and result in `None`.
+///
+/// Note this function is not async because it uses a sync advisory file
+/// locking API.
+#[cfg(unix)]
+pub(crate) fn lookup(log_id: u64, offset: usize, config: &Config) -> Option<HistoryEntry> {
+    use std::io::BufRead;
+    use std::io::BufReader;
+    use std::os::unix::fs::MetadataExt;
+
+    let path = history_filepath(config);
+    let file: File = match OpenOptions::new().read(true).open(&path) {
+        Ok(f) => f,
+        Err(e) => {
+            tracing::warn!(error = %e, "failed to open history file");
+            return None;
+        }
+    };
+
+    let metadata = match file.metadata() {
+        Ok(m) => m,
+        Err(e) => {
+            tracing::warn!(error = %e, "failed to stat history file");
+            return None;
+        }
+    };
+
+    if metadata.ino() != log_id {
+        return None;
+    }
+
+    // Open & lock file for reading.
+    if let Err(e) = acquire_shared_lock_with_retry(&file) {
+        tracing::warn!(error = %e, "failed to acquire shared lock on history file");
+        return None;
+    }
+
+    let reader = BufReader::new(&file);
+    for (idx, line_res) in reader.lines().enumerate() {
+        let line = match line_res {
+            Ok(l) => l,
+            Err(e) => {
+                tracing::warn!(error = %e, "failed to read line from history file");
+                return None;
+            }
+        };
+
+        if idx == offset {
+            match serde_json::from_str::<HistoryEntry>(&line) {
+                Ok(entry) => return Some(entry),
+                Err(e) => {
+                    tracing::warn!(error = %e, "failed to parse history entry");
+                    return None;
+                }
+            }
+        }
+    }
+
+    None
+}
+
+/// Fallback stub for non-Unix systems: currently always returns `None`.
+#[cfg(not(unix))]
+pub(crate) fn lookup(log_id: u64, offset: usize, config: &Config) -> Option<HistoryEntry> {
+    let _ = (log_id, offset, config);
+    None
+}
+
+#[cfg(unix)]
+fn acquire_shared_lock_with_retry(file: &File) -> Result<()> {
+    for _ in 0..MAX_RETRIES {
+        match fs2::FileExt::try_lock_shared(file) {
+            Ok(()) => return Ok(()),
+            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+                std::thread::sleep(RETRY_SLEEP);
+            }
+            Err(e) => return Err(e),
+        }
+    }
+
+    Err(std::io::Error::new(
+        std::io::ErrorKind::WouldBlock,
+        "could not acquire shared lock on history file after multiple attempts",
+    ))
+}
+
+/// On Unix systems ensure the file permissions are `0o600` (rw-------). If the
+/// permissions cannot be changed the error is propagated to the caller.
+#[cfg(unix)]
+async fn ensure_owner_only_permissions(file: &File) -> Result<()> {
+    let metadata = file.metadata()?;
+    let current_mode = metadata.permissions().mode() & 0o777;
+    if current_mode != 0o600 {
+        let mut perms = metadata.permissions();
+        perms.set_mode(0o600);
+        let perms_clone = perms.clone();
+        let file_clone = file.try_clone()?;
+        tokio::task::spawn_blocking(move || file_clone.set_permissions(perms_clone)).await??;
+    }
+    Ok(())
+}
+
+#[cfg(not(unix))]
+async fn ensure_owner_only_permissions(_file: &File) -> Result<()> {
+    // For now, on non-Unix, simply succeed.
+    Ok(())
+}

codex-rs/core/src/model_provider_info.rs

@@ -29,7 +29,7 @@ pub enum WireApi {
 }
 
 /// Serializable representation of a provider definition.
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
 pub struct ModelProviderInfo {
     /// Friendly display name.
     pub name: String,