feat: show the version when starting Codex (#1182)

The TypeScript version of the CLI shows the version when it starts up,
which is helpful when users share screenshots (and nice to know, as a
user).

.github/actions/codex/.gitignore

@@ -0,0 +1 @@
+/node_modules/

.github/actions/codex/.prettierrc.toml

@@ -0,0 +1,8 @@
+printWidth = 80
+quoteProps = "consistent"
+semi = true
+tabWidth = 2
+trailingComma = "all"
+
+# Preserve existing behavior for markdown/text wrapping.
+proseWrap = "preserve"

.github/actions/codex/README.md

@@ -0,0 +1,140 @@
+# openai/codex-action
+
+`openai/codex-action` is a GitHub Action that facilitates the use of [Codex](https://github.com/openai/codex) on GitHub issues and pull requests. Using the action, associate **labels** to run Codex with the appropriate prompt for the given context. Codex will respond by posting comments or creating PRs, whichever you specify!
+
+Here is a sample workflow that uses `openai/codex-action`:
+
+```yaml
+name: Codex
+
+on:
+  issues:
+    types: [opened, labeled]
+  pull_request:
+    branches: [main]
+    types: [labeled]
+
+jobs:
+  codex:
+    if: ... # optional, but can be effective in conserving CI resources
+    runs-on: ubuntu-latest
+    # TODO(mbolin): Need to verify if/when `write` is necessary.
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      # By default, Codex runs network disabled using --full-auto, so perform
+      # any setup that requires network (such as installing dependencies)
+      # before openai/codex-action.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run Codex
+        uses: openai/codex-action@latest
+        with:
+          openai_api_key: ${{ secrets.CODEX_OPENAI_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+See sample usage in [`codex.yml`](../../workflows/codex.yml).
+
+## Triggering the Action
+
+Using the sample workflow above, we have:
+
+```yaml
+on:
+  issues:
+    types: [opened, labeled]
+  pull_request:
+    branches: [main]
+    types: [labeled]
+```
+
+which means our workflow will be triggered when any of the following events occur:
+
+- a label is added to an issue
+- a label is added to a pull request against the `main` branch
+
+### Label-Based Triggers
+
+To define a GitHub label that should trigger Codex, create a file named `.github/codex/labels/LABEL-NAME.md` in your repository where `LABEL-NAME` is the name of the label. The content of the file is the prompt template to use when the label is added (see more on [Prompt Template Variables](#prompt-template-variables) below).
+
+For example, if the file `.github/codex/labels/codex-review.md` exists, then:
+
+- Adding the `codex-review` label will trigger the workflow containing the `openai/codex-action` GitHub Action.
+- When `openai/codex-action` starts, it will replace the `codex-review` label with `codex-review-in-progress`.
+- When `openai/codex-action` is finished, it will replace the `codex-review-in-progress` label with `codex-review-completed`.
+
+If Codex sees that either `codex-review-in-progress` or `codex-review-completed` is already present, it will not perform the action.
+
+As determined by the [default config](./src/default-label-config.ts), Codex will act on the following labels by default:
+
+- Adding the `codex-review` label to a pull request will have Codex review the PR and add it to the PR as a comment.
+- Adding the `codex-triage` label to an issue will have Codex investigate the issue and report its findings as a comment.
+- Adding the `codex-issue-fix` label to an issue will have Codex attempt to fix the issue and create a PR wit the fix, if any.
+
+## Action Inputs
+
+The `openai/codex-action` GitHub Action takes the following inputs
+
+### `openai_api_key` (required)
+
+Set your `OPENAI_API_KEY` as a [repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). See **Secrets and varaibles** then **Actions** in the settings for your GitHub repo.
+
+Note that the secret name does not have to be `OPENAI_API_KEY`. For example, you might want to name it `CODEX_OPENAI_API_KEY` and then configure it on `openai/codex-action` as follows:
+
+```yaml
+openai_api_key: ${{ secrets.CODEX_OPENAI_API_KEY }}
+```
+
+### `github_token` (required)
+
+This is required so that Codex can post a comment or create a PR. Set this value on the action as follows:
+
+```yaml
+github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### `codex_args`
+
+A whitespace-delimited list of arguments to pass to Codex. Defaults to `--full-auto`, but if you want to override the default model to use `o3`:
+
+```yaml
+codex_args: "--full-auto --model o3"
+```
+
+For more complex configurations, use the `codex_home` input.
+
+### `codex_home`
+
+If set, the value to use for the `$CODEX_HOME` environment variable when running Codex. As explained [in the docs](https://github.com/openai/codex/tree/main/codex-rs#readme), this folder can contain the `config.toml` to configure Codex, custom instructions, and log files.
+
+This should be a relative path within your repo.
+
+## Prompt Template Variables
+
+As shown above, `"prompt"` and `"promptPath"` are used to define prompt templates that will be populated and passed to Codex in response to certain events. All template variables are of the form `{CODEX_ACTION_...}` and the supported values are defined below.
+
+### `CODEX_ACTION_ISSUE_TITLE`
+
+If the action was triggered on a GitHub issue, this is the issue title.
+
+Specifically it is read as the `.issue.title` from the `$GITHUB_EVENT_PATH`.
+
+### `CODEX_ACTION_ISSUE_BODY`
+
+If the action was triggered on a GitHub issue, this is the issue body.
+
+Specifically it is read as the `.issue.body` from the `$GITHUB_EVENT_PATH`.
+
+### `CODEX_ACTION_GITHUB_EVENT_PATH`
+
+The value of the `$GITHUB_EVENT_PATH` environment variable, which is the path to the file that contains the JSON payload for the event that triggered the workflow. Codex can use `jq` to read only the fields of interest from this file.
+
+### `CODEX_ACTION_PR_DIFF`
+
+If the action was triggered on a pull request, this is the diff between the base and head commits of the PR. It is the output from `git diff`.
+
+Note that the content of the diff could be quite large, so is generally safer to point Codex at `CODEX_ACTION_GITHUB_EVENT_PATH` and let it decide how it wants to explore the change.

.github/actions/codex/action.yml

@@ -0,0 +1,124 @@
+name: "Codex [reusable action]"
+description: "A reusable action that runs a Codex model."
+
+inputs:
+  openai_api_key:
+    description: "The value to use as the OPENAI_API_KEY environment variable when running Codex."
+    required: true
+  trigger_phrase:
+    description: "Text to trigger Codex from a PR/issue body or comment."
+    required: false
+    default: ""
+  github_token:
+    description: "Token so Codex can comment on the PR or issue."
+    required: true
+  codex_args:
+    description: "A whitespace-delimited list of arguments to pass to Codex. Due to limitations in YAML, arguments with spaces are not supported. For more complex configurations, use the `codex_home` input."
+    required: false
+    default: "--full-auto"
+  codex_home:
+    description: "Value to use as the CODEX_HOME environment variable when running Codex."
+    required: false
+  codex_release_tag:
+    description: "The release tag of the Codex model to run."
+    required: false
+    default: "codex-rs-d519bd8bbd1e1fd9efdc5d68cf7bebdec0dd0f28-1-rust-v0.0.2505270918"
+
+runs:
+  using: "composite"
+  steps:
+    # Do this in Bash so we do not even bother to install Bun if the sender does
+    # not have write access to the repo.
+    - name: Verify user has write access to the repo.
+      env:
+        GH_TOKEN: ${{ github.token }}
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        PERMISSION=$(gh api \
+          "/repos/${GITHUB_REPOSITORY}/collaborators/${{ github.event.sender.login }}/permission" \
+          | jq -r '.permission')
+
+        if [[ "$PERMISSION" != "admin" && "$PERMISSION" != "write" ]]; then
+          exit 1
+        fi
+
+    - name: Download Codex
+      env:
+        GH_TOKEN: ${{ github.token }}
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # Determine OS/arch and corresponding Codex artifact name.
+        uname_s=$(uname -s)
+        uname_m=$(uname -m)
+
+        case "$uname_s" in
+          Linux*)   os="linux" ;;
+          Darwin*)  os="apple-darwin" ;;
+          *) echo "Unsupported operating system: $uname_s"; exit 1 ;;
+        esac
+
+        case "$uname_m" in
+          x86_64*) arch="x86_64" ;;
+          arm64*|aarch64*) arch="aarch64" ;;
+          *) echo "Unsupported architecture: $uname_m"; exit 1 ;;
+        esac
+
+        # linux builds differentiate between musl and gnu.
+        if [[ "$os" == "linux" ]]; then
+          if [[ "$arch" == "x86_64" ]]; then
+            triple="${arch}-unknown-linux-musl"
+          else
+            # Only other supported linux build is aarch64 gnu.
+            triple="${arch}-unknown-linux-gnu"
+          fi
+        else
+          # macOS
+          triple="${arch}-apple-darwin"
+        fi
+
+        # Note that if we start baking version numbers into the artifact name,
+        # we will need to update this action.yml file to match.
+        artifact="codex-exec-${triple}.tar.gz"
+
+        gh release download ${{ inputs.codex_release_tag }} --repo openai/codex \
+          --pattern "$artifact" --output - \
+        | tar xzO > /usr/local/bin/codex-exec
+        chmod +x /usr/local/bin/codex-exec
+
+        # Display Codex version to confirm binary integrity; ensure we point it
+        # at the checked-out repository via --cd so that any subsequent commands
+        # use the correct working directory.
+        codex-exec --cd "$GITHUB_WORKSPACE" --version
+
+    - name: Install Bun
+      uses: oven-sh/setup-bun@v2
+      with:
+        bun-version: 1.2.11
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        cd ${{ github.action_path }}
+        bun install --production
+
+    - name: Run Codex
+      shell: bash
+      run: bun run ${{ github.action_path }}/src/main.ts
+      # Process args plus environment variables often have a max of 128 KiB,
+      # so we should fit within that limit?
+      env:
+        INPUT_CODEX_ARGS: ${{ inputs.codex_args || '' }}
+        INPUT_CODEX_HOME: ${{ inputs.codex_home || ''}}
+        INPUT_TRIGGER_PHRASE: ${{ inputs.trigger_phrase || '' }}
+        OPENAI_API_KEY: ${{ inputs.openai_api_key }}
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+        GITHUB_EVENT_ACTION: ${{ github.event.action || '' }}
+        GITHUB_EVENT_LABEL_NAME: ${{ github.event.label.name || '' }}
+        GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number || '' }}
+        GITHUB_EVENT_ISSUE_BODY: ${{ github.event.issue.body || '' }}
+        GITHUB_EVENT_REVIEW_BODY: ${{ github.event.review.body || '' }}
+        GITHUB_EVENT_COMMENT_BODY: ${{ github.event.comment.body || '' }}

.github/actions/codex/bun.lock

@@ -0,0 +1,85 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "codex-action",
+      "dependencies": {
+        "@actions/core": "^1.11.1",
+        "@actions/github": "^6.0.1",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.2.11",
+        "@types/node": "^22.15.21",
+        "prettier": "^3.5.3",
+        "typescript": "^5.8.3",
+      },
+    },
+  },
+  "packages": {
+    "@actions/core": ["@actions/core@1.11.1", "", { "dependencies": { "@actions/exec": "^1.1.1", "@actions/http-client": "^2.0.1" } }, "sha512-hXJCSrkwfA46Vd9Z3q4cpEpHB1rL5NG04+/rbqW9d3+CSvtB1tYe8UTpAlixa1vj0m/ULglfEK2UKxMGxCxv5A=="],
+
+    "@actions/exec": ["@actions/exec@1.1.1", "", { "dependencies": { "@actions/io": "^1.0.1" } }, "sha512-+sCcHHbVdk93a0XT19ECtO/gIXoxvdsgQLzb2fE2/5sIZmWQuluYyjPQtrtTHdU1YzTZ7bAPN4sITq2xi1679w=="],
+
+    "@actions/github": ["@actions/github@6.0.1", "", { "dependencies": { "@actions/http-client": "^2.2.0", "@octokit/core": "^5.0.1", "@octokit/plugin-paginate-rest": "^9.2.2", "@octokit/plugin-rest-endpoint-methods": "^10.4.0", "@octokit/request": "^8.4.1", "@octokit/request-error": "^5.1.1", "undici": "^5.28.5" } }, "sha512-xbZVcaqD4XnQAe35qSQqskb3SqIAfRyLBrHMd/8TuL7hJSz2QtbDwnNM8zWx4zO5l2fnGtseNE3MbEvD7BxVMw=="],
+
+    "@actions/http-client": ["@actions/http-client@2.2.3", "", { "dependencies": { "tunnel": "^0.0.6", "undici": "^5.25.4" } }, "sha512-mx8hyJi/hjFvbPokCg4uRd4ZX78t+YyRPtnKWwIl+RzNaVuFpQHfmlGVfsKEJN8LwTCvL+DfVgAM04XaHkm6bA=="],
+
+    "@actions/io": ["@actions/io@1.1.3", "", {}, "sha512-wi9JjgKLYS7U/z8PPbco+PvTb/nRWjeoFlJ1Qer83k/3C5PHQi28hiVdeE2kHXmIL99mQFawx8qt/JPjZilJ8Q=="],
+
+    "@fastify/busboy": ["@fastify/busboy@2.1.1", "", {}, "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA=="],
+
+    "@octokit/auth-token": ["@octokit/auth-token@4.0.0", "", {}, "sha512-tY/msAuJo6ARbK6SPIxZrPBms3xPbfwBrulZe0Wtr/DIY9lje2HeV1uoebShn6mx7SjCHif6EjMvoREj+gZ+SA=="],
+
+    "@octokit/core": ["@octokit/core@5.2.1", "", { "dependencies": { "@octokit/auth-token": "^4.0.0", "@octokit/graphql": "^7.1.0", "@octokit/request": "^8.4.1", "@octokit/request-error": "^5.1.1", "@octokit/types": "^13.0.0", "before-after-hook": "^2.2.0", "universal-user-agent": "^6.0.0" } }, "sha512-dKYCMuPO1bmrpuogcjQ8z7ICCH3FP6WmxpwC03yjzGfZhj9fTJg6+bS1+UAplekbN2C+M61UNllGOOoAfGCrdQ=="],
+
+    "@octokit/endpoint": ["@octokit/endpoint@9.0.6", "", { "dependencies": { "@octokit/types": "^13.1.0", "universal-user-agent": "^6.0.0" } }, "sha512-H1fNTMA57HbkFESSt3Y9+FBICv+0jFceJFPWDePYlR/iMGrwM5ph+Dd4XRQs+8X+PUFURLQgX9ChPfhJ/1uNQw=="],
+
+    "@octokit/graphql": ["@octokit/graphql@7.1.1", "", { "dependencies": { "@octokit/request": "^8.4.1", "@octokit/types": "^13.0.0", "universal-user-agent": "^6.0.0" } }, "sha512-3mkDltSfcDUoa176nlGoA32RGjeWjl3K7F/BwHwRMJUW/IteSa4bnSV8p2ThNkcIcZU2umkZWxwETSSCJf2Q7g=="],
+
+    "@octokit/openapi-types": ["@octokit/openapi-types@24.2.0", "", {}, "sha512-9sIH3nSUttelJSXUrmGzl7QUBFul0/mB8HRYl3fOlgHbIWG+WnYDXU3v/2zMtAvuzZ/ed00Ei6on975FhBfzrg=="],
+
+    "@octokit/plugin-paginate-rest": ["@octokit/plugin-paginate-rest@9.2.2", "", { "dependencies": { "@octokit/types": "^12.6.0" }, "peerDependencies": { "@octokit/core": "5" } }, "sha512-u3KYkGF7GcZnSD/3UP0S7K5XUFT2FkOQdcfXZGZQPGv3lm4F2Xbf71lvjldr8c1H3nNbF+33cLEkWYbokGWqiQ=="],
+
+    "@octokit/plugin-rest-endpoint-methods": ["@octokit/plugin-rest-endpoint-methods@10.4.1", "", { "dependencies": { "@octokit/types": "^12.6.0" }, "peerDependencies": { "@octokit/core": "5" } }, "sha512-xV1b+ceKV9KytQe3zCVqjg+8GTGfDYwaT1ATU5isiUyVtlVAO3HNdzpS4sr4GBx4hxQ46s7ITtZrAsxG22+rVg=="],
+
+    "@octokit/request": ["@octokit/request@8.4.1", "", { "dependencies": { "@octokit/endpoint": "^9.0.6", "@octokit/request-error": "^5.1.1", "@octokit/types": "^13.1.0", "universal-user-agent": "^6.0.0" } }, "sha512-qnB2+SY3hkCmBxZsR/MPCybNmbJe4KAlfWErXq+rBKkQJlbjdJeS85VI9r8UqeLYLvnAenU8Q1okM/0MBsAGXw=="],
+
+    "@octokit/request-error": ["@octokit/request-error@5.1.1", "", { "dependencies": { "@octokit/types": "^13.1.0", "deprecation": "^2.0.0", "once": "^1.4.0" } }, "sha512-v9iyEQJH6ZntoENr9/yXxjuezh4My67CBSu9r6Ve/05Iu5gNgnisNWOsoJHTP6k0Rr0+HQIpnH+kyammu90q/g=="],
+
+    "@octokit/types": ["@octokit/types@13.10.0", "", { "dependencies": { "@octokit/openapi-types": "^24.2.0" } }, "sha512-ifLaO34EbbPj0Xgro4G5lP5asESjwHracYJvVaPIyXMuiuXLlhic3S47cBdTb+jfODkTE5YtGCLt3Ay3+J97sA=="],
+
+    "@types/bun": ["@types/bun@1.2.13", "", { "dependencies": { "bun-types": "1.2.13" } }, "sha512-u6vXep/i9VBxoJl3GjZsl/BFIsvML8DfVDO0RYLEwtSZSp981kEO1V5NwRcO1CPJ7AmvpbnDCiMKo3JvbDEjAg=="],
+
+    "@types/node": ["@types/node@22.15.21", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-EV/37Td6c+MgKAbkcLG6vqZ2zEYHD7bvSrzqqs2RIhbA6w3x+Dqz8MZM3sP6kGTeLrdoOgKZe+Xja7tUB2DNkQ=="],
+
+    "before-after-hook": ["before-after-hook@2.2.3", "", {}, "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="],
+
+    "bun-types": ["bun-types@1.2.13", "", { "dependencies": { "@types/node": "*" } }, "sha512-rRjA1T6n7wto4gxhAO/ErZEtOXyEZEmnIHQfl0Dt1QQSB4QV0iP6BZ9/YB5fZaHFQ2dwHFrmPaRQ9GGMX01k9Q=="],
+
+    "deprecation": ["deprecation@2.3.1", "", {}, "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "prettier": ["prettier@3.5.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw=="],
+
+    "tunnel": ["tunnel@0.0.6", "", {}, "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici": ["undici@5.29.0", "", { "dependencies": { "@fastify/busboy": "^2.0.0" } }, "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg=="],
+
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+    "universal-user-agent": ["universal-user-agent@6.0.1", "", {}, "sha512-yCzhz6FN2wU1NiiQRogkTQszlQSlpWaw8SvVegAc+bDxbzHgh1vX8uIe8OYyMH6DwH+sdTJsgMl36+mSMdRJIQ=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
+    "@octokit/plugin-paginate-rest/@octokit/types": ["@octokit/types@12.6.0", "", { "dependencies": { "@octokit/openapi-types": "^20.0.0" } }, "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw=="],
+
+    "@octokit/plugin-rest-endpoint-methods/@octokit/types": ["@octokit/types@12.6.0", "", { "dependencies": { "@octokit/openapi-types": "^20.0.0" } }, "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw=="],
+
+    "@octokit/plugin-paginate-rest/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@20.0.0", "", {}, "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA=="],
+
+    "@octokit/plugin-rest-endpoint-methods/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@20.0.0", "", {}, "sha512-EtqRBEjp1dL/15V7WiX5LJMIxxkdiGJnabzYx5Apx4FkQIFgAfKumXeYAqqJCj1s+BMX4cPFIFC4OLCR6stlnA=="],
+  }
+}

.github/actions/codex/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "codex-action",
+    "version": "0.0.0",
+    "private": true,
+    "scripts": {
+        "format": "prettier --check src",
+        "format:fix": "prettier --write src",
+        "test": "bun test",
+        "typecheck": "tsc"
+    },
+    "dependencies": {
+        "@actions/core": "^1.11.1",
+        "@actions/github": "^6.0.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.2.11",
+        "@types/node": "^22.15.21",
+        "prettier": "^3.5.3",
+        "typescript": "^5.8.3"
+    }
+}

.github/actions/codex/src/add-reaction.ts

@@ -0,0 +1,85 @@
+import * as github from "@actions/github";
+import type { EnvContext } from "./env-context";
+
+/**
+ * Add an "eyes" reaction to the entity (issue, issue comment, or pull request
+ * review comment) that triggered the current Codex invocation.
+ *
+ * The purpose is to provide immediate feedback to the user – similar to the
+ * *-in-progress label flow – indicating that the bot has acknowledged the
+ * request and is working on it.
+ *
+ * We attempt to add the reaction best suited for the current GitHub event:
+ *
+ *   • issues              → POST /repos/{owner}/{repo}/issues/{issue_number}/reactions
+ *   • issue_comment       → POST /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions
+ *   • pull_request_review_comment → POST /repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions
+ *
+ * If the specific target is unavailable (e.g. unexpected payload shape) we
+ * silently skip instead of failing the whole action because the reaction is
+ * merely cosmetic.
+ */
+export async function addEyesReaction(ctx: EnvContext): Promise<void> {
+  const octokit = ctx.getOctokit();
+  const { owner, repo } = github.context.repo;
+  const eventName = github.context.eventName;
+
+  try {
+    switch (eventName) {
+      case "issue_comment": {
+        const commentId = (github.context.payload as any)?.comment?.id;
+        if (commentId) {
+          await octokit.rest.reactions.createForIssueComment({
+            owner,
+            repo,
+            comment_id: commentId,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      case "pull_request_review_comment": {
+        const commentId = (github.context.payload as any)?.comment?.id;
+        if (commentId) {
+          await octokit.rest.reactions.createForPullRequestReviewComment({
+            owner,
+            repo,
+            comment_id: commentId,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      case "issues": {
+        const issueNumber = github.context.issue.number;
+        if (issueNumber) {
+          await octokit.rest.reactions.createForIssue({
+            owner,
+            repo,
+            issue_number: issueNumber,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      default: {
+        // Fallback: try to react to the issue/PR if we have a number.
+        const issueNumber = github.context.issue.number;
+        if (issueNumber) {
+          await octokit.rest.reactions.createForIssue({
+            owner,
+            repo,
+            issue_number: issueNumber,
+            content: "eyes",
+          });
+        }
+      }
+    }
+  } catch (error) {
+    // Do not fail the action if reaction creation fails – log and continue.
+    console.warn(`Failed to add \"eyes\" reaction: ${error}`);
+  }
+}

.github/actions/codex/src/comment.ts

@@ -0,0 +1,53 @@
+import type { EnvContext } from "./env-context";
+import { runCodex } from "./run-codex";
+import { postComment } from "./post-comment";
+import { addEyesReaction } from "./add-reaction";
+
+/**
+ * Handle `issue_comment` and `pull_request_review_comment` events once we know
+ * the action is supported.
+ */
+export async function onComment(ctx: EnvContext): Promise<void> {
+  const triggerPhrase = ctx.tryGet("INPUT_TRIGGER_PHRASE");
+  if (!triggerPhrase) {
+    console.warn("Empty trigger phrase: skipping.");
+    return;
+  }
+
+  // Attempt to get the body of the comment from the environment. Depending on
+  // the event type either `GITHUB_EVENT_COMMENT_BODY` (issue & PR comments) or
+  // `GITHUB_EVENT_REVIEW_BODY` (PR reviews) is set.
+  const commentBody =
+    ctx.tryGetNonEmpty("GITHUB_EVENT_COMMENT_BODY") ??
+    ctx.tryGetNonEmpty("GITHUB_EVENT_REVIEW_BODY") ??
+    ctx.tryGetNonEmpty("GITHUB_EVENT_ISSUE_BODY");
+
+  if (!commentBody) {
+    console.warn("Comment body not found in environment: skipping.");
+    return;
+  }
+
+  // Check if the trigger phrase is present.
+  if (!commentBody.includes(triggerPhrase)) {
+    console.log(
+      `Trigger phrase '${triggerPhrase}' not found: nothing to do for this comment.`,
+    );
+    return;
+  }
+
+  // Derive the prompt by removing the trigger phrase. Remove only the first
+  // occurrence to keep any additional occurrences that might be meaningful.
+  const prompt = commentBody.replace(triggerPhrase, "").trim();
+
+  if (prompt.length === 0) {
+    console.warn("Prompt is empty after removing trigger phrase: skipping");
+    return;
+  }
+
+  // Provide immediate feedback that we are working on the request.
+  await addEyesReaction(ctx);
+
+  // Run Codex and post the response as a new comment.
+  const lastMessage = await runCodex(prompt, ctx);
+  await postComment(lastMessage, ctx);
+}

.github/actions/codex/src/config.ts

@@ -0,0 +1,11 @@
+import { readdirSync, statSync } from "fs";
+import * as path from "path";
+
+export interface Config {
+  labels: Record<string, LabelConfig>;
+}
+
+export interface LabelConfig {
+  /** Returns the prompt template. */
+  getPromptTemplate(): string;
+}

.github/actions/codex/src/default-label-config.ts

@@ -0,0 +1,44 @@
+import type { Config } from "./config";
+
+export function getDefaultConfig(): Config {
+  return {
+    labels: {
+      "codex-investigate-issue": {
+        getPromptTemplate: () =>
+          `
+Troubleshoot whether the reported issue is valid.
+
+Provide a concise and respectful comment summarizing the findings.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}
+`.trim(),
+      },
+      "codex-code-review": {
+        getPromptTemplate: () =>
+          `
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the \`base\` and \`head\` refs that define this PR. Both refs are available locally.
+`.trim(),
+      },
+      "codex-attempt-fix": {
+        getPromptTemplate: () =>
+          `
+Attempt to solve the reported issue.
+
+If a code change is required, create a new branch, commit the fix, and open a pull-request that resolves the problem.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}
+`.trim(),
+      },
+    },
+  };
+}

.github/actions/codex/src/env-context.ts

@@ -0,0 +1,116 @@
+/*
+ * Centralised access to environment variables used by the Codex GitHub
+ * Action.
+ *
+ * To enable proper unit-testing we avoid reading from `process.env` at module
+ * initialisation time.  Instead a `EnvContext` object is created (usually from
+ * the real `process.env`) and passed around explicitly or – where that is not
+ * yet practical – imported as the shared `defaultContext` singleton. Tests can
+ * create their own context backed by a stubbed map of variables without having
+ * to mutate global state.
+ */
+
+import { fail } from "./fail";
+import * as github from "@actions/github";
+
+export interface EnvContext {
+  /**
+   * Return the value for a given environment variable or terminate the action
+   * via `fail` if it is missing / empty.
+   */
+  get(name: string): string;
+
+  /**
+   * Attempt to read an environment variable. Returns the value when present;
+   * otherwise returns undefined (does not call `fail`).
+   */
+  tryGet(name: string): string | undefined;
+
+  /**
+   * Attempt to read an environment variable. Returns non-empty string value or
+   * null if unset or empty string.
+   */
+  tryGetNonEmpty(name: string): string | null;
+
+  /**
+   * Return a memoised Octokit instance authenticated via the token resolved
+   * from the provided argument (when defined) or the environment variables
+   * `GITHUB_TOKEN`/`GH_TOKEN`.
+   *
+   * Subsequent calls return the same cached instance to avoid spawning
+   * multiple REST clients within a single action run.
+   */
+  getOctokit(token?: string): ReturnType<typeof github.getOctokit>;
+}
+
+/** Internal helper – *not* exported. */
+function _getRequiredEnv(
+  name: string,
+  env: Record<string, string | undefined>,
+): string | undefined {
+  const value = env[name];
+
+  // Avoid leaking secrets into logs while still logging non-secret variables.
+  if (name.endsWith("KEY") || name.endsWith("TOKEN")) {
+    if (value) {
+      console.log(`value for ${name} was found`);
+    }
+  } else {
+    console.log(`${name}=${value}`);
+  }
+
+  return value;
+}
+
+/** Create a context backed by the supplied environment map (defaults to `process.env`). */
+export function createEnvContext(
+  env: Record<string, string | undefined> = process.env,
+): EnvContext {
+  // Lazily instantiated Octokit client – shared across this context.
+  let cachedOctokit: ReturnType<typeof github.getOctokit> | null = null;
+
+  return {
+    get(name: string): string {
+      const value = _getRequiredEnv(name, env);
+      if (value == null) {
+        fail(`Missing required environment variable: ${name}`);
+      }
+      return value;
+    },
+
+    tryGet(name: string): string | undefined {
+      return _getRequiredEnv(name, env);
+    },
+
+    tryGetNonEmpty(name: string): string | null {
+      const value = _getRequiredEnv(name, env);
+      return value == null || value === "" ? null : value;
+    },
+
+    getOctokit(token?: string) {
+      if (cachedOctokit) {
+        return cachedOctokit;
+      }
+
+      // Determine the token to authenticate with.
+      const githubToken = token ?? env["GITHUB_TOKEN"] ?? env["GH_TOKEN"];
+
+      if (!githubToken) {
+        fail(
+          "Unable to locate a GitHub token. `github_token` should have been set on the action.",
+        );
+      }
+
+      cachedOctokit = github.getOctokit(githubToken!);
+      return cachedOctokit;
+    },
+  };
+}
+
+/**
+ * Shared context built from the actual `process.env`.  Production code that is
+ * not yet refactored to receive a context explicitly may import and use this
+ * singleton.  Tests should avoid the singleton and instead pass their own
+ * context to the functions they exercise.
+ */
+export const defaultContext: EnvContext = createEnvContext();

.github/actions/codex/src/fail.ts

@@ -0,0 +1,4 @@
+export function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}

.github/actions/codex/src/git-helpers.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from "child_process";
+import * as github from "@actions/github";
+import { EnvContext } from "./env-context";
+
+function runGit(args: string[], silent = true): string {
+  console.info(`Running git ${args.join(" ")}`);
+  const res = spawnSync("git", args, {
+    encoding: "utf8",
+    stdio: silent ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  if (res.error) {
+    throw res.error;
+  }
+  if (res.status !== 0) {
+    // Return stderr so caller may handle; else throw.
+    throw new Error(
+      `git ${args.join(" ")} failed with code ${res.status}: ${res.stderr}`,
+    );
+  }
+  return res.stdout.trim();
+}
+
+function stageAllChanges() {
+  runGit(["add", "-A"]);
+}
+
+function hasStagedChanges(): boolean {
+  const res = spawnSync("git", ["diff", "--cached", "--quiet", "--exit-code"]);
+  return res.status !== 0;
+}
+
+function ensureOnBranch(
+  issueNumber: number,
+  protectedBranches: string[],
+  suggestedSlug?: string,
+): string {
+  let branch = "";
+  try {
+    branch = runGit(["symbolic-ref", "--short", "-q", "HEAD"]);
+  } catch {
+    branch = "";
+  }
+
+  // If detached HEAD or on a protected branch, create a new branch.
+  if (!branch || protectedBranches.includes(branch)) {
+    if (suggestedSlug) {
+      const safeSlug = suggestedSlug
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+      branch = `codex-fix-${issueNumber}-${safeSlug}`;
+    } else {
+      branch = `codex-fix-${issueNumber}-${Date.now()}`;
+    }
+    runGit(["switch", "-c", branch]);
+  }
+  return branch;
+}
+
+function commitIfNeeded(issueNumber: number) {
+  if (hasStagedChanges()) {
+    runGit([
+      "commit",
+      "-m",
+      `fix: automated fix for #${issueNumber} via Codex`,
+    ]);
+  }
+}
+
+function pushBranch(branch: string, githubToken: string, ctx: EnvContext) {
+  const repoSlug = ctx.get("GITHUB_REPOSITORY"); // owner/repo
+  const remoteUrl = `https://x-access-token:${githubToken}@github.com/${repoSlug}.git`;
+
+  runGit(["push", "--force-with-lease", "-u", remoteUrl, `HEAD:${branch}`]);
+}
+
+/**
+ * If this returns a string, it is the URL of the created PR.
+ */
+export async function maybePublishPRForIssue(
+  issueNumber: number,
+  lastMessage: string,
+  ctx: EnvContext,
+): Promise<string | undefined> {
+  // Only proceed if GITHUB_TOKEN available.
+  const githubToken =
+    ctx.tryGetNonEmpty("GITHUB_TOKEN") ?? ctx.tryGetNonEmpty("GH_TOKEN");
+  if (!githubToken) {
+    console.warn("No GitHub token - skipping PR creation.");
+    return undefined;
+  }
+
+  // Print `git status` for debugging.
+  runGit(["status"]);
+
+  // Stage any remaining changes so they can be committed and pushed.
+  stageAllChanges();
+
+  const octokit = ctx.getOctokit(githubToken);
+
+  const { owner, repo } = github.context.repo;
+
+  // Determine default branch to treat as protected.
+  let defaultBranch = "main";
+  try {
+    const repoInfo = await octokit.rest.repos.get({ owner, repo });
+    defaultBranch = repoInfo.data.default_branch ?? "main";
+  } catch (e) {
+    console.warn(`Failed to get default branch, assuming 'main': ${e}`);
+  }
+
+  const sanitizedMessage = lastMessage.replace(/\u2022/g, "-");
+  const [summaryLine] = sanitizedMessage.split(/\r?\n/);
+  const branch = ensureOnBranch(issueNumber, [defaultBranch, "master"], summaryLine);
+  commitIfNeeded(issueNumber);
+  pushBranch(branch, githubToken, ctx);
+
+  // Try to find existing PR for this branch
+  const headParam = `${owner}:${branch}`;
+  const existing = await octokit.rest.pulls.list({
+    owner,
+    repo,
+    head: headParam,
+    state: "open",
+  });
+  if (existing.data.length > 0) {
+    return existing.data[0].html_url;
+  }
+
+  // Determine base branch (default to main)
+  let baseBranch = "main";
+  try {
+    const repoInfo = await octokit.rest.repos.get({ owner, repo });
+    baseBranch = repoInfo.data.default_branch ?? "main";
+  } catch (e) {
+    console.warn(`Failed to get default branch, assuming 'main': ${e}`);
+  }
+
+  const pr = await octokit.rest.pulls.create({
+    owner,
+    repo,
+    title: summaryLine,
+    head: branch,
+    base: baseBranch,
+    body: sanitizedMessage,
+  });
+  return pr.data.html_url;
+}

.github/actions/codex/src/git-user.ts

@@ -0,0 +1,16 @@
+export function setGitHubActionsUser(): void {
+  const commands = [
+    ["git", "config", "--global", "user.name", "github-actions[bot]"],
+    [
+      "git",
+      "config",
+      "--global",
+      "user.email",
+      "41898282+github-actions[bot]@users.noreply.github.com",
+    ],
+  ];
+
+  for (const command of commands) {
+    Bun.spawnSync(command);
+  }
+}

.github/actions/codex/src/github-workspace.ts

@@ -0,0 +1,11 @@
+import * as pathMod from "path";
+import { EnvContext } from "./env-context";
+
+export function resolveWorkspacePath(path: string, ctx: EnvContext): string {
+  if (pathMod.isAbsolute(path)) {
+    return path;
+  } else {
+    const workspace = ctx.get("GITHUB_WORKSPACE");
+    return pathMod.join(workspace, path);
+  }
+}

.github/actions/codex/src/load-config.ts

@@ -0,0 +1,56 @@
+import type { Config, LabelConfig } from "./config";
+
+import { getDefaultConfig } from "./default-label-config";
+import { readFileSync, readdirSync, statSync } from "fs";
+import * as path from "path";
+
+/**
+ * Build an in-memory configuration object by scanning the repository for
+ * Markdown templates located in `.github/codex/labels`.
+ *
+ * Each `*.md` file in that directory represents a label that can trigger the
+ * Codex GitHub Action. The filename **without** the extension is interpreted
+ * as the label name, e.g. `codex-review.md` ➜ `codex-review`.
+ *
+ * For every such label we derive the corresponding `doneLabel` by appending
+ * the suffix `-completed`.
+ */
+export function loadConfig(workspace: string): Config {
+  const labelsDir = path.join(workspace, ".github", "codex", "labels");
+
+  let entries: string[];
+  try {
+    entries = readdirSync(labelsDir);
+  } catch {
+    // If the directory is missing, return the default configuration.
+    return getDefaultConfig();
+  }
+
+  const labels: Record<string, LabelConfig> = {};
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) {
+      continue;
+    }
+
+    const fullPath = path.join(labelsDir, entry);
+
+    if (!statSync(fullPath).isFile()) {
+      continue;
+    }
+
+    const labelName = entry.slice(0, -3); // trim ".md"
+
+    labels[labelName] = new FileLabelConfig(fullPath);
+  }
+
+  return { labels };
+}
+
+class FileLabelConfig implements LabelConfig {
+  constructor(private readonly promptPath: string) {}
+
+  getPromptTemplate(): string {
+    return readFileSync(this.promptPath, "utf8");
+  }
+}

.github/actions/codex/src/main.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+
+import type { Config } from "./config";
+
+import { defaultContext, EnvContext } from "./env-context";
+import { loadConfig } from "./load-config";
+import { setGitHubActionsUser } from "./git-user";
+import { onLabeled } from "./process-label";
+import { ensureBaseAndHeadCommitsForPRAreAvailable } from "./prompt-template";
+import { performAdditionalValidation } from "./verify-inputs";
+import { onComment } from "./comment";
+import { onReview } from "./review";
+
+async function main(): Promise<void> {
+  const ctx: EnvContext = defaultContext;
+
+  // Build the configuration dynamically by scanning `.github/codex/labels`.
+  const GITHUB_WORKSPACE = ctx.get("GITHUB_WORKSPACE");
+  const config: Config = loadConfig(GITHUB_WORKSPACE);
+
+  // Optionally perform additional validation of prompt template files.
+  performAdditionalValidation(config, GITHUB_WORKSPACE);
+
+  const GITHUB_EVENT_NAME = ctx.get("GITHUB_EVENT_NAME");
+  const GITHUB_EVENT_ACTION = ctx.get("GITHUB_EVENT_ACTION");
+
+  // Set user.name and user.email to a bot before Codex runs, just in case it
+  // creates a commit.
+  setGitHubActionsUser();
+
+  switch (GITHUB_EVENT_NAME) {
+    case "issues": {
+      if (GITHUB_EVENT_ACTION === "labeled") {
+        await onLabeled(config, ctx);
+        return;
+      } else if (GITHUB_EVENT_ACTION === "opened") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+    case "issue_comment": {
+      if (GITHUB_EVENT_ACTION === "created") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request": {
+      if (GITHUB_EVENT_ACTION === "labeled") {
+        await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+        await onLabeled(config, ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request_review": {
+      await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+      if (GITHUB_EVENT_ACTION === "submitted") {
+        await onReview(ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request_review_comment": {
+      await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+      if (GITHUB_EVENT_ACTION === "created") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+  }
+
+  console.warn(
+    `Unsupported action '${GITHUB_EVENT_ACTION}' for event '${GITHUB_EVENT_NAME}'.`,
+  );
+}
+
+main();

.github/actions/codex/src/post-comment.ts

@@ -0,0 +1,62 @@
+import { fail } from "./fail";
+import * as github from "@actions/github";
+import { EnvContext } from "./env-context";
+
+/**
+ * Post a comment to the issue / pull request currently in scope.
+ *
+ * Provide the environment context so that token lookup (inside getOctokit) does
+ * not rely on global state.
+ */
+export async function postComment(
+  commentBody: string,
+  ctx: EnvContext,
+): Promise<void> {
+  // Append a footer with a link back to the workflow run, if available.
+  const footer = buildWorkflowRunFooter(ctx);
+  const bodyWithFooter = footer ? `${commentBody}${footer}` : commentBody;
+
+  const octokit = ctx.getOctokit();
+  console.info("Got Octokit instance for posting comment");
+  const { owner, repo } = github.context.repo;
+  const issueNumber = github.context.issue.number;
+
+  if (!issueNumber) {
+    console.warn(
+      "No issue or pull_request number found in GitHub context; skipping comment creation.",
+    );
+    return;
+  }
+
+  try {
+    console.info("Calling octokit.rest.issues.createComment()");
+    await octokit.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: bodyWithFooter,
+    });
+  } catch (error) {
+    fail(`Failed to create comment via GitHub API: ${error}`);
+  }
+}
+
+/**
+ * Helper to build a Markdown fragment linking back to the workflow run that
+ * generated the current comment. Returns `undefined` if required environment
+ * variables are missing – e.g. when running outside of GitHub Actions – so we
+ * can gracefully skip the footer in those cases.
+ */
+function buildWorkflowRunFooter(ctx: EnvContext): string | undefined {
+  const serverUrl =
+    ctx.tryGetNonEmpty("GITHUB_SERVER_URL") ?? "https://github.com";
+  const repository = ctx.tryGetNonEmpty("GITHUB_REPOSITORY");
+  const runId = ctx.tryGetNonEmpty("GITHUB_RUN_ID");
+
+  if (!repository || !runId) {
+    return undefined;
+  }
+
+  const url = `${serverUrl}/${repository}/actions/runs/${runId}`;
+  return `\n\n---\n*[_View workflow run_](${url})*`;
+}

.github/actions/codex/src/process-label.ts

@@ -0,0 +1,195 @@
+import { fail } from "./fail";
+import { EnvContext } from "./env-context";
+import { renderPromptTemplate } from "./prompt-template";
+
+import { postComment } from "./post-comment";
+import { runCodex } from "./run-codex";
+
+import * as github from "@actions/github";
+import { Config, LabelConfig } from "./config";
+import { maybePublishPRForIssue } from "./git-helpers";
+
+export async function onLabeled(
+  config: Config,
+  ctx: EnvContext,
+): Promise<void> {
+  const GITHUB_EVENT_LABEL_NAME = ctx.get("GITHUB_EVENT_LABEL_NAME");
+  const labelConfig = config.labels[GITHUB_EVENT_LABEL_NAME] as
+    | LabelConfig
+    | undefined;
+  if (!labelConfig) {
+    fail(
+      `Label \`${GITHUB_EVENT_LABEL_NAME}\` not found in config: ${JSON.stringify(config)}`,
+    );
+  }
+
+  await processLabelConfig(ctx, GITHUB_EVENT_LABEL_NAME, labelConfig);
+}
+
+/**
+ * Wrapper that handles `-in-progress` and `-completed` semantics around the core lint/fix/review
+ * processing. It will:
+ *
+ * - Skip execution if the `-in-progress` or `-completed` label is already present.
+ * - Mark the PR/issue as `-in-progress`.
+ * - After successful execution, mark the PR/issue as `-completed`.
+ */
+async function processLabelConfig(
+  ctx: EnvContext,
+  label: string,
+  labelConfig: LabelConfig,
+): Promise<void> {
+  const octokit = ctx.getOctokit();
+  const { owner, repo, issueNumber, labelNames } =
+    await getCurrentLabels(octokit);
+
+  const inProgressLabel = `${label}-in-progress`;
+  const completedLabel = `${label}-completed`;
+  for (const markerLabel of [inProgressLabel, completedLabel]) {
+    if (labelNames.includes(markerLabel)) {
+      console.log(
+        `Label '${markerLabel}' already present on issue/PR #${issueNumber}. Skipping Codex action.`,
+      );
+
+      // Clean up: remove the triggering label to avoid confusion and re-runs.
+      await addAndRemoveLabels(octokit, {
+        owner,
+        repo,
+        issueNumber,
+        remove: markerLabel,
+      });
+
+      return;
+    }
+  }
+
+  // Mark the PR/issue as in progress.
+  await addAndRemoveLabels(octokit, {
+    owner,
+    repo,
+    issueNumber,
+    add: inProgressLabel,
+    remove: label,
+  });
+
+  // Run the core Codex processing.
+  await processLabel(ctx, label, labelConfig);
+
+  // Mark the PR/issue as completed.
+  await addAndRemoveLabels(octokit, {
+    owner,
+    repo,
+    issueNumber,
+    add: completedLabel,
+    remove: inProgressLabel,
+  });
+}
+
+async function processLabel(
+  ctx: EnvContext,
+  label: string,
+  labelConfig: LabelConfig,
+): Promise<void> {
+  const template = labelConfig.getPromptTemplate();
+  const populatedTemplate = await renderPromptTemplate(template, ctx);
+
+  // Always run Codex and post the resulting message as a comment.
+  let commentBody = await runCodex(populatedTemplate, ctx);
+
+  // Current heuristic: only try to create a PR if "attempt" or "fix" is in the
+  // label name. (Yes, we plan to evolve this.)
+  if (label.indexOf("fix") !== -1 || label.indexOf("attempt") !== -1) {
+    console.info(`label ${label} indicates we should attempt to create a PR`);
+    const prUrl = await maybeFixIssue(ctx, commentBody);
+    if (prUrl) {
+      commentBody += `\n\n---\nOpened pull request: ${prUrl}`;
+    }
+  } else {
+    console.info(
+      `label ${label} does not indicate we should attempt to create a PR`,
+    );
+  }
+
+  await postComment(commentBody, ctx);
+}
+
+async function maybeFixIssue(
+  ctx: EnvContext,
+  lastMessage: string,
+): Promise<string | undefined> {
+  // Attempt to create a PR out of any changes Codex produced.
+  const issueNumber = github.context.issue.number!; // exists for issues triggering this path
+  try {
+    return await maybePublishPRForIssue(issueNumber, lastMessage, ctx);
+  } catch (e) {
+    console.warn(`Failed to publish PR: ${e}`);
+  }
+}
+
+async function getCurrentLabels(
+  octokit: ReturnType<typeof github.getOctokit>,
+): Promise<{
+  owner: string;
+  repo: string;
+  issueNumber: number;
+  labelNames: Array<string>;
+}> {
+  const { owner, repo } = github.context.repo;
+  const issueNumber = github.context.issue.number;
+
+  if (!issueNumber) {
+    fail("No issue or pull_request number found in GitHub context.");
+  }
+
+  const { data: issueData } = await octokit.rest.issues.get({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+
+  const labelNames =
+    issueData.labels?.map((label: any) =>
+      typeof label === "string" ? label : label.name,
+    ) ?? [];
+
+  return { owner, repo, issueNumber, labelNames };
+}
+
+async function addAndRemoveLabels(
+  octokit: ReturnType<typeof github.getOctokit>,
+  opts: {
+    owner: string;
+    repo: string;
+    issueNumber: number;
+    add?: string;
+    remove?: string;
+  },
+): Promise<void> {
+  const { owner, repo, issueNumber, add, remove } = opts;
+
+  if (add) {
+    try {
+      await octokit.rest.issues.addLabels({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        labels: [add],
+      });
+    } catch (error) {
+      console.warn(`Failed to add label '${add}': ${error}`);
+    }
+  }
+
+  if (remove) {
+    try {
+      await octokit.rest.issues.removeLabel({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        name: remove,
+      });
+    } catch (error) {
+      console.warn(`Failed to remove label '${remove}': ${error}`);
+    }
+  }
+}

.github/actions/codex/src/prompt-template.ts

@@ -0,0 +1,284 @@
+/*
+ * Utilities to render Codex prompt templates.
+ *
+ * A template is a Markdown (or plain-text) file that may contain one or more
+ * placeholders of the form `{CODEX_ACTION_<NAME>}`. At runtime these
+ * placeholders are substituted with dynamically generated content. Each
+ * placeholder is resolved **exactly once** even if it appears multiple times
+ * in the same template.
+ */
+
+import { readFile } from "fs/promises";
+
+import { EnvContext } from "./env-context";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazily caches parsed `$GITHUB_EVENT_PATH` contents keyed by the file path so
+ * we only hit the filesystem once per unique event payload.
+ */
+const githubEventDataCache: Map<string, Promise<any>> = new Map();
+
+function getGitHubEventData(ctx: EnvContext): Promise<any> {
+  const eventPath = ctx.get("GITHUB_EVENT_PATH");
+  let cached = githubEventDataCache.get(eventPath);
+  if (!cached) {
+    cached = readFile(eventPath, "utf8").then((raw) => JSON.parse(raw));
+    githubEventDataCache.set(eventPath, cached);
+  }
+  return cached;
+}
+
+async function runCommand(args: Array<string>): Promise<string> {
+  const result = Bun.spawnSync(args, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (result.success) {
+    return result.stdout.toString();
+  }
+
+  console.error(`Error running ${JSON.stringify(args)}: ${result.stderr}`);
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+// Regex that captures the variable name without the surrounding { } braces.
+const VAR_REGEX = /\{(CODEX_ACTION_[A-Z0-9_]+)\}/g;
+
+// Cache individual placeholder values so each one is resolved at most once per
+// process even if many templates reference it.
+const placeholderCache: Map<string, Promise<string>> = new Map();
+
+/**
+ * Parse a template string, resolve all placeholders and return the rendered
+ * result.
+ */
+export async function renderPromptTemplate(
+  template: string,
+  ctx: EnvContext,
+): Promise<string> {
+  // ---------------------------------------------------------------------
+  // 1) Gather all *unique* placeholders present in the template.
+  // ---------------------------------------------------------------------
+  const variables = new Set<string>();
+  for (const match of template.matchAll(VAR_REGEX)) {
+    variables.add(match[1]);
+  }
+
+  // ---------------------------------------------------------------------
+  // 2) Kick off (or reuse) async resolution for each variable.
+  // ---------------------------------------------------------------------
+  for (const variable of variables) {
+    if (!placeholderCache.has(variable)) {
+      placeholderCache.set(variable, resolveVariable(variable, ctx));
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // 3) Await completion so we can perform a simple synchronous replace below.
+  // ---------------------------------------------------------------------
+  const resolvedEntries: [string, string][] = [];
+  for (const [key, promise] of placeholderCache.entries()) {
+    resolvedEntries.push([key, await promise]);
+  }
+  const resolvedMap = new Map<string, string>(resolvedEntries);
+
+  // ---------------------------------------------------------------------
+  // 4) Replace each occurrence.  We use replace with a callback to ensure
+  //    correct substitution even if variable names overlap (they shouldn't,
+  //    but better safe than sorry).
+  // ---------------------------------------------------------------------
+  return template.replace(VAR_REGEX, (_, varName: string) => {
+    return resolvedMap.get(varName) ?? "";
+  });
+}
+
+export async function ensureBaseAndHeadCommitsForPRAreAvailable(
+  ctx: EnvContext,
+): Promise<{ baseSha: string; headSha: string } | null> {
+  const prShas = await getPrShas(ctx);
+  if (prShas == null) {
+    console.warn("Unable to resolve PR branches");
+    return null;
+  }
+
+  const event = await getGitHubEventData(ctx);
+  const pr = event.pull_request;
+  if (!pr) {
+    console.warn("event.pull_request is not defined - unexpected");
+    return null;
+  }
+
+  const workspace = ctx.get("GITHUB_WORKSPACE");
+
+  // Refs (branch names)
+  const baseRef: string | undefined = pr.base?.ref;
+  const headRef: string | undefined = pr.head?.ref;
+
+  // Clone URLs
+  const baseRemoteUrl: string | undefined = pr.base?.repo?.clone_url;
+  const headRemoteUrl: string | undefined = pr.head?.repo?.clone_url;
+
+  if (!baseRef || !headRef || !baseRemoteUrl || !headRemoteUrl) {
+    console.warn(
+      "Missing PR ref or remote URL information - cannot fetch commits",
+    );
+    return null;
+  }
+
+  // Ensure we have the base branch.
+  await runCommand([
+    "git",
+    "-C",
+    workspace,
+    "fetch",
+    "--no-tags",
+    "origin",
+    baseRef,
+  ]);
+
+  // Ensure we have the head branch.
+  if (headRemoteUrl === baseRemoteUrl) {
+    // Same repository – the commit is available from `origin`.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "fetch",
+      "--no-tags",
+      "origin",
+      headRef,
+    ]);
+  } else {
+    // Fork – make sure a `pr` remote exists that points at the fork. Attempting
+    // to add a remote that already exists causes git to error, so we swallow
+    // any non-zero exit codes from that specific command.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "remote",
+      "add",
+      "pr",
+      headRemoteUrl,
+    ]);
+
+    // Whether adding succeeded or the remote already existed, attempt to fetch
+    // the head ref from the `pr` remote.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "fetch",
+      "--no-tags",
+      "pr",
+      headRef,
+    ]);
+  }
+
+  return prShas;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers – still exported for use by other modules.
+// ---------------------------------------------------------------------------
+
+export async function resolvePrDiff(ctx: EnvContext): Promise<string> {
+  const prShas = await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+  if (prShas == null) {
+    console.warn("Unable to resolve PR branches");
+    return "";
+  }
+
+  const workspace = ctx.get("GITHUB_WORKSPACE");
+  const { baseSha, headSha } = prShas;
+  return runCommand([
+    "git",
+    "-C",
+    workspace,
+    "diff",
+    "--color=never",
+    `${baseSha}..${headSha}`,
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Placeholder resolution
+// ---------------------------------------------------------------------------
+
+async function resolveVariable(name: string, ctx: EnvContext): Promise<string> {
+  switch (name) {
+    case "CODEX_ACTION_ISSUE_TITLE": {
+      const event = await getGitHubEventData(ctx);
+      const issue = event.issue ?? event.pull_request;
+      return issue?.title ?? "";
+    }
+
+    case "CODEX_ACTION_ISSUE_BODY": {
+      const event = await getGitHubEventData(ctx);
+      const issue = event.issue ?? event.pull_request;
+      return issue?.body ?? "";
+    }
+
+    case "CODEX_ACTION_GITHUB_EVENT_PATH": {
+      return ctx.get("GITHUB_EVENT_PATH");
+    }
+
+    case "CODEX_ACTION_BASE_REF": {
+      const event = await getGitHubEventData(ctx);
+      return event?.pull_request?.base?.ref ?? "";
+    }
+
+    case "CODEX_ACTION_HEAD_REF": {
+      const event = await getGitHubEventData(ctx);
+      return event?.pull_request?.head?.ref ?? "";
+    }
+
+    case "CODEX_ACTION_PR_DIFF": {
+      return resolvePrDiff(ctx);
+    }
+
+    // -------------------------------------------------------------------
+    // Add new template variables here.
+    // -------------------------------------------------------------------
+
+    default: {
+      // Unknown variable – leave it blank to avoid leaking placeholders to the
+      // final prompt.  The alternative would be to `fail()` here, but silently
+      // ignoring unknown placeholders is more forgiving and better matches the
+      // behaviour of typical template engines.
+      console.warn(`Unknown template variable: ${name}`);
+      return "";
+    }
+  }
+}
+
+async function getPrShas(
+  ctx: EnvContext,
+): Promise<{ baseSha: string; headSha: string } | null> {
+  const event = await getGitHubEventData(ctx);
+  const pr = event.pull_request;
+  if (!pr) {
+    console.warn("event.pull_request is not defined");
+    return null;
+  }
+
+  // Prefer explicit SHAs if available to avoid relying on local branch names.
+  const baseSha: string | undefined = pr.base?.sha;
+  const headSha: string | undefined = pr.head?.sha;
+
+  if (!baseSha || !headSha) {
+    console.warn("one of base or head is not defined on event.pull_request");
+    return null;
+  }
+
+  return { baseSha, headSha };
+}

.github/actions/codex/src/review.ts

@@ -0,0 +1,42 @@
+import type { EnvContext } from "./env-context";
+import { runCodex } from "./run-codex";
+import { postComment } from "./post-comment";
+import { addEyesReaction } from "./add-reaction";
+
+/**
+ * Handle `pull_request_review` events. We treat the review body the same way
+ * as a normal comment.
+ */
+export async function onReview(ctx: EnvContext): Promise<void> {
+  const triggerPhrase = ctx.tryGet("INPUT_TRIGGER_PHRASE");
+  if (!triggerPhrase) {
+    console.warn("Empty trigger phrase: skipping.");
+    return;
+  }
+
+  const reviewBody = ctx.tryGet("GITHUB_EVENT_REVIEW_BODY");
+
+  if (!reviewBody) {
+    console.warn("Review body not found in environment: skipping.");
+    return;
+  }
+
+  if (!reviewBody.includes(triggerPhrase)) {
+    console.log(
+      `Trigger phrase '${triggerPhrase}' not found: nothing to do for this review.`,
+    );
+    return;
+  }
+
+  const prompt = reviewBody.replace(triggerPhrase, "").trim();
+
+  if (prompt.length === 0) {
+    console.warn("Prompt is empty after removing trigger phrase: skipping.");
+    return;
+  }
+
+  await addEyesReaction(ctx);
+
+  const lastMessage = await runCodex(prompt, ctx);
+  await postComment(lastMessage, ctx);
+}

.github/actions/codex/src/run-codex.ts

@@ -0,0 +1,56 @@
+import { fail } from "./fail";
+import { EnvContext } from "./env-context";
+import { tmpdir } from "os";
+import { join } from "node:path";
+import { readFile, mkdtemp } from "fs/promises";
+import { resolveWorkspacePath } from "./github-workspace";
+
+/**
+ * Runs the Codex CLI with the provided prompt and returns the output written
+ * to the "last message" file.
+ */
+export async function runCodex(
+  prompt: string,
+  ctx: EnvContext,
+): Promise<string> {
+  const OPENAI_API_KEY = ctx.get("OPENAI_API_KEY");
+
+  const tempDirPath = await mkdtemp(join(tmpdir(), "codex-"));
+  const lastMessageOutput = join(tempDirPath, "codex-prompt.md");
+
+  const args = ["/usr/local/bin/codex-exec"];
+
+  const inputCodexArgs = ctx.tryGet("INPUT_CODEX_ARGS")?.trim();
+  if (inputCodexArgs) {
+    args.push(...inputCodexArgs.split(/\s+/));
+  }
+
+  args.push("--output-last-message", lastMessageOutput, prompt);
+
+  const env: Record<string, string> = { ...process.env, OPENAI_API_KEY };
+  const INPUT_CODEX_HOME = ctx.tryGet("INPUT_CODEX_HOME");
+  if (INPUT_CODEX_HOME) {
+    env.CODEX_HOME = resolveWorkspacePath(INPUT_CODEX_HOME, ctx);
+  }
+
+  console.log(`Running Codex: ${JSON.stringify(args)}`);
+  const result = Bun.spawnSync(args, {
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  if (!result.success) {
+    fail(`Codex failed: see above for details.`);
+  }
+
+  // Read the output generated by Codex.
+  let lastMessage: string;
+  try {
+    lastMessage = await readFile(lastMessageOutput, "utf8");
+  } catch (err) {
+    fail(`Failed to read Codex output at '${lastMessageOutput}': ${err}`);
+  }
+
+  return lastMessage;
+}

.github/actions/codex/src/verify-inputs.ts

@@ -0,0 +1,33 @@
+// Validate the inputs passed to the composite action.
+// The script currently ensures that the provided configuration file exists and
+// matches the expected schema.
+
+import type { Config } from "./config";
+
+import { existsSync } from "fs";
+import * as path from "path";
+import { fail } from "./fail";
+
+export function performAdditionalValidation(config: Config, workspace: string) {
+  // Additional validation: ensure referenced prompt files exist and are Markdown.
+  for (const [label, details] of Object.entries(config.labels)) {
+    // Determine which prompt key is present (the schema guarantees exactly one).
+    const promptPathStr =
+      (details as any).prompt ?? (details as any).promptPath;
+
+    if (promptPathStr) {
+      const promptPath = path.isAbsolute(promptPathStr)
+        ? promptPathStr
+        : path.join(workspace, promptPathStr);
+
+      if (!existsSync(promptPath)) {
+        fail(`Prompt file for label '${label}' not found: ${promptPath}`);
+      }
+      if (!promptPath.endsWith(".md")) {
+        fail(
+          `Prompt file for label '${label}' must be a .md file (got ${promptPathStr}).`,
+        );
+      }
+    }
+  }
+}

.github/actions/codex/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+
+  "include": ["src"]
+}

.github/codex/home/config.toml

@@ -0,0 +1,3 @@
+model = "o3"
+
+# Consider setting [mcp_servers] here!

.github/codex/labels/codex-attempt.md

@@ -0,0 +1,9 @@
+Attempt to solve the reported issue.
+
+If a code change is required, create a new branch, commit the fix, and open a pull request that resolves the problem.
+
+Here is the original GitHub issue that triggered this run:
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}

.github/codex/labels/codex-review.md

@@ -0,0 +1,7 @@
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the `base` and `head` refs that define this PR. Both refs are available locally.

.github/codex/labels/codex-triage.md

@@ -0,0 +1,7 @@
+Troubleshoot whether the reported issue is valid.
+
+Provide a concise and respectful comment summarizing the findings.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}

.github/workflows/codex.yml

@@ -0,0 +1,95 @@
+name: Codex
+
+on:
+  issues:
+    types: [opened, labeled]
+  pull_request:
+    branches: [main]
+    types: [labeled]
+
+jobs:
+  codex:
+    # This `if` check provides complex filtering logic to avoid running Codex
+    # on every PR. Admittedly, one thing this does not verify is whether the
+    # sender has write access to the repo: that must be done as part of a
+    # runtime step.
+    #
+    # Note the label values should match the ones in the .github/codex/labels
+    # folder.
+    if: |
+      (github.event_name == 'issues' && (
+        (github.event.action == 'labeled' && (github.event.label.name == 'codex-attempt' || github.event.label.name == 'codex-triage'))
+      )) ||
+      (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'codex-review')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # can push or create branches
+      issues: write # for comments + labels on issues/PRs
+      pull-requests: write # for PR comments/labels
+    steps:
+      # TODO: Consider adding an optional mode (--dry-run?) to actions/codex
+      # that verifies whether Codex should actually be run for this event.
+      # (For example, it may be rejected because the sender does not have
+      # write access to the repo.) The benefit would be two-fold:
+      # 1. As the first step of this job, it gives us a chance to add a reaction
+      #    or comment to the PR/issue ASAP to "ack" the request.
+      # 2. It saves resources by skipping the clone and setup steps below if
+      #    Codex is not going to run.
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # We install the dependencies like we would for an ordinary CI job,
+      # particularly because Codex will not have network access to install
+      # these dependencies.
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.1
+          run_install: false
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "store_path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.store_path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - uses: dtolnay/rust-toolchain@1.87
+        with:
+          targets: x86_64-unknown-linux-gnu
+          components: clippy
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            ${{ github.workspace }}/codex-rs/target/
+          key: cargo-ubuntu-24.04-x86_64-unknown-linux-gnu-${{ hashFiles('**/Cargo.lock') }}
+
+      # Note it is possible that the `verify` step internal to Run Codex will
+      # fail, in which case the work to setup the repo was worthless :(
+      - name: Run Codex
+        uses: ./.github/actions/codex
+        with:
+          openai_api_key: ${{ secrets.CODEX_OPENAI_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          codex_home: ./.github/codex/home

codex-cli/scripts/install_native_deps.sh

@@ -65,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/15192425904"
+WORKFLOW_URL="https://github.com/openai/codex/actions/runs/15334411824"
 WORKFLOW_ID="${WORKFLOW_URL##*/}"
 
 ARTIFACTS_DIR="$(mktemp -d)"

codex-rs/Cargo.lock

@@ -54,6 +54,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "aligned-vec"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4aa90d7ce82d4be67b64039a3d588d38dbcc6736577de4a847025ce5b0c468d1"
+
 [[package]]
 name = "allocative"
 version = "0.3.4"
@@ -177,6 +183,29 @@ version = "1.0.98"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e16d2d3311acee920a9eb8d33b8cbc1787ce4a264e85f964c2404b969bdcd487"
 
+[[package]]
+name = "arbitrary"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dde20b3d026af13f561bdd0f15edf01fc734f0dafcedbaf42bba506a9517f223"
+
+[[package]]
+name = "arg_enum_proc_macro"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.100",
+]
+
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
 [[package]]
 name = "ascii-canvas"
 version = "3.0.0"
@@ -247,6 +276,29 @@ version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26"
 
+[[package]]
+name = "av1-grain"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f3efb2ca85bc610acfa917b5aaa36f3fcbebed5b3182d7f877b02531c4b80c8"
+dependencies = [
+ "anyhow",
+ "arrayvec",
+ "log",
+ "nom",
+ "num-rational",
+ "v_frame",
+]
+
+[[package]]
+name = "avif-serialize"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98922d6a4cfbcb08820c69d8eeccc05bb1f29bfa06b4f5b1dbfe9a868bd7608e"
+dependencies = [
+ "arrayvec",
+]
+
 [[package]]
 name = "backtrace"
 version = "0.3.71"
@@ -304,6 +356,12 @@ version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
 
+[[package]]
+name = "bit_field"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc827186963e592360843fb5ba4b973e145841266c1357f7180c43526f2e5b61"
+
 [[package]]
 name = "bitflags"
 version = "1.3.2"
@@ -316,6 +374,12 @@ version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5c8214115b7bf84099f1309324e63141d4c5d7cc26862f97a0a857dbefe165bd"
 
+[[package]]
+name = "bitstream-io"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6099cdc01846bc367c4e7dd630dc5966dccf36b652fae7a74e17b640411a91b2"
+
 [[package]]
 name = "bstr"
 version = "1.12.0"
@@ -327,6 +391,12 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "built"
+version = "0.7.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56ed6191a7e78c36abdb16ab65341eefd73d64d303fffccdbb00d51e4205967b"
+
 [[package]]
 name = "bumpalo"
 version = "3.17.0"
@@ -339,12 +409,24 @@ version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5ce89b21cab1437276d2650d57e971f9d548a2d9037cc231abdc0562b97498ce"
 
+[[package]]
+name = "bytemuck"
+version = "1.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9134a6ef01ce4b366b50689c94f82c14bc72bc5d0386829828a2e2752ef7958c"
+
 [[package]]
 name = "byteorder"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.10.1"
@@ -372,9 +454,21 @@ version = "1.2.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e3a13707ac958681c13b39b458c073d0d9bc8a22cb1b2f4c8e55eb72c13f362"
 dependencies = [
+ "jobserver",
+ "libc",
  "shlex",
 ]
 
+[[package]]
+name = "cfg-expr"
+version = "0.15.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02"
+dependencies = [
+ "smallvec",
+ "target-lexicon",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.0"
@@ -506,6 +600,8 @@ version = "0.0.0"
 dependencies = [
  "clap",
  "codex-core",
+ "serde",
+ "toml",
 ]
 
 [[package]]
@@ -534,7 +630,7 @@ dependencies = [
  "path-absolutize",
  "predicates",
  "pretty_assertions",
- "rand",
+ "rand 0.9.1",
  "reqwest",
  "seccompiler",
  "serde",
@@ -634,6 +730,7 @@ dependencies = [
  "serde",
  "serde_json",
  "tokio",
+ "toml",
  "tracing",
  "tracing-subscriber",
 ]
@@ -643,6 +740,7 @@ name = "codex-tui"
 version = "0.0.0"
 dependencies = [
  "anyhow",
+ "base64 0.22.1",
  "clap",
  "codex-ansi-escape",
  "codex-common",
@@ -650,11 +748,13 @@ dependencies = [
  "codex-linux-sandbox",
  "color-eyre",
  "crossterm",
+ "image",
  "lazy_static",
  "mcp-types",
  "path-clean",
  "pretty_assertions",
  "ratatui",
+ "ratatui-image",
  "regex",
  "serde_json",
  "shlex",
@@ -697,6 +797,12 @@ dependencies = [
  "tracing-error",
 ]
 
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
 [[package]]
 name = "colorchoice"
 version = "1.0.3"
@@ -769,6 +875,25 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "crossbeam-utils"
 version = "0.8.21"
@@ -1172,6 +1297,21 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "exr"
+version = "1.73.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83197f59927b46c04a183a619b7c29df34e63e63c7869320862268c0ef687e0"
+dependencies = [
+ "bit_field",
+ "half",
+ "lebe",
+ "miniz_oxide 0.8.8",
+ "rayon-core",
+ "smallvec",
+ "zune-inflate",
+]
+
 [[package]]
 name = "eyre"
 version = "0.6.12"
@@ -1199,6 +1339,15 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "fixedbitset"
 version = "0.4.2"
@@ -1415,6 +1564,16 @@ dependencies = [
  "wasi 0.14.2+wasi-0.2.4",
 ]
 
+[[package]]
+name = "gif"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3fb2d69b19215e18bb912fa30f7ce15846e301408695e44e0ef719f1da9e19f2"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
 [[package]]
 name = "gimli"
 version = "0.28.1"
@@ -1446,6 +1605,16 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "half"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "459196ed295495a68f7d7fe1d84f6c4b7ff0e21fe3017b2f283c6fac3ad803c9"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.12.3"
@@ -1638,7 +1807,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core",
+ "windows-core 0.61.0",
 ]
 
 [[package]]
@@ -1768,6 +1937,12 @@ dependencies = [
  "syn 2.0.100",
 ]
 
+[[package]]
+name = "icy_sixel"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccc0a9c4770bc47b0a933256a496cfb8b6531f753ea9bccb19c6dff0ff7273fc"
+
 [[package]]
 name = "ident_case"
 version = "1.0.1"
@@ -1795,6 +1970,45 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db35664ce6b9810857a38a906215e75a9c879f0696556a39f59c62829710251a"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "color_quant",
+ "exr",
+ "gif",
+ "image-webp",
+ "num-traits",
+ "png",
+ "qoi",
+ "ravif",
+ "rayon",
+ "rgb",
+ "tiff",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b77d01e822461baa8409e156015a1d91735549f0f2c17691bd2d996bef238f7f"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
+[[package]]
+name = "imgref"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0263a3d970d5c054ed9312c0057b4f3bde9c0b33836d3637361d4a9e6e7a408"
+
 [[package]]
 name = "indenter"
 version = "0.3.3"
@@ -1842,6 +2056,17 @@ dependencies = [
  "syn 2.0.100",
 ]
 
+[[package]]
+name = "interpolate_name"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "inventory"
 version = "0.3.20"
@@ -1883,6 +2108,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba291022dbbd398a455acf126c1e341954079855bc60dfdda641363bd6922569"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -1931,6 +2165,22 @@ dependencies = [
  "syn 2.0.100",
 ]
 
+[[package]]
+name = "jobserver"
+version = "0.1.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38f262f097c174adebe41eb73d66ae9c06b2844fb0da69969647bbddd9b0538a"
+dependencies = [
+ "getrandom 0.3.2",
+ "libc",
+]
+
+[[package]]
+name = "jpeg-decoder"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5d4a7da358eff58addd2877a45865158f0d78c911d43a5784ceb7bbf52833b0"
+
 [[package]]
 name = "js-sys"
 version = "0.3.77"
@@ -1989,12 +2239,28 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
+[[package]]
+name = "lebe"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03087c2bad5e1034e8cace5926dec053fb3790248370865f5117a7d0213354c8"
+
 [[package]]
 name = "libc"
 version = "0.2.172"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d750af042f7ef4f724306de029d18836c26c1765a54a6a3f094cbd23a7267ffa"
 
+[[package]]
+name = "libfuzzer-sys"
+version = "0.4.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf78f52d400cf2d84a3a973a78a592b4adc535739e0a5597a0da6f0c357adc75"
+dependencies = [
+ "arbitrary",
+ "cc",
+]
+
 [[package]]
 name = "libredox"
 version = "0.1.3"
@@ -2068,6 +2334,15 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[package]]
+name = "loop9"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fae87c125b03c1d2c0150c90365d7d6bcc53fb73a9acaef207d2d065860f062"
+dependencies = [
+ "imgref",
+]
+
 [[package]]
 name = "lru"
 version = "0.12.5"
@@ -2105,6 +2380,16 @@ dependencies = [
  "regex-automata 0.1.10",
 ]
 
+[[package]]
+name = "maybe-rayon"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ea1f30cedd69f0a2954655f7188c6a834246d2bcf1e315e2ac40c4b24dc9519"
+dependencies = [
+ "cfg-if",
+ "rayon",
+]
+
 [[package]]
 name = "mcp-types"
 version = "0.0.0"
@@ -2166,6 +2451,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3be647b768db090acb35d5ec5db2b0e1f1de11133ca123b9eacf5137868f892a"
 dependencies = [
  "adler2",
+ "simd-adler32",
 ]
 
 [[package]]
@@ -2254,6 +2540,12 @@ dependencies = [
  "nom",
 ]
 
+[[package]]
+name = "noop_proc_macro"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0676bb32a98c1a483ce53e500a81ad9c3d5b3f7c920c28c24e9cb0980d0b5bc8"
+
 [[package]]
 name = "normalize-line-endings"
 version = "0.3.0"
@@ -2286,6 +2578,17 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "51d515d32fb182ee37cda2ccdcb92950d6a3c2893aa280e540671c2cd0f3b1d9"
 
+[[package]]
+name = "num-derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "num-integer"
 version = "0.1.46"
@@ -2295,6 +2598,17 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -2564,6 +2878,19 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.8",
+]
+
 [[package]]
 name = "portable-atomic"
 version = "1.11.0"
@@ -2658,6 +2985,25 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "profiling"
+version = "1.0.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "afbdc74edc00b6f6a218ca6a5364d6226a259d4b8ea1af4a0ea063f27e179f4d"
+dependencies = [
+ "profiling-procmacros",
+]
+
+[[package]]
+name = "profiling-procmacros"
+version = "1.0.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a65f2e60fbf1063868558d69c6beacf412dc755f9fc020f514b7955fc914fe30"
+dependencies = [
+ "quote",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.0"
@@ -2677,6 +3023,21 @@ version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
 
+[[package]]
+name = "qoi"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f6d64c71eb498fe9eae14ce4ec935c555749aef511cca85b5568910d6e48001"
+dependencies = [
+ "bytemuck",
+]
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.32.0"
@@ -2711,14 +3072,35 @@ dependencies = [
  "nibble_vec",
 ]
 
+[[package]]
+name = "rand"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+dependencies = [
+ "libc",
+ "rand_chacha 0.3.1",
+ "rand_core 0.6.4",
+]
+
 [[package]]
 name = "rand"
 version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9fbfd9d094a40bf3ae768db9361049ace4c0e04a4fd6b359518bd7b73a73dd97"
 dependencies = [
- "rand_chacha",
- "rand_core",
+ "rand_chacha 0.9.0",
+ "rand_core 0.9.3",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.6.4",
 ]
 
 [[package]]
@@ -2728,7 +3110,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
 dependencies = [
  "ppv-lite86",
- "rand_core",
+ "rand_core 0.9.3",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom 0.2.16",
 ]
 
 [[package]]
@@ -2761,6 +3152,92 @@ dependencies = [
  "unicode-width 0.2.0",
 ]
 
+[[package]]
+name = "ratatui-image"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3f1d31464920104b247593f008158372d2fdb8165e93a4299cdd6f994448c9a"
+dependencies = [
+ "base64 0.21.7",
+ "icy_sixel",
+ "image",
+ "rand 0.8.5",
+ "ratatui",
+ "rustix 0.38.44",
+ "thiserror 1.0.69",
+ "windows",
+]
+
+[[package]]
+name = "rav1e"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd87ce80a7665b1cce111f8a16c1f3929f6547ce91ade6addf4ec86a8dda5ce9"
+dependencies = [
+ "arbitrary",
+ "arg_enum_proc_macro",
+ "arrayvec",
+ "av1-grain",
+ "bitstream-io",
+ "built",
+ "cfg-if",
+ "interpolate_name",
+ "itertools 0.12.1",
+ "libc",
+ "libfuzzer-sys",
+ "log",
+ "maybe-rayon",
+ "new_debug_unreachable",
+ "noop_proc_macro",
+ "num-derive",
+ "num-traits",
+ "once_cell",
+ "paste",
+ "profiling",
+ "rand 0.8.5",
+ "rand_chacha 0.3.1",
+ "simd_helpers",
+ "system-deps",
+ "thiserror 1.0.69",
+ "v_frame",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "ravif"
+version = "0.11.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6a5f31fcf7500f9401fea858ea4ab5525c99f2322cfcee732c0e6c74208c0c6"
+dependencies = [
+ "avif-serialize",
+ "imgref",
+ "loop9",
+ "quick-error",
+ "rav1e",
+ "rayon",
+ "rgb",
+]
+
+[[package]]
+name = "rayon"
+version = "1.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b418a60154510ca1a002a752ca9714984e21e4241e804d32555251faf8b78ffa"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1465873a3dfdaa8ae7cb14b4383657caab0b3e8a0aa9ae8e04b044854c8dfce2"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.11"
@@ -2908,6 +3385,12 @@ dependencies = [
  "windows-registry",
 ]
 
+[[package]]
+name = "rgb"
+version = "0.8.50"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57397d16646700483b67d2dd6511d79318f9d057fdbd21a4066aeac8b41d310a"
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -3345,6 +3828,21 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d66dc143e6b11c1eddc06d5c423cfc97062865baf299914ab64caa38182078fe"
+
+[[package]]
+name = "simd_helpers"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95890f873bec569a0362c235787f3aca6e1e887302ba4840839bcc6459c42da6"
+dependencies = [
+ "quote",
+]
+
 [[package]]
 name = "simdutf8"
 version = "0.1.5"
@@ -3652,6 +4150,25 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "system-deps"
+version = "6.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3e535eb8dded36d55ec13eddacd30dec501792ff23a0b1682c38601b8cf2349"
+dependencies = [
+ "cfg-expr",
+ "heck",
+ "pkg-config",
+ "toml",
+ "version-compare",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
 [[package]]
 name = "tempfile"
 version = "3.19.1"
@@ -3751,6 +4268,17 @@ dependencies = [
  "once_cell",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba1310fcea54c6a9a4fd1aad794ecc02c31682f6bfbecdf460bf19533eed1e3e"
+dependencies = [
+ "flate2",
+ "jpeg-decoder",
+ "weezl",
+]
+
 [[package]]
 name = "time"
 version = "0.3.41"
@@ -4175,6 +4703,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "v_frame"
+version = "0.3.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f32aaa24bacd11e488aa9ba66369c7cd514885742c9fe08cfe85884db3e92b"
+dependencies = [
+ "aligned-vec",
+ "num-traits",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"
@@ -4187,6 +4726,12 @@ version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
 
+[[package]]
+name = "version-compare"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "852e951cb7832cb45cb1169900d19760cfa39b82bc0ea9c0e5a14ae88411c98b"
+
 [[package]]
 name = "version_check"
 version = "0.9.5"
@@ -4330,6 +4875,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "weezl"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a751b3277700db47d3e574514de2eced5e54dc8a5436a3bf7a0b248b2cee16f3"
+
 [[package]]
 name = "wildmatch"
 version = "2.4.0"
@@ -4367,19 +4918,53 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
+[[package]]
+name = "windows"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd04d41d93c4992d421894c18c8b43496aa748dd4c081bac0dc93eb0489272b6"
+dependencies = [
+ "windows-core 0.58.0",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ba6d44ec8c2591c134257ce647b7ea6b20335bf6379a27dac5f1641fcf59f99"
+dependencies = [
+ "windows-implement 0.58.0",
+ "windows-interface 0.58.0",
+ "windows-result 0.2.0",
+ "windows-strings 0.1.0",
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-core"
 version = "0.61.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4763c1de310c86d75a878046489e2e5ba02c649d185f21c67d4cf8a56d098980"
 dependencies = [
- "windows-implement",
- "windows-interface",
+ "windows-implement 0.60.0",
+ "windows-interface 0.59.1",
  "windows-link",
- "windows-result",
+ "windows-result 0.3.2",
  "windows-strings 0.4.0",
 ]
 
+[[package]]
+name = "windows-implement"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bbd5b46c938e506ecbce286b6628a02171d56153ba733b6c741fc627ec9579b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "windows-implement"
 version = "0.60.0"
@@ -4391,6 +4976,17 @@ dependencies = [
  "syn 2.0.100",
 ]
 
+[[package]]
+name = "windows-interface"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053c4c462dc91d3b1504c6fe5a726dd15e216ba718e84a0e46a88fbe5ded3515"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.100",
+]
+
 [[package]]
 name = "windows-interface"
 version = "0.59.1"
@@ -4414,11 +5010,20 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4286ad90ddb45071efd1a66dfa43eb02dd0dfbae1545ad6cc3c51cf34d7e8ba3"
 dependencies = [
- "windows-result",
+ "windows-result 0.3.2",
  "windows-strings 0.3.1",
  "windows-targets 0.53.0",
 ]
 
+[[package]]
+name = "windows-result"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d1043d8214f791817bab27572aaa8af63732e11bf84aa21a45a78d6c317ae0e"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-result"
 version = "0.3.2"
@@ -4428,6 +5033,16 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-strings"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cd9b125c486025df0eabcb585e62173c6c9eddcec5d117d3b6e8c30e2ee4d10"
+dependencies = [
+ "windows-result 0.2.0",
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-strings"
 version = "0.3.1"
@@ -4773,3 +5388,27 @@ dependencies = [
  "quote",
  "syn 2.0.100",
 ]
+
+[[package]]
+name = "zune-core"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f423a2c17029964870cfaabb1f13dfab7d092a62a29a89264f4d36990ca414a"
+
+[[package]]
+name = "zune-inflate"
+version = "0.2.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73ab332fe2f6680068f3582b16a24f90ad7096d5d39b974d1c0aff0125116f02"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "zune-jpeg"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99a5bab8d7dedf81405c4bb1f2b83ea057643d9cb28778cea9eecddeedd2e028"
+dependencies = [
+ "zune-core",
+]

codex-rs/README.md

@@ -1,16 +1,31 @@
-# codex-rs
+# Codex CLI (Rust Implementation)
 
-April 24, 2025
+We provide Codex CLI as a standalone, native executable to ensure a zero-dependency install.
 
-Today, Codex CLI is written in TypeScript and requires Node.js 22+ to run it. For a number of users, this runtime requirement inhibits adoption: they would be better served by a standalone executable. As maintainers, we want Codex to run efficiently in a wide range of environments with minimal overhead. We also want to take advantage of operating system-specific APIs to provide better sandboxing, where possible.
+## Installing Codex
 
-To that end, we are moving forward with a Rust implementation of Codex CLI contained in this folder, which has the following benefits:
+Today, the easiest way to install Codex is via `npm`, though we plan to publish Codex to other package managers soon.
 
-- The CLI compiles to small, standalone, platform-specific binaries.
-- 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.
+```shell
+npm i -g @openai/codex@native
+codex
+```
 
-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.
+You can also download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).
+
+## Config
+
+Codex supports a rich set of configuration options. See [`config.md`](./config.md) for details.
+
+## Model Context Protocol Support
+
+Codex CLI functions as an MCP client that can connect to MCP servers on startup. See the [`mcp_servers`](./config.md#mcp_servers) section in the configuration documentation for details.
+
+It is still experimental, but you can also launch Codex as an MCP _server_ by running `codex mcp`. Using the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) is
+
+```shell
+npx @modelcontextprotocol/inspector codex mcp
+```
 
 ## Code Organization
 
@@ -20,373 +35,3 @@ This folder is the root of a Cargo workspace. It contains quite a bit of experim
 - [`exec/`](./exec) "headless" CLI for use in automation.
 - [`tui/`](./tui) CLI that launches a fullscreen TUI built with [Ratatui](https://ratatui.rs/).
 - [`cli/`](./cli) CLI multitool that provides the aforementioned CLIs via subcommands.
-
-## Config
-
-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 "codex-mini-latest"
-```
-
-### model_provider
-
-Codex comes bundled with a number of "model providers" predefined. This config value is a string that indicates which provider to use. You can also define your own providers via `model_providers`.
-
-For example, if you are running ollama with Mistral locally, then you would need to add the following to your config:
-
-```toml
-model = "mistral"
-model_provider = "ollama"
-```
-
-because the following definition for `ollama` is included in Codex:
-
-```toml
-[model_providers.ollama]
-name = "Ollama"
-base_url = "http://localhost:11434/v1"
-wire_api = "chat"
-```
-
-This option defaults to `"openai"` and the corresponding provider is defined as follows:
-
-```toml
-[model_providers.openai]
-name = "OpenAI"
-base_url = "https://api.openai.com/v1"
-env_key = "OPENAI_API_KEY"
-wire_api = "responses"
-```
-
-### model_providers
-
-This option lets you override and amend the default set of model providers bundled with Codex. This value is a map where the key is the value to use with `model_provider` to select the correspodning provider.
-
-For example, if you wanted to add a provider that uses the OpenAI 4o model via the chat completions API, then you
-
-```toml
-# Recall that in TOML, root keys must be listed before tables.
-model = "gpt-4o"
-model_provider = "openai-chat-completions"
-
-[model_providers.openai-chat-completions]
-# Name of the provider that will be displayed in the Codex UI.
-name = "OpenAI using Chat Completions"
-# The path `/chat/completions` will be amended to this URL to make the POST
-# request for the chat completions.
-base_url = "https://api.openai.com/v1"
-# If `env_key` is set, identifies an environment variable that must be set when
-# using Codex with this provider. The value of the environment variable must be
-# non-empty and will be used in the `Bearer TOKEN` HTTP header for the POST request.
-env_key = "OPENAI_API_KEY"
-# valid values for wire_api are "chat" and "responses".
-wire_api = "chat"
-```
-
-### approval_policy
-
-Determines when the user should be prompted to approve whether Codex can execute a command:
-
-```toml
-# This is analogous to --suggest in the TypeScript Codex CLI
-approval_policy = "unless-allow-listed"
-```
-
-```toml
-# If the command fails when run in the sandbox, Codex asks for permission to
-# retry the command outside the sandbox.
-approval_policy = "on-failure"
-```
-
-```toml
-# User is never prompted: if the command fails, Codex will automatically try
-# something out. Note the `exec` subcommand always uses this mode.
-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:
-
-```toml
-# This is comparable to --full-auto in the TypeScript Codex CLI, though
-# specifying `disk-write-platform-global-temp-folder` adds /tmp as a writable
-# folder in addition to $TMPDIR.
-sandbox_permissions = [
-    "disk-full-read-access",
-    "disk-write-platform-user-temp-folder",
-    "disk-write-platform-global-temp-folder",
-    "disk-write-cwd",
-]
-```
-
-To add additional writable folders, use `disk-write-folder`, which takes a parameter (this can be specified multiple times):
-
-```toml
-sandbox_permissions = [
-    # ...
-    "disk-write-folder=/Users/mbolin/.pyenv/shims",
-]
-```
-
-### mcp_servers
-
-Defines the list of MCP servers that Codex can consult for tool use. Currently, only servers that are launched by executing a program that communicate over stdio are supported. For servers that use the SSE transport, consider an adapter like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
-
-**Note:** Codex may cache the list of tools and resources from an MCP server so that Codex can include this information in context at startup without spawning all the servers. This is designed to save resources by loading MCP servers lazily.
-
-This config option is comparable to how Claude and Cursor define `mcpServers` in their respective JSON config files, though because Codex uses TOML for its config language, the format is slightly different. For example, the following config in JSON:
-
-```json
-{
-  "mcpServers": {
-    "server-name": {
-      "command": "npx",
-      "args": ["-y", "mcp-server"],
-      "env": {
-        "API_KEY": "value"
-      }
-    }
-  }
-}
-```
-
-Should be represented as follows in `~/.codex/config.toml`:
-
-```toml
-# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
-[mcp_servers.server-name]
-command = "npx"
-args = ["-y", "mcp-server"]
-env = { "API_KEY" = "value" }
-```
-
-### disable_response_storage
-
-Currently, customers whose accounts are set to use Zero Data Retention (ZDR) must set `disable_response_storage` to `true` so that Codex uses an alternative to the Responses API that works with ZDR:
-
-```toml
-disable_response_storage = true
-```
-
-### shell_environment_policy
-
-Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it passes **only a minimal core subset** of your environment to those subprocesses to avoid leaking credentials. You can tune this behavior via the **`shell_environment_policy`** block in
-`config.toml`:
-
-```toml
-[shell_environment_policy]
-# inherit can be "core" (default), "all", or "none"
-inherit = "core"
-# set to true to *skip* the filter for `"*KEY*"` and `"*TOKEN*"`
-ignore_default_excludes = false
-# exclude patterns (case-insensitive globs)
-exclude = ["AWS_*", "AZURE_*"]
-# force-set / override values
-set = { CI = "1" }
-# if provided, *only* vars matching these patterns are kept
-include_only = ["PATH", "HOME"]
-```
-
-| Field                     | Type                       | Default | Description                                                                                                                                     |
-| ------------------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `inherit`                 | string                     | `core`  | Starting template for the environment:<br>`core` (`HOME`, `PATH`, `USER`, …), `all` (clone full parent env), or `none` (start empty).           |
-| `ignore_default_excludes` | boolean                    | `false` | When `false`, Codex removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN` (case-insensitive) before other rules run.              |
-| `exclude`                 | array&lt;string&gt;        | `[]`    | Case-insensitive glob patterns to drop after the default filter.<br>Examples: `"AWS_*"`, `"AZURE_*"`.                                           |
-| `set`                     | table&lt;string,string&gt; | `{}`    | Explicit key/value overrides or additions – always win over inherited values.                                                                   |
-| `include_only`            | array&lt;string&gt;        | `[]`    | If non-empty, a whitelist of patterns; only variables that match _one_ pattern survive the final step. (Generally used with `inherit = "all"`.) |
-
-The patterns are **glob style**, not full regular expressions: `*` matches any
-number of characters, `?` matches exactly one, and character classes like
-`[A-Z]`/`[^0-9]` are supported. Matching is always **case-insensitive**. This
-syntax is documented in code as `EnvironmentVariablePattern` (see
-`core/src/config_types.rs`).
-
-If you just need a clean slate with a few custom entries you can write:
-
-```toml
-[shell_environment_policy]
-inherit = "none"
-set = { PATH = "/usr/bin", MY_FLAG = "1" }
-```
-
-Currently, `CODEX_SANDBOX_NETWORK_DISABLED=1` is also added to the environment, assuming network is disabled. This is not configurable.
-
-### notify
-
-Specify a program that will be executed to get notified about events generated by Codex. Note that the program will receive the notification argument as a string of JSON, e.g.:
-
-```json
-{
-  "type": "agent-turn-complete",
-  "turn-id": "12345",
-  "input-messages": ["Rename `foo` to `bar` and update the callsites."],
-  "last-assistant-message": "Rename complete and verified `cargo build` succeeds."
-}
-```
-
-The `"type"` property will always be set. Currently, `"agent-turn-complete"` is the only notification type that is supported.
-
-As an example, here is a Python script that parses the JSON and decides whether to show a desktop push notification using [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS:
-
-```python
-#!/usr/bin/env python3
-
-import json
-import subprocess
-import sys
-
-
-def main() -> int:
-    if len(sys.argv) != 2:
-        print("Usage: notify.py <NOTIFICATION_JSON>")
-        return 1
-
-    try:
-        notification = json.loads(sys.argv[1])
-    except json.JSONDecodeError:
-        return 1
-
-    match notification_type := notification.get("type"):
-        case "agent-turn-complete":
-            assistant_message = notification.get("last-assistant-message")
-            if assistant_message:
-                title = f"Codex: {assistant_message}"
-            else:
-                title = "Codex: Turn Complete!"
-            input_messages = notification.get("input_messages", [])
-            message = " ".join(input_messages)
-            title += message
-        case _:
-            print(f"not sending a push notification for: {notification_type}")
-            return 0
-
-    subprocess.check_output(
-        [
-            "terminal-notifier",
-            "-title",
-            title,
-            "-message",
-            message,
-            "-group",
-            "codex",
-            "-ignoreDnD",
-            "-activate",
-            "com.googlecode.iterm2",
-        ]
-    )
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
-```
-
-To have Codex use this script for notifications, you would configure it via `notify` in `~/.codex/config.toml` using the appropriate path to `notify.py` on your computer:
-
-```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/cli/src/debug_sandbox.rs

@@ -1,5 +1,6 @@
 use std::path::PathBuf;
 
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
@@ -20,12 +21,14 @@ pub async fn run_command_under_seatbelt(
     let SeatbeltCommand {
         full_auto,
         sandbox,
+        config_overrides,
         command,
     } = command;
     run_command_under_sandbox(
         full_auto,
         sandbox,
         command,
+        config_overrides,
         codex_linux_sandbox_exe,
         SandboxType::Seatbelt,
     )
@@ -39,12 +42,14 @@ pub async fn run_command_under_landlock(
     let LandlockCommand {
         full_auto,
         sandbox,
+        config_overrides,
         command,
     } = command;
     run_command_under_sandbox(
         full_auto,
         sandbox,
         command,
+        config_overrides,
         codex_linux_sandbox_exe,
         SandboxType::Landlock,
     )
@@ -60,16 +65,22 @@ async fn run_command_under_sandbox(
     full_auto: bool,
     sandbox: SandboxPermissionOption,
     command: Vec<String>,
+    config_overrides: CliConfigOverrides,
     codex_linux_sandbox_exe: Option<PathBuf>,
     sandbox_type: SandboxType,
 ) -> anyhow::Result<()> {
     let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
     let cwd = std::env::current_dir()?;
-    let config = Config::load_with_overrides(ConfigOverrides {
-        sandbox_policy: Some(sandbox_policy),
-        codex_linux_sandbox_exe,
-        ..Default::default()
-    })?;
+    let config = Config::load_with_cli_overrides(
+        config_overrides
+            .parse_overrides()
+            .map_err(anyhow::Error::msg)?,
+        ConfigOverrides {
+            sandbox_policy: Some(sandbox_policy),
+            codex_linux_sandbox_exe,
+            ..Default::default()
+        },
+    )?;
     let stdio_policy = StdioPolicy::Inherit;
     let env = create_env(&config.shell_environment_policy);
 

codex-rs/cli/src/lib.rs

@@ -3,6 +3,7 @@ mod exit_status;
 pub mod proto;
 
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 
 #[derive(Debug, Parser)]
@@ -14,6 +15,9 @@ pub struct SeatbeltCommand {
     #[clap(flatten)]
     pub sandbox: SandboxPermissionOption,
 
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
     /// Full command args to run under seatbelt.
     #[arg(trailing_var_arg = true)]
     pub command: Vec<String>,
@@ -28,6 +32,9 @@ pub struct LandlockCommand {
     #[clap(flatten)]
     pub sandbox: SandboxPermissionOption,
 
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
     /// Full command args to run under landlock.
     #[arg(trailing_var_arg = true)]
     pub command: Vec<String>,

codex-rs/cli/src/main.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 use codex_cli::LandlockCommand;
 use codex_cli::SeatbeltCommand;
 use codex_cli::proto;
+use codex_common::CliConfigOverrides;
 use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 use std::path::PathBuf;
@@ -19,6 +20,9 @@ use crate::proto::ProtoCli;
     subcommand_negates_reqs = true
 )]
 struct MultitoolCli {
+    #[clap(flatten)]
+    pub config_overrides: CliConfigOverrides,
+
     #[clap(flatten)]
     interactive: TuiCli,
 
@@ -73,28 +77,34 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
 
     match cli.subcommand {
         None => {
-            codex_tui::run_main(cli.interactive, codex_linux_sandbox_exe)?;
+            let mut tui_cli = cli.interactive;
+            prepend_config_flags(&mut tui_cli.config_overrides, cli.config_overrides);
+            codex_tui::run_main(tui_cli, codex_linux_sandbox_exe)?;
         }
-        Some(Subcommand::Exec(exec_cli)) => {
+        Some(Subcommand::Exec(mut exec_cli)) => {
+            prepend_config_flags(&mut exec_cli.config_overrides, cli.config_overrides);
             codex_exec::run_main(exec_cli, codex_linux_sandbox_exe).await?;
         }
         Some(Subcommand::Mcp) => {
             codex_mcp_server::run_main(codex_linux_sandbox_exe).await?;
         }
-        Some(Subcommand::Proto(proto_cli)) => {
+        Some(Subcommand::Proto(mut proto_cli)) => {
+            prepend_config_flags(&mut proto_cli.config_overrides, cli.config_overrides);
             proto::run_main(proto_cli).await?;
         }
         Some(Subcommand::Debug(debug_args)) => match debug_args.cmd {
-            DebugCommand::Seatbelt(seatbelt_command) => {
+            DebugCommand::Seatbelt(mut seatbelt_cli) => {
+                prepend_config_flags(&mut seatbelt_cli.config_overrides, cli.config_overrides);
                 codex_cli::debug_sandbox::run_command_under_seatbelt(
-                    seatbelt_command,
+                    seatbelt_cli,
                     codex_linux_sandbox_exe,
                 )
                 .await?;
             }
-            DebugCommand::Landlock(landlock_command) => {
+            DebugCommand::Landlock(mut landlock_cli) => {
+                prepend_config_flags(&mut landlock_cli.config_overrides, cli.config_overrides);
                 codex_cli::debug_sandbox::run_command_under_landlock(
-                    landlock_command,
+                    landlock_cli,
                     codex_linux_sandbox_exe,
                 )
                 .await?;
@@ -104,3 +114,14 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
 
     Ok(())
 }
+
+/// Prepend root-level overrides so they have lower precedence than
+/// CLI-specific ones specified after the subcommand (if any).
+fn prepend_config_flags(
+    subcommand_config_overrides: &mut CliConfigOverrides,
+    cli_config_overrides: CliConfigOverrides,
+) {
+    subcommand_config_overrides
+        .raw_overrides
+        .splice(0..0, cli_config_overrides.raw_overrides);
+}

codex-rs/cli/src/proto.rs

@@ -2,6 +2,7 @@ use std::io::IsTerminal;
 use std::sync::Arc;
 
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_core::Codex;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
@@ -13,9 +14,12 @@ use tracing::error;
 use tracing::info;
 
 #[derive(Debug, Parser)]
-pub struct ProtoCli {}
+pub struct ProtoCli {
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+}
 
-pub async fn run_main(_opts: ProtoCli) -> anyhow::Result<()> {
+pub async fn run_main(opts: ProtoCli) -> anyhow::Result<()> {
     if std::io::stdin().is_terminal() {
         anyhow::bail!("Protocol mode expects stdin to be a pipe, not a terminal");
     }
@@ -24,7 +28,12 @@ pub async fn run_main(_opts: ProtoCli) -> anyhow::Result<()> {
         .with_writer(std::io::stderr)
         .init();
 
-    let config = Config::load_with_overrides(ConfigOverrides::default())?;
+    let ProtoCli { config_overrides } = opts;
+    let overrides_vec = config_overrides
+        .parse_overrides()
+        .map_err(anyhow::Error::msg)?;
+
+    let config = Config::load_with_cli_overrides(overrides_vec, ConfigOverrides::default())?;
     let ctrl_c = notify_on_sigint();
     let (codex, _init_id) = Codex::spawn(config, ctrl_c.clone()).await?;
     let codex = Arc::new(codex);

codex-rs/common/Cargo.toml

@@ -9,8 +9,10 @@ workspace = true
 [dependencies]
 clap = { version = "4", features = ["derive", "wrap_help"], optional = true }
 codex-core = { path = "../core" }
+toml = { version = "0.8", optional = true }
+serde = { version = "1", optional = true }
 
 [features]
 # Separate feature so that `clap` is not a mandatory dependency.
-cli = ["clap"]
+cli = ["clap", "toml", "serde"]
 elapsed = []

codex-rs/common/src/config_override.rs

@@ -0,0 +1,170 @@
+//! Support for `-c key=value` overrides shared across Codex CLI tools.
+//!
+//! This module provides a [`CliConfigOverrides`] struct that can be embedded
+//! into a `clap`-derived CLI struct using `#[clap(flatten)]`. Each occurrence
+//! of `-c key=value` (or `--config key=value`) will be collected as a raw
+//! string. Helper methods are provided to convert the raw strings into
+//! key/value pairs as well as to apply them onto a mutable
+//! `serde_json::Value` representing the configuration tree.
+
+use clap::ArgAction;
+use clap::Parser;
+use serde::de::Error as SerdeError;
+use toml::Value;
+
+/// CLI option that captures arbitrary configuration overrides specified as
+/// `-c key=value`. It intentionally keeps both halves **unparsed** so that the
+/// calling code can decide how to interpret the right-hand side.
+#[derive(Parser, Debug, Default, Clone)]
+pub struct CliConfigOverrides {
+    /// Override a configuration value that would otherwise be loaded from
+    /// `~/.codex/config.toml`. Use a dotted path (`foo.bar.baz`) to override
+    /// nested values. The `value` portion is parsed as JSON. If it fails to
+    /// parse as JSON, the raw string is used as a literal.
+    ///
+    /// Examples:
+    ///   - `-c model="o3"`
+    ///   - `-c 'sandbox_permissions=["disk-full-read-access"]'`
+    ///   - `-c shell_environment_policy.inherit=all`
+    #[arg(
+        short = 'c',
+        long = "config",
+        value_name = "key=value",
+        action = ArgAction::Append,
+        global = true,
+    )]
+    pub raw_overrides: Vec<String>,
+}
+
+impl CliConfigOverrides {
+    /// Parse the raw strings captured from the CLI into a list of `(path,
+    /// value)` tuples where `value` is a `serde_json::Value`.
+    pub fn parse_overrides(&self) -> Result<Vec<(String, Value)>, String> {
+        self.raw_overrides
+            .iter()
+            .map(|s| {
+                // Only split on the *first* '=' so values are free to contain
+                // the character.
+                let mut parts = s.splitn(2, '=');
+                let key = match parts.next() {
+                    Some(k) => k.trim(),
+                    None => return Err("Override missing key".to_string()),
+                };
+                let value_str = parts
+                    .next()
+                    .ok_or_else(|| format!("Invalid override (missing '='): {s}"))?
+                    .trim();
+
+                if key.is_empty() {
+                    return Err(format!("Empty key in override: {s}"));
+                }
+
+                // Attempt to parse as JSON. If that fails, treat it as a raw
+                // string. This allows convenient usage such as
+                // `-c model=o3` without the quotes.
+                let value: Value = match parse_toml_value(value_str) {
+                    Ok(v) => v,
+                    Err(_) => Value::String(value_str.to_string()),
+                };
+
+                Ok((key.to_string(), value))
+            })
+            .collect()
+    }
+
+    /// Apply all parsed overrides onto `target`. Intermediate objects will be
+    /// created as necessary. Values located at the destination path will be
+    /// replaced.
+    pub fn apply_on_value(&self, target: &mut Value) -> Result<(), String> {
+        let overrides = self.parse_overrides()?;
+        for (path, value) in overrides {
+            apply_single_override(target, &path, value);
+        }
+        Ok(())
+    }
+}
+
+/// Apply a single override onto `root`, creating intermediate objects as
+/// necessary.
+fn apply_single_override(root: &mut Value, path: &str, value: Value) {
+    use toml::value::Table;
+
+    let parts: Vec<&str> = path.split('.').collect();
+    let mut current = root;
+
+    for (i, part) in parts.iter().enumerate() {
+        let is_last = i == parts.len() - 1;
+
+        if is_last {
+            match current {
+                Value::Table(tbl) => {
+                    tbl.insert((*part).to_string(), value);
+                }
+                _ => {
+                    let mut tbl = Table::new();
+                    tbl.insert((*part).to_string(), value);
+                    *current = Value::Table(tbl);
+                }
+            }
+            return;
+        }
+
+        // Traverse or create intermediate table.
+        match current {
+            Value::Table(tbl) => {
+                current = tbl
+                    .entry((*part).to_string())
+                    .or_insert_with(|| Value::Table(Table::new()));
+            }
+            _ => {
+                *current = Value::Table(Table::new());
+                if let Value::Table(tbl) = current {
+                    current = tbl
+                        .entry((*part).to_string())
+                        .or_insert_with(|| Value::Table(Table::new()));
+                }
+            }
+        }
+    }
+}
+
+fn parse_toml_value(raw: &str) -> Result<Value, toml::de::Error> {
+    let wrapped = format!("_x_ = {raw}");
+    let table: toml::Table = toml::from_str(&wrapped)?;
+    table
+        .get("_x_")
+        .cloned()
+        .ok_or_else(|| SerdeError::custom("missing sentinel key"))
+}
+
+#[cfg(all(test, feature = "cli"))]
+#[allow(clippy::expect_used, clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_basic_scalar() {
+        let v = parse_toml_value("42").expect("parse");
+        assert_eq!(v.as_integer(), Some(42));
+    }
+
+    #[test]
+    fn fails_on_unquoted_string() {
+        assert!(parse_toml_value("hello").is_err());
+    }
+
+    #[test]
+    fn parses_array() {
+        let v = parse_toml_value("[1, 2, 3]").expect("parse");
+        let arr = v.as_array().expect("array");
+        assert_eq!(arr.len(), 3);
+    }
+
+    #[test]
+    fn parses_inline_table() {
+        let v = parse_toml_value("{a = 1, b = 2}").expect("parse");
+        let tbl = v.as_table().expect("table");
+        assert_eq!(tbl.get("a").unwrap().as_integer(), Some(1));
+        assert_eq!(tbl.get("b").unwrap().as_integer(), Some(2));
+    }
+}

codex-rs/common/src/lib.rs

@@ -8,3 +8,9 @@ pub mod elapsed;
 pub use approval_mode_cli_arg::ApprovalModeCliArg;
 #[cfg(feature = "cli")]
 pub use approval_mode_cli_arg::SandboxPermissionOption;
+
+#[cfg(any(feature = "cli", test))]
+mod config_override;
+
+#[cfg(feature = "cli")]
+pub use config_override::CliConfigOverrides;

codex-rs/config.md

@@ -0,0 +1,387 @@
+# Config
+
+Codex supports several mechanisms for setting config values:
+
+- Config-specific command-line flags, such as `--model o3` (highest precedence).
+- A generic `-c`/`--config` flag that takes a `key=value` pair, such as `--config model="o3"`.
+  - The key can contain dots to set a value deeper than the root, e.g. `--config model_providers.openai.wire_api="chat"`.
+  - Values can contain objects, such as `--config shell_environment_policy.include_only=["PATH", "HOME", "USER"]`.
+  - For consistency with `config.toml`, values are in TOML format rather than JSON format, so use `{a = 1, b = 2}` rather than `{"a": 1, "b": 2}`.
+  - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that both `-c model="o3"` and `-c model=o3` are equivalent.
+- The `$CODEX_HOME/config.toml` configuration file where the `CODEX_HOME` environment value defaults to `~/.codex`. (Note `CODEX_HOME` will also be where logs and other Codex-related information are stored.)
+
+Both the `--config` flag and the `config.toml` file support the following options:
+
+## model
+
+The model that Codex should use.
+
+```toml
+model = "o3"  # overrides the default of "codex-mini-latest"
+```
+
+## model_provider
+
+Codex comes bundled with a number of "model providers" predefined. This config value is a string that indicates which provider to use. You can also define your own providers via `model_providers`.
+
+For example, if you are running ollama with Mistral locally, then you would need to add the following to your config:
+
+```toml
+model = "mistral"
+model_provider = "ollama"
+```
+
+because the following definition for `ollama` is included in Codex:
+
+```toml
+[model_providers.ollama]
+name = "Ollama"
+base_url = "http://localhost:11434/v1"
+wire_api = "chat"
+```
+
+This option defaults to `"openai"` and the corresponding provider is defined as follows:
+
+```toml
+[model_providers.openai]
+name = "OpenAI"
+base_url = "https://api.openai.com/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "responses"
+```
+
+## model_providers
+
+This option lets you override and amend the default set of model providers bundled with Codex. This value is a map where the key is the value to use with `model_provider` to select the correspodning provider.
+
+For example, if you wanted to add a provider that uses the OpenAI 4o model via the chat completions API, then you
+
+```toml
+# Recall that in TOML, root keys must be listed before tables.
+model = "gpt-4o"
+model_provider = "openai-chat-completions"
+
+[model_providers.openai-chat-completions]
+# Name of the provider that will be displayed in the Codex UI.
+name = "OpenAI using Chat Completions"
+# The path `/chat/completions` will be amended to this URL to make the POST
+# request for the chat completions.
+base_url = "https://api.openai.com/v1"
+# If `env_key` is set, identifies an environment variable that must be set when
+# using Codex with this provider. The value of the environment variable must be
+# non-empty and will be used in the `Bearer TOKEN` HTTP header for the POST request.
+env_key = "OPENAI_API_KEY"
+# valid values for wire_api are "chat" and "responses".
+wire_api = "chat"
+```
+
+## approval_policy
+
+Determines when the user should be prompted to approve whether Codex can execute a command:
+
+```toml
+# This is analogous to --suggest in the TypeScript Codex CLI
+approval_policy = "unless-allow-listed"
+```
+
+```toml
+# If the command fails when run in the sandbox, Codex asks for permission to
+# retry the command outside the sandbox.
+approval_policy = "on-failure"
+```
+
+```toml
+# User is never prompted: if the command fails, Codex will automatically try
+# something out. Note the `exec` subcommand always uses this mode.
+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 `codex-mini-latest`)
+
+## sandbox_permissions
+
+List of permissions to grant to the sandbox that Codex uses to execute untrusted commands:
+
+```toml
+# This is comparable to --full-auto in the TypeScript Codex CLI, though
+# specifying `disk-write-platform-global-temp-folder` adds /tmp as a writable
+# folder in addition to $TMPDIR.
+sandbox_permissions = [
+    "disk-full-read-access",
+    "disk-write-platform-user-temp-folder",
+    "disk-write-platform-global-temp-folder",
+    "disk-write-cwd",
+]
+```
+
+To add additional writable folders, use `disk-write-folder`, which takes a parameter (this can be specified multiple times):
+
+```toml
+sandbox_permissions = [
+    # ...
+    "disk-write-folder=/Users/mbolin/.pyenv/shims",
+]
+```
+
+## mcp_servers
+
+Defines the list of MCP servers that Codex can consult for tool use. Currently, only servers that are launched by executing a program that communicate over stdio are supported. For servers that use the SSE transport, consider an adapter like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
+
+**Note:** Codex may cache the list of tools and resources from an MCP server so that Codex can include this information in context at startup without spawning all the servers. This is designed to save resources by loading MCP servers lazily.
+
+This config option is comparable to how Claude and Cursor define `mcpServers` in their respective JSON config files, though because Codex uses TOML for its config language, the format is slightly different. For example, the following config in JSON:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "mcp-server"],
+      "env": {
+        "API_KEY": "value"
+      }
+    }
+  }
+}
+```
+
+Should be represented as follows in `~/.codex/config.toml`:
+
+```toml
+# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
+[mcp_servers.server-name]
+command = "npx"
+args = ["-y", "mcp-server"]
+env = { "API_KEY" = "value" }
+```
+
+## disable_response_storage
+
+Currently, customers whose accounts are set to use Zero Data Retention (ZDR) must set `disable_response_storage` to `true` so that Codex uses an alternative to the Responses API that works with ZDR:
+
+```toml
+disable_response_storage = true
+```
+
+## shell_environment_policy
+
+Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it passes **only a minimal core subset** of your environment to those subprocesses to avoid leaking credentials. You can tune this behavior via the **`shell_environment_policy`** block in
+`config.toml`:
+
+```toml
+[shell_environment_policy]
+# inherit can be "core" (default), "all", or "none"
+inherit = "core"
+# set to true to *skip* the filter for `"*KEY*"` and `"*TOKEN*"`
+ignore_default_excludes = false
+# exclude patterns (case-insensitive globs)
+exclude = ["AWS_*", "AZURE_*"]
+# force-set / override values
+set = { CI = "1" }
+# if provided, *only* vars matching these patterns are kept
+include_only = ["PATH", "HOME"]
+```
+
+| Field                     | Type                       | Default | Description                                                                                                                                     |
+| ------------------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inherit`                 | string                     | `core`  | Starting template for the environment:<br>`core` (`HOME`, `PATH`, `USER`, …), `all` (clone full parent env), or `none` (start empty).           |
+| `ignore_default_excludes` | boolean                    | `false` | When `false`, Codex removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN` (case-insensitive) before other rules run.              |
+| `exclude`                 | array&lt;string&gt;        | `[]`    | Case-insensitive glob patterns to drop after the default filter.<br>Examples: `"AWS_*"`, `"AZURE_*"`.                                           |
+| `set`                     | table&lt;string,string&gt; | `{}`    | Explicit key/value overrides or additions – always win over inherited values.                                                                   |
+| `include_only`            | array&lt;string&gt;        | `[]`    | If non-empty, a whitelist of patterns; only variables that match _one_ pattern survive the final step. (Generally used with `inherit = "all"`.) |
+
+The patterns are **glob style**, not full regular expressions: `*` matches any
+number of characters, `?` matches exactly one, and character classes like
+`[A-Z]`/`[^0-9]` are supported. Matching is always **case-insensitive**. This
+syntax is documented in code as `EnvironmentVariablePattern` (see
+`core/src/config_types.rs`).
+
+If you just need a clean slate with a few custom entries you can write:
+
+```toml
+[shell_environment_policy]
+inherit = "none"
+set = { PATH = "/usr/bin", MY_FLAG = "1" }
+```
+
+Currently, `CODEX_SANDBOX_NETWORK_DISABLED=1` is also added to the environment, assuming network is disabled. This is not configurable.
+
+## notify
+
+Specify a program that will be executed to get notified about events generated by Codex. Note that the program will receive the notification argument as a string of JSON, e.g.:
+
+```json
+{
+  "type": "agent-turn-complete",
+  "turn-id": "12345",
+  "input-messages": ["Rename `foo` to `bar` and update the callsites."],
+  "last-assistant-message": "Rename complete and verified `cargo build` succeeds."
+}
+```
+
+The `"type"` property will always be set. Currently, `"agent-turn-complete"` is the only notification type that is supported.
+
+As an example, here is a Python script that parses the JSON and decides whether to show a desktop push notification using [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS:
+
+```python
+#!/usr/bin/env python3
+
+import json
+import subprocess
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: notify.py <NOTIFICATION_JSON>")
+        return 1
+
+    try:
+        notification = json.loads(sys.argv[1])
+    except json.JSONDecodeError:
+        return 1
+
+    match notification_type := notification.get("type"):
+        case "agent-turn-complete":
+            assistant_message = notification.get("last-assistant-message")
+            if assistant_message:
+                title = f"Codex: {assistant_message}"
+            else:
+                title = "Codex: Turn Complete!"
+            input_messages = notification.get("input_messages", [])
+            message = " ".join(input_messages)
+            title += message
+        case _:
+            print(f"not sending a push notification for: {notification_type}")
+            return 0
+
+    subprocess.check_output(
+        [
+            "terminal-notifier",
+            "-title",
+            title,
+            "-message",
+            message,
+            "-group",
+            "codex",
+            "-ignoreDnD",
+            "-activate",
+            "com.googlecode.iterm2",
+        ]
+    )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+To have Codex use this script for notifications, you would configure it via `notify` in `~/.codex/config.toml` using the appropriate path to `notify.py` on your computer:
+
+```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.
+
+## hide_agent_reasoning
+
+Codex intermittently emits "reasoning" events that show the model’s internal "thinking" before it produces a final answer. Some users may find these events distracting, especially in CI logs or minimal terminal output.
+
+Setting `hide_agent_reasoning` to `true` suppresses these events in **both** the TUI as well as the headless `exec` sub-command:
+
+```toml
+hide_agent_reasoning = true   # defaults to false
+```
+
+## 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/core/src/chat_completions.rs

@@ -25,6 +25,7 @@ use crate::flags::OPENAI_REQUEST_MAX_RETRIES;
 use crate::flags::OPENAI_STREAM_IDLE_TIMEOUT_MS;
 use crate::models::ContentItem;
 use crate::models::ResponseItem;
+use crate::openai_tools::create_tools_json_for_chat_completions_api;
 use crate::util::backoff;
 
 /// Implementation for the classic Chat Completions API. This is intentionally
@@ -56,17 +57,22 @@ pub(crate) async fn stream_chat_completions(
         }
     }
 
+    let tools_json = create_tools_json_for_chat_completions_api(prompt, model)?;
     let payload = json!({
         "model": model,
         "messages": messages,
-        "stream": true
+        "stream": true,
+        "tools": tools_json,
     });
 
     let base_url = provider.base_url.trim_end_matches('/');
     let url = format!("{}/chat/completions", base_url);
 
     debug!(url, "POST (chat)");
-    trace!("request payload: {}", payload);
+    trace!(
+        "request payload: {}",
+        serde_json::to_string_pretty(&payload).unwrap_or_default()
+    );
 
     let api_key = provider.api_key()?;
     let mut attempt = 0;

codex-rs/core/src/client.rs

@@ -1,7 +1,5 @@
-use std::collections::BTreeMap;
 use std::io::BufRead;
 use std::path::Path;
-use std::sync::LazyLock;
 use std::time::Duration;
 
 use bytes::Bytes;
@@ -11,7 +9,6 @@ use reqwest::StatusCode;
 use serde::Deserialize;
 use serde::Serialize;
 use serde_json::Value;
-use serde_json::json;
 use tokio::sync::mpsc;
 use tokio::time::timeout;
 use tokio_util::io::ReaderStream;
@@ -36,71 +33,9 @@ use crate::flags::OPENAI_STREAM_IDLE_TIMEOUT_MS;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::WireApi;
 use crate::models::ResponseItem;
+use crate::openai_tools::create_tools_json_for_responses_api;
 use crate::util::backoff;
 
-/// When serialized as JSON, this produces a valid "Tool" in the OpenAI
-/// Responses API.
-#[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,
-    description: &'static str,
-    strict: bool,
-    parameters: JsonSchema,
-}
-
-/// Generic JSON‑Schema subset needed for our tool definitions
-#[derive(Debug, Clone, Serialize)]
-#[serde(tag = "type", rename_all = "lowercase")]
-enum JsonSchema {
-    String,
-    Number,
-    Array {
-        items: Box<JsonSchema>,
-    },
-    Object {
-        properties: BTreeMap<String, JsonSchema>,
-        required: &'static [&'static str],
-        #[serde(rename = "additionalProperties")]
-        additional_properties: bool,
-    },
-}
-
-/// Tool usage specification
-static DEFAULT_TOOLS: LazyLock<Vec<OpenAiTool>> = LazyLock::new(|| {
-    let mut properties = BTreeMap::new();
-    properties.insert(
-        "command".to_string(),
-        JsonSchema::Array {
-            items: Box::new(JsonSchema::String),
-        },
-    );
-    properties.insert("workdir".to_string(), JsonSchema::String);
-    properties.insert("timeout".to_string(), JsonSchema::Number);
-
-    vec![OpenAiTool::Function(ResponsesApiTool {
-        name: "shell",
-        description: "Runs a shell command, and returns its output.",
-        strict: false,
-        parameters: JsonSchema::Object {
-            properties,
-            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,
@@ -161,27 +96,8 @@ impl ModelClient {
             return stream_from_fixture(path).await;
         }
 
-        // Assemble tool list: built-in tools + any extra tools from the prompt.
-        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
-                .clone()
-                .into_iter()
-                .map(|(name, tool)| mcp_tool_to_openai_tool(name, tool)),
-        );
-
-        debug!("tools_json: {}", serde_json::to_string_pretty(&tools_json)?);
-
         let full_instructions = prompt.get_full_instructions();
+        let tools_json = create_tools_json_for_responses_api(prompt, &self.model)?;
         let payload = Payload {
             model: &self.model,
             instructions: &full_instructions,
@@ -276,20 +192,6 @@ impl ModelClient {
     }
 }
 
-fn mcp_tool_to_openai_tool(
-    fully_qualified_name: String,
-    tool: mcp_types::Tool,
-) -> serde_json::Value {
-    // TODO(mbolin): Change the contract of this function to return
-    // ResponsesApiTool.
-    json!({
-        "name": fully_qualified_name,
-        "description": tool.description,
-        "parameters": tool.input_schema,
-        "type": "function",
-    })
-}
-
 #[derive(Debug, Deserialize, Serialize)]
 struct SseEvent {
     #[serde(rename = "type")]

codex-rs/core/src/config.rs

@@ -16,6 +16,7 @@ use serde::Deserialize;
 use std::collections::HashMap;
 use std::path::Path;
 use std::path::PathBuf;
+use toml::Value as TomlValue;
 
 /// 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
@@ -41,6 +42,11 @@ pub struct Config {
 
     pub shell_environment_policy: ShellEnvironmentPolicy,
 
+    /// When `true`, `AgentReasoning` events emitted by the backend will be
+    /// suppressed from the frontend output. This can reduce visual noise when
+    /// users are only interested in the final agent responses.
+    pub hide_agent_reasoning: bool,
+
     /// Disable server-side response storage (sends the full conversation
     /// context with every request). Currently necessary for OpenAI customers
     /// who have opted into Zero Data Retention (ZDR).
@@ -108,6 +114,108 @@ pub struct Config {
     pub codex_linux_sandbox_exe: Option<PathBuf>,
 }
 
+impl Config {
+    /// Load configuration with *generic* CLI overrides (`-c key=value`) applied
+    /// **in between** the values parsed from `config.toml` and the
+    /// strongly-typed overrides specified via [`ConfigOverrides`].
+    ///
+    /// The precedence order is therefore: `config.toml` < `-c` overrides <
+    /// `ConfigOverrides`.
+    pub fn load_with_cli_overrides(
+        cli_overrides: Vec<(String, TomlValue)>,
+        overrides: ConfigOverrides,
+    ) -> std::io::Result<Self> {
+        // 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()?;
+
+        // Step 1: parse `config.toml` into a generic JSON value.
+        let mut root_value = load_config_as_toml(&codex_home)?;
+
+        // Step 2: apply the `-c` overrides.
+        for (path, value) in cli_overrides.into_iter() {
+            apply_toml_override(&mut root_value, &path, value);
+        }
+
+        // Step 3: deserialize into `ConfigToml` so that Serde can enforce the
+        // correct types.
+        let cfg: ConfigToml = root_value.try_into().map_err(|e| {
+            tracing::error!("Failed to deserialize overridden config: {e}");
+            std::io::Error::new(std::io::ErrorKind::InvalidData, e)
+        })?;
+
+        // Step 4: merge with the strongly-typed overrides.
+        Self::load_from_base_config_with_overrides(cfg, overrides, codex_home)
+    }
+}
+
+/// Read `CODEX_HOME/config.toml` and return it as a generic TOML value. Returns
+/// an empty TOML table when the file does not exist.
+fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
+    let config_path = codex_home.join("config.toml");
+    match std::fs::read_to_string(&config_path) {
+        Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
+            Ok(val) => Ok(val),
+            Err(e) => {
+                tracing::error!("Failed to parse config.toml: {e}");
+                Err(std::io::Error::new(std::io::ErrorKind::InvalidData, e))
+            }
+        },
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            tracing::info!("config.toml not found, using defaults");
+            Ok(TomlValue::Table(Default::default()))
+        }
+        Err(e) => {
+            tracing::error!("Failed to read config.toml: {e}");
+            Err(e)
+        }
+    }
+}
+
+/// Apply a single dotted-path override onto a TOML value.
+fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue) {
+    use toml::value::Table;
+
+    let segments: Vec<&str> = path.split('.').collect();
+    let mut current = root;
+
+    for (idx, segment) in segments.iter().enumerate() {
+        let is_last = idx == segments.len() - 1;
+
+        if is_last {
+            match current {
+                TomlValue::Table(table) => {
+                    table.insert(segment.to_string(), value);
+                }
+                _ => {
+                    let mut table = Table::new();
+                    table.insert(segment.to_string(), value);
+                    *current = TomlValue::Table(table);
+                }
+            }
+            return;
+        }
+
+        // Traverse or create intermediate object.
+        match current {
+            TomlValue::Table(table) => {
+                current = table
+                    .entry(segment.to_string())
+                    .or_insert_with(|| TomlValue::Table(Table::new()));
+            }
+            _ => {
+                *current = TomlValue::Table(Table::new());
+                if let TomlValue::Table(tbl) = current {
+                    current = tbl
+                        .entry(segment.to_string())
+                        .or_insert_with(|| TomlValue::Table(Table::new()));
+                }
+            }
+        }
+    }
+}
+
 /// Base config deserialized from ~/.codex/config.toml.
 #[derive(Deserialize, Debug, Clone, Default)]
 pub struct ConfigToml {
@@ -169,29 +277,10 @@ pub struct ConfigToml {
 
     /// 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(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}");
-                std::io::Error::new(std::io::ErrorKind::InvalidData, e)
-            }),
-            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
-                tracing::info!("config.toml not found, using defaults");
-                Ok(Self::default())
-            }
-            Err(e) => {
-                tracing::error!("Failed to read config.toml: {e}");
-                Err(e)
-            }
-        }
-    }
+    /// When set to `true`, `AgentReasoning` events will be hidden from the
+    /// UI/output. Defaults to `false`.
+    pub hide_agent_reasoning: Option<bool>,
 }
 
 fn deserialize_sandbox_permissions<'de, D>(
@@ -227,28 +316,12 @@ pub struct ConfigOverrides {
     pub cwd: Option<PathBuf>,
     pub approval_policy: Option<AskForApproval>,
     pub sandbox_policy: Option<SandboxPolicy>,
-    pub disable_response_storage: Option<bool>,
     pub model_provider: Option<String>,
     pub config_profile: Option<String>,
     pub codex_linux_sandbox_exe: Option<PathBuf>,
 }
 
 impl Config {
-    /// Load configuration, optionally applying overrides (CLI flags). Merges
-    /// ~/.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> {
-        // 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, codex_home)
-    }
-
     /// 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(
@@ -264,7 +337,6 @@ impl Config {
             cwd,
             approval_policy,
             sandbox_policy,
-            disable_response_storage,
             model_provider,
             config_profile: config_profile_key,
             codex_linux_sandbox_exe,
@@ -356,8 +428,8 @@ impl Config {
                 .unwrap_or_else(AskForApproval::default),
             sandbox_policy,
             shell_environment_policy,
-            disable_response_storage: disable_response_storage
-                .or(config_profile.disable_response_storage)
+            disable_response_storage: config_profile
+                .disable_response_storage
                 .or(cfg.disable_response_storage)
                 .unwrap_or(false),
             notify: cfg.notify,
@@ -370,6 +442,8 @@ impl Config {
             file_opener: cfg.file_opener.unwrap_or(UriBasedFileOpener::VsCode),
             tui: cfg.tui.unwrap_or_default(),
             codex_linux_sandbox_exe,
+
+            hide_agent_reasoning: cfg.hide_agent_reasoning.unwrap_or(false),
         };
         Ok(config)
     }
@@ -711,6 +785,7 @@ disable_response_storage = true
                 file_opener: UriBasedFileOpener::VsCode,
                 tui: Tui::default(),
                 codex_linux_sandbox_exe: None,
+                hide_agent_reasoning: false,
             },
             o3_profile_config
         );
@@ -750,6 +825,7 @@ disable_response_storage = true
             file_opener: UriBasedFileOpener::VsCode,
             tui: Tui::default(),
             codex_linux_sandbox_exe: None,
+            hide_agent_reasoning: false,
         };
 
         assert_eq!(expected_gpt3_profile_config, gpt3_profile_config);
@@ -804,6 +880,7 @@ disable_response_storage = true
             file_opener: UriBasedFileOpener::VsCode,
             tui: Tui::default(),
             codex_linux_sandbox_exe: None,
+            hide_agent_reasoning: false,
         };
 
         assert_eq!(expected_zdr_profile_config, zdr_profile_config);

codex-rs/core/src/config_types.rs

@@ -89,7 +89,7 @@ pub struct Tui {
 }
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
-
+#[serde(rename_all = "kebab-case")]
 pub enum ShellEnvironmentPolicyInherit {
     /// "Core" environment variables for the platform. On UNIX, this would
     /// include HOME, LOGNAME, PATH, SHELL, and USER, among others.

codex-rs/core/src/lib.rs

@@ -27,6 +27,7 @@ mod model_provider_info;
 pub use model_provider_info::ModelProviderInfo;
 pub use model_provider_info::WireApi;
 mod models;
+mod openai_tools;
 mod project_doc;
 pub mod protocol;
 mod rollout;

codex-rs/core/src/mcp_tool_call.rs

@@ -50,51 +50,18 @@ pub(crate) async fn handle_mcp_tool_call(
     notify_mcp_tool_call_event(sess, sub_id, tool_call_begin_event).await;
 
     // Perform the tool call.
-    let (tool_call_end_event, tool_call_err) = match sess
+    let result = sess
         .call_tool(&server, &tool_name, arguments_value, timeout)
         .await
-    {
-        Ok(result) => (
-            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
-                call_id,
-                success: !result.is_error.unwrap_or(false),
-                result: Some(result),
-            }),
-            None,
-        ),
-        Err(e) => (
-            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
-                call_id,
-                success: false,
-                result: None,
-            }),
-            Some(e),
-        ),
-    };
+        .map_err(|e| format!("tool call error: {e}"));
+    let tool_call_end_event = EventMsg::McpToolCallEnd(McpToolCallEndEvent {
+        call_id: call_id.clone(),
+        result: result.clone(),
+    });
 
     notify_mcp_tool_call_event(sess, sub_id, tool_call_end_event.clone()).await;
-    let EventMsg::McpToolCallEnd(McpToolCallEndEvent {
-        call_id,
-        success,
-        result,
-    }) = tool_call_end_event
-    else {
-        unimplemented!("unexpected event type");
-    };
 
-    ResponseInputItem::FunctionCallOutput {
-        call_id,
-        output: FunctionCallOutputPayload {
-            content: result.map_or_else(
-                || format!("err: {tool_call_err:?}"),
-                |result| {
-                    serde_json::to_string(&result)
-                        .unwrap_or_else(|e| format!("JSON serialization error: {e}"))
-                },
-            ),
-            success: Some(success),
-        },
-    }
+    ResponseInputItem::McpToolCallOutput { call_id, result }
 }
 
 async fn notify_mcp_tool_call_event(sess: &Session, sub_id: &str, event: EventMsg) {

codex-rs/core/src/models.rs

@@ -1,6 +1,7 @@
 use std::collections::HashMap;
 
 use base64::Engine;
+use mcp_types::CallToolResult;
 use serde::Deserialize;
 use serde::Serialize;
 use serde::ser::Serializer;
@@ -18,6 +19,10 @@ pub enum ResponseInputItem {
         call_id: String,
         output: FunctionCallOutputPayload,
     },
+    McpToolCallOutput {
+        call_id: String,
+        result: Result<CallToolResult, String>,
+    },
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -77,6 +82,19 @@ impl From<ResponseInputItem> for ResponseItem {
             ResponseInputItem::FunctionCallOutput { call_id, output } => {
                 Self::FunctionCallOutput { call_id, output }
             }
+            ResponseInputItem::McpToolCallOutput { call_id, result } => Self::FunctionCallOutput {
+                call_id,
+                output: FunctionCallOutputPayload {
+                    success: Some(result.is_ok()),
+                    content: result.map_or_else(
+                        |tool_call_err| format!("err: {tool_call_err:?}"),
+                        |result| {
+                            serde_json::to_string(&result)
+                                .unwrap_or_else(|e| format!("JSON serialization error: {e}"))
+                        },
+                    ),
+                },
+            },
         }
     }
 }

codex-rs/core/src/openai_tools.rs

@@ -0,0 +1,158 @@
+use serde::Serialize;
+use serde_json::json;
+use std::collections::BTreeMap;
+use std::sync::LazyLock;
+
+use crate::client_common::Prompt;
+
+#[derive(Debug, Clone, Serialize)]
+pub(crate) struct ResponsesApiTool {
+    name: &'static str,
+    description: &'static str,
+    strict: bool,
+    parameters: JsonSchema,
+}
+
+/// When serialized as JSON, this produces a valid "Tool" in the OpenAI
+/// Responses API.
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type")]
+pub(crate) enum OpenAiTool {
+    #[serde(rename = "function")]
+    Function(ResponsesApiTool),
+    #[serde(rename = "local_shell")]
+    LocalShell {},
+}
+
+/// Generic JSON‑Schema subset needed for our tool definitions
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub(crate) enum JsonSchema {
+    String,
+    Number,
+    Array {
+        items: Box<JsonSchema>,
+    },
+    Object {
+        properties: BTreeMap<String, JsonSchema>,
+        required: &'static [&'static str],
+        #[serde(rename = "additionalProperties")]
+        additional_properties: bool,
+    },
+}
+
+/// Tool usage specification
+static DEFAULT_TOOLS: LazyLock<Vec<OpenAiTool>> = LazyLock::new(|| {
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "command".to_string(),
+        JsonSchema::Array {
+            items: Box::new(JsonSchema::String),
+        },
+    );
+    properties.insert("workdir".to_string(), JsonSchema::String);
+    properties.insert("timeout".to_string(), JsonSchema::Number);
+
+    vec![OpenAiTool::Function(ResponsesApiTool {
+        name: "shell",
+        description: "Runs a shell command, and returns its output.",
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: &["command"],
+            additional_properties: false,
+        },
+    })]
+});
+
+static DEFAULT_CODEX_MODEL_TOOLS: LazyLock<Vec<OpenAiTool>> =
+    LazyLock::new(|| vec![OpenAiTool::LocalShell {}]);
+
+/// Returns JSON values that are compatible with Function Calling in the
+/// Responses API:
+/// https://platform.openai.com/docs/guides/function-calling?api-mode=responses
+pub(crate) fn create_tools_json_for_responses_api(
+    prompt: &Prompt,
+    model: &str,
+) -> crate::error::Result<Vec<serde_json::Value>> {
+    // Assemble tool list: built-in tools + any extra tools from the prompt.
+    let default_tools = if 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
+            .clone()
+            .into_iter()
+            .map(|(name, tool)| mcp_tool_to_openai_tool(name, tool)),
+    );
+
+    tracing::debug!("tools_json: {}", serde_json::to_string_pretty(&tools_json)?);
+    Ok(tools_json)
+}
+
+/// Returns JSON values that are compatible with Function Calling in the
+/// Chat Completions API:
+/// https://platform.openai.com/docs/guides/function-calling?api-mode=chat
+pub(crate) fn create_tools_json_for_chat_completions_api(
+    prompt: &Prompt,
+    model: &str,
+) -> crate::error::Result<Vec<serde_json::Value>> {
+    // We start with the JSON for the Responses API and than rewrite it to match
+    // the chat completions tool call format.
+    let responses_api_tools_json = create_tools_json_for_responses_api(prompt, model)?;
+    let tools_json = responses_api_tools_json
+        .into_iter()
+        .filter_map(|mut tool| {
+            if tool.get("type") != Some(&serde_json::Value::String("function".to_string())) {
+                return None;
+            }
+
+            if let Some(map) = tool.as_object_mut() {
+                // Remove "type" field as it is not needed in chat completions.
+                map.remove("type");
+                Some(json!({
+                    "type": "function",
+                    "function": map,
+                }))
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<serde_json::Value>>();
+    Ok(tools_json)
+}
+
+fn mcp_tool_to_openai_tool(
+    fully_qualified_name: String,
+    tool: mcp_types::Tool,
+) -> serde_json::Value {
+    let mcp_types::Tool {
+        description,
+        mut input_schema,
+        ..
+    } = tool;
+
+    // OpenAI models mandate the "properties" field in the schema. The Agents
+    // SDK fixed this by inserting an empty object for "properties" if it is not
+    // already present https://github.com/openai/openai-agents-python/issues/449
+    // so here we do the same.
+    if input_schema.properties.is_none() {
+        input_schema.properties = Some(serde_json::Value::Object(serde_json::Map::new()));
+    }
+
+    // TODO(mbolin): Change the contract of this function to return
+    // ResponsesApiTool.
+    json!({
+        "name": fully_qualified_name,
+        "description": description,
+        "parameters": input_schema,
+        "type": "function",
+    })
+}

codex-rs/core/src/protocol.rs

@@ -396,10 +396,17 @@ pub struct McpToolCallBeginEvent {
 pub struct McpToolCallEndEvent {
     /// Identifier for the corresponding McpToolCallBegin that finished.
     pub call_id: String,
-    /// Whether the tool call was successful. If `false`, `result` might not be present.
-    pub success: bool,
     /// Result of the tool call. Note this could be an error.
-    pub result: Option<CallToolResult>,
+    pub result: Result<CallToolResult, String>,
+}
+
+impl McpToolCallEndEvent {
+    pub fn is_success(&self) -> bool {
+        match &self.result {
+            Ok(result) => !result.is_error.unwrap_or(false),
+            Err(_) => false,
+        }
+    }
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
@@ -554,7 +561,7 @@ mod tests {
             id: "1234".to_string(),
             msg: EventMsg::SessionConfigured(SessionConfiguredEvent {
                 session_id,
-                model: "o4-mini".to_string(),
+                model: "codex-mini-latest".to_string(),
                 history_log_id: 0,
                 history_entry_count: 0,
             }),
@@ -562,7 +569,7 @@ mod tests {
         let serialized = serde_json::to_string(&event).unwrap();
         assert_eq!(
             serialized,
-            r#"{"id":"1234","msg":{"type":"session_configured","session_id":"67e55044-10b1-426f-9247-bb680e5fe0c8","model":"o4-mini","history_log_id":0,"history_entry_count":0}}"#
+            r#"{"id":"1234","msg":{"type":"session_configured","session_id":"67e55044-10b1-426f-9247-bb680e5fe0c8","model":"codex-mini-latest","history_log_id":0,"history_entry_count":0}}"#
         );
     }
 }

codex-rs/exec/src/cli.rs

@@ -1,5 +1,6 @@
 use clap::Parser;
 use clap::ValueEnum;
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 use std::path::PathBuf;
 
@@ -33,9 +34,8 @@ pub struct Cli {
     #[arg(long = "skip-git-repo-check", default_value_t = false)]
     pub skip_git_repo_check: bool,
 
-    /// Disable server‑side response storage (sends the full conversation context with every request)
-    #[arg(long = "disable-response-storage", default_value_t = false)]
-    pub disable_response_storage: bool,
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
 
     /// Specifies color settings for use in the output.
     #[arg(long = "color", value_enum, default_value_t = Color::Auto)]
@@ -45,8 +45,10 @@ pub struct Cli {
     #[arg(long = "output-last-message")]
     pub last_message_file: Option<PathBuf>,
 
-    /// Initial instructions for the agent.
-    pub prompt: String,
+    /// Initial instructions for the agent. If not provided as an argument (or
+    /// if `-` is used), instructions are read from stdin.
+    #[arg(value_name = "PROMPT")]
+    pub prompt: Option<String>,
 }
 
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)]

codex-rs/exec/src/event_processor.rs

@@ -1,4 +1,3 @@
-use chrono::Utc;
 use codex_common::elapsed::format_elapsed;
 use codex_core::config::Config;
 use codex_core::protocol::AgentMessageEvent;
@@ -37,15 +36,20 @@ pub(crate) struct EventProcessor {
     // using .style() with one of these fields. If you need a new style, add a
     // new field here.
     bold: Style,
+    italic: Style,
     dimmed: Style,
 
     magenta: Style,
     red: Style,
     green: Style,
+    cyan: Style,
+
+    /// Whether to include `AgentReasoning` events in the output.
+    show_agent_reasoning: bool,
 }
 
 impl EventProcessor {
-    pub(crate) fn create_with_ansi(with_ansi: bool) -> Self {
+    pub(crate) fn create_with_ansi(with_ansi: bool, show_agent_reasoning: bool) -> Self {
         let call_id_to_command = HashMap::new();
         let call_id_to_patch = HashMap::new();
         let call_id_to_tool_call = HashMap::new();
@@ -55,22 +59,28 @@ impl EventProcessor {
                 call_id_to_command,
                 call_id_to_patch,
                 bold: Style::new().bold(),
+                italic: Style::new().italic(),
                 dimmed: Style::new().dimmed(),
                 magenta: Style::new().magenta(),
                 red: Style::new().red(),
                 green: Style::new().green(),
+                cyan: Style::new().cyan(),
                 call_id_to_tool_call,
+                show_agent_reasoning,
             }
         } else {
             Self {
                 call_id_to_command,
                 call_id_to_patch,
                 bold: Style::new(),
+                italic: Style::new(),
                 dimmed: Style::new(),
                 magenta: Style::new(),
                 red: Style::new(),
                 green: Style::new(),
+                cyan: Style::new(),
                 call_id_to_tool_call,
+                show_agent_reasoning,
             }
         }
     }
@@ -94,59 +104,73 @@ struct PatchApplyBegin {
     auto_approved: bool,
 }
 
+// Timestamped println helper. The timestamp is styled with self.dimmed.
+#[macro_export]
 macro_rules! ts_println {
-    ($($arg:tt)*) => {{
-        let now = Utc::now();
-        let formatted = now.format("%Y-%m-%dT%H:%M:%S").to_string();
-        print!("[{}] ", formatted);
+    ($self:ident, $($arg:tt)*) => {{
+        let now = chrono::Utc::now();
+        let formatted = now.format("[%Y-%m-%dT%H:%M:%S]");
+        print!("{} ", formatted.style($self.dimmed));
         println!($($arg)*);
     }};
 }
 
-/// Print a concise summary of the effective configuration that will be used
-/// for the session. This mirrors the information shown in the TUI welcome
-/// screen.
-pub(crate) fn print_config_summary(config: &Config, with_ansi: bool) {
-    let bold = if with_ansi {
-        Style::new().bold()
-    } else {
-        Style::new()
-    };
+impl EventProcessor {
+    /// Print a concise summary of the effective configuration that will be used
+    /// for the session. This mirrors the information shown in the TUI welcome
+    /// screen.
+    pub(crate) fn print_config_summary(&mut self, config: &Config, prompt: &str) {
+        const VERSION: &str = env!("CARGO_PKG_VERSION");
+        ts_println!(
+            self,
+            "OpenAI Codex v{} (research preview)\n--------",
+            VERSION
+        );
 
-    ts_println!("OpenAI Codex (research preview)\n--------");
+        let entries = vec![
+            ("workdir", config.cwd.display().to_string()),
+            ("model", config.model.clone()),
+            ("provider", config.model_provider_id.clone()),
+            ("approval", format!("{:?}", config.approval_policy)),
+            ("sandbox", format!("{:?}", config.sandbox_policy)),
+        ];
 
-    let entries = vec![
-        ("workdir", config.cwd.display().to_string()),
-        ("model", config.model.clone()),
-        ("provider", config.model_provider_id.clone()),
-        ("approval", format!("{:?}", config.approval_policy)),
-        ("sandbox", format!("{:?}", config.sandbox_policy)),
-    ];
+        for (key, value) in entries {
+            println!("{} {}", format!("{key}: ").style(self.bold), value);
+        }
 
-    for (key, value) in entries {
-        println!("{} {}", format!("{key}: ").style(bold), value);
+        println!("--------");
+
+        // Echo the prompt that will be sent to the agent so it is visible in the
+        // transcript/logs before any events come in. Note the prompt may have been
+        // read from stdin, so it may not be visible in the terminal otherwise.
+        ts_println!(
+            self,
+            "{}\n{}",
+            "User instructions:".style(self.bold).style(self.cyan),
+            prompt
+        );
     }
 
-    println!("--------\n");
-}
-
-impl EventProcessor {
     pub(crate) fn process_event(&mut self, event: Event) {
         let Event { id: _, msg } = event;
         match msg {
             EventMsg::Error(ErrorEvent { message }) => {
                 let prefix = "ERROR:".style(self.red);
-                ts_println!("{prefix} {message}");
+                ts_println!(self, "{prefix} {message}");
             }
             EventMsg::BackgroundEvent(BackgroundEventEvent { message }) => {
-                ts_println!("{}", message.style(self.dimmed));
+                ts_println!(self, "{}", message.style(self.dimmed));
             }
             EventMsg::TaskStarted | EventMsg::TaskComplete(_) => {
                 // Ignore.
             }
             EventMsg::AgentMessage(AgentMessageEvent { message }) => {
-                let prefix = "Agent message:".style(self.bold);
-                ts_println!("{prefix} {message}");
+                ts_println!(
+                    self,
+                    "{}\n{message}",
+                    "codex".style(self.bold).style(self.magenta)
+                );
             }
             EventMsg::ExecCommandBegin(ExecCommandBeginEvent {
                 call_id,
@@ -161,6 +185,7 @@ impl EventProcessor {
                     },
                 );
                 ts_println!(
+                    self,
                     "{} {} in {}",
                     "exec".style(self.magenta),
                     escape_command(&command).style(self.bold),
@@ -196,11 +221,11 @@ impl EventProcessor {
                 match exit_code {
                     0 => {
                         let title = format!("{call} succeeded{duration}:");
-                        ts_println!("{}", title.style(self.green));
+                        ts_println!(self, "{}", title.style(self.green));
                     }
                     _ => {
                         let title = format!("{call} exited {exit_code}{duration}:");
-                        ts_println!("{}", title.style(self.red));
+                        ts_println!(self, "{}", title.style(self.red));
                     }
                 }
                 println!("{}", truncated_output.style(self.dimmed));
@@ -237,16 +262,15 @@ impl EventProcessor {
                 );
 
                 ts_println!(
+                    self,
                     "{} {}",
                     "tool".style(self.magenta),
                     invocation.style(self.bold),
                 );
             }
-            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
-                call_id,
-                success,
-                result,
-            }) => {
+            EventMsg::McpToolCallEnd(tool_call_end_event) => {
+                let is_success = tool_call_end_event.is_success();
+                let McpToolCallEndEvent { call_id, result } = tool_call_end_event;
                 // Retrieve start time and invocation for duration calculation and labeling.
                 let info = self.call_id_to_tool_call.remove(&call_id);
 
@@ -261,13 +285,13 @@ impl EventProcessor {
                     (String::new(), format!("tool('{call_id}')"))
                 };
 
-                let status_str = if success { "success" } else { "failed" };
-                let title_style = if success { self.green } else { self.red };
+                let status_str = if is_success { "success" } else { "failed" };
+                let title_style = if is_success { self.green } else { self.red };
                 let title = format!("{invocation} {status_str}{duration}:");
 
-                ts_println!("{}", title.style(title_style));
+                ts_println!(self, "{}", title.style(title_style));
 
-                if let Some(res) = result {
+                if let Ok(res) = result {
                     let val: serde_json::Value = res.into();
                     let pretty =
                         serde_json::to_string_pretty(&val).unwrap_or_else(|_| val.to_string());
@@ -293,6 +317,7 @@ impl EventProcessor {
                 );
 
                 ts_println!(
+                    self,
                     "{} auto_approved={}:",
                     "apply_patch".style(self.magenta),
                     auto_approved,
@@ -384,7 +409,7 @@ impl EventProcessor {
                 };
 
                 let title = format!("{label} exited {exit_code}{duration}:");
-                ts_println!("{}", title.style(title_style));
+                ts_println!(self, "{}", title.style(title_style));
                 for line in output.lines() {
                     println!("{}", line.style(self.dimmed));
                 }
@@ -396,7 +421,14 @@ impl EventProcessor {
                 // Should we exit?
             }
             EventMsg::AgentReasoning(agent_reasoning_event) => {
-                println!("thinking: {}", agent_reasoning_event.text);
+                if self.show_agent_reasoning {
+                    ts_println!(
+                        self,
+                        "{}\n{}",
+                        "thinking".style(self.italic).style(self.magenta),
+                        agent_reasoning_event.text
+                    );
+                }
             }
             EventMsg::SessionConfigured(session_configured_event) => {
                 let SessionConfiguredEvent {
@@ -407,12 +439,13 @@ impl EventProcessor {
                 } = session_configured_event;
 
                 ts_println!(
+                    self,
                     "{} {}",
                     "codex session".style(self.magenta).style(self.bold),
                     session_id.to_string().style(self.dimmed)
                 );
 
-                ts_println!("model: {}", model);
+                ts_println!(self, "model: {}", model);
                 println!();
             }
             EventMsg::GetHistoryEntryResponse(_) => {

codex-rs/exec/src/lib.rs

@@ -2,6 +2,7 @@ mod cli;
 mod event_processor;
 
 use std::io::IsTerminal;
+use std::io::Read;
 use std::path::Path;
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -19,7 +20,6 @@ use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::util::is_inside_git_repo;
 use event_processor::EventProcessor;
-use event_processor::print_config_summary;
 use tracing::debug;
 use tracing::error;
 use tracing::info;
@@ -34,12 +34,47 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         sandbox,
         cwd,
         skip_git_repo_check,
-        disable_response_storage,
         color,
         last_message_file,
         prompt,
+        config_overrides,
     } = cli;
 
+    // Determine the prompt based on CLI arg and/or stdin.
+    let prompt = match prompt {
+        Some(p) if p != "-" => p,
+        // Either `-` was passed or no positional arg.
+        maybe_dash => {
+            // When no arg (None) **and** stdin is a TTY, bail out early – unless the
+            // user explicitly forced reading via `-`.
+            let force_stdin = matches!(maybe_dash.as_deref(), Some("-"));
+
+            if std::io::stdin().is_terminal() && !force_stdin {
+                eprintln!(
+                    "No prompt provided. Either specify one as an argument or pipe the prompt into stdin."
+                );
+                std::process::exit(1);
+            }
+
+            // Ensure the user knows we are waiting on stdin, as they may
+            // have gotten into this state by mistake. If so, and they are not
+            // writing to stdin, Codex will hang indefinitely, so this should
+            // help them debug in that case.
+            if !force_stdin {
+                eprintln!("Reading prompt from stdin...");
+            }
+            let mut buffer = String::new();
+            if let Err(e) = std::io::stdin().read_to_string(&mut buffer) {
+                eprintln!("Failed to read prompt from stdin: {e}");
+                std::process::exit(1);
+            } else if buffer.trim().is_empty() {
+                eprintln!("No prompt provided via stdin.");
+                std::process::exit(1);
+            }
+            buffer
+        }
+    };
+
     let (stdout_with_ansi, stderr_with_ansi) = match color {
         cli::Color::Always => (true, true),
         cli::Color::Never => (false, false),
@@ -63,18 +98,25 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         // the user for approval.
         approval_policy: Some(AskForApproval::Never),
         sandbox_policy,
-        disable_response_storage: if disable_response_storage {
-            Some(true)
-        } else {
-            None
-        },
         cwd: cwd.map(|p| p.canonicalize().unwrap_or(p)),
         model_provider: None,
         codex_linux_sandbox_exe,
     };
-    let config = Config::load_with_overrides(overrides)?;
-    // Print the effective configuration so users can see what Codex is using.
-    print_config_summary(&config, stdout_with_ansi);
+    // Parse `-c` overrides.
+    let cli_kv_overrides = match config_overrides.parse_overrides() {
+        Ok(v) => v,
+        Err(e) => {
+            eprintln!("Error parsing -c overrides: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    let config = Config::load_with_cli_overrides(cli_kv_overrides, overrides)?;
+    let mut event_processor =
+        EventProcessor::create_with_ansi(stdout_with_ansi, !config.hide_agent_reasoning);
+    // Print the effective configuration and prompt so users can see what Codex
+    // is using.
+    event_processor.print_config_summary(&config, &prompt);
 
     if !skip_git_repo_check && !is_inside_git_repo(&config) {
         eprintln!("Not inside a Git repo and --skip-git-repo-check was not specified.");
@@ -164,7 +206,6 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
     info!("Sent prompt with event ID: {initial_prompt_task_id}");
 
     // Run the loop until the task is complete.
-    let mut event_processor = EventProcessor::create_with_ansi(stdout_with_ansi);
     while let Some(event) = rx.recv().await {
         let (is_last_event, last_assistant_message) = match &event.msg {
             EventMsg::TaskComplete(TaskCompleteEvent { last_agent_message }) => {

codex-rs/exec/src/main.rs

@@ -10,13 +10,30 @@
 //! This allows us to ship a completely separate set of functionality as part
 //! of the `codex-exec` binary.
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_exec::Cli;
 use codex_exec::run_main;
 
+#[derive(Parser, Debug)]
+struct TopCli {
+    #[clap(flatten)]
+    config_overrides: CliConfigOverrides,
+
+    #[clap(flatten)]
+    inner: Cli,
+}
+
 fn main() -> anyhow::Result<()> {
     codex_linux_sandbox::run_with_sandbox(|codex_linux_sandbox_exe| async move {
-        let cli = Cli::parse();
-        run_main(cli, codex_linux_sandbox_exe).await?;
+        let top_cli = TopCli::parse();
+        // Merge root-level overrides into inner CLI struct so downstream logic remains unchanged.
+        let mut inner = top_cli.inner;
+        inner
+            .config_overrides
+            .raw_overrides
+            .splice(0..0, top_cli.config_overrides.raw_overrides);
+
+        run_main(inner, codex_linux_sandbox_exe).await?;
         Ok(())
     })
 }

codex-rs/justfile

@@ -1,15 +1,21 @@
+set positional-arguments
+
 # Display help
 help:
     just -l
 
-# Install the `codex-tui` binary
-install:
-    cargo install --path tui
+# `codex`
+codex *args:
+    cargo run --bin codex -- "$@"
 
-# Run the TUI app
+# `codex exec`
+exec *args:
+    cargo run --bin codex -- exec "$@"
+
+# `codex tui`
 tui *args:
-    cargo run --bin codex -- tui {{args}}
+    cargo run --bin codex -- tui "$@"
 
-# Run the Proto app
-proto *args:
-    cargo run --bin codex -- proto {{args}}
+# format code
+fmt:
+    cargo fmt -- --config imports_granularity=Item

codex-rs/mcp-client/src/main.rs

@@ -20,9 +20,22 @@ use mcp_types::Implementation;
 use mcp_types::InitializeRequestParams;
 use mcp_types::ListToolsRequestParams;
 use mcp_types::MCP_SCHEMA_VERSION;
+use tracing_subscriber::EnvFilter;
 
 #[tokio::main]
 async fn main() -> Result<()> {
+    let default_level = "debug";
+    let _ = tracing_subscriber::fmt()
+        // Fallback to the `default_level` log filter if the environment
+        // variable is not set _or_ contains an invalid value
+        .with_env_filter(
+            EnvFilter::try_from_default_env()
+                .or_else(|_| EnvFilter::try_new(default_level))
+                .unwrap_or_else(|_| EnvFilter::new(default_level)),
+        )
+        .with_writer(std::io::stderr)
+        .try_init();
+
     // Collect command-line arguments excluding the program name itself.
     let mut args: Vec<String> = std::env::args().skip(1).collect();
 

codex-rs/mcp-server/Cargo.toml

@@ -22,6 +22,7 @@ mcp-types = { path = "../mcp-types" }
 schemars = "0.8.22"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+toml = "0.8"
 tracing = { version = "0.1.41", features = ["log"] }
 tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }
 tokio = { version = "1", features = [

codex-rs/mcp-server/src/codex_tool_config.rs

@@ -1,15 +1,16 @@
 //! Configuration object accepted by the `codex` MCP tool-call.
 
-use std::path::PathBuf;
-
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::SandboxPolicy;
 use mcp_types::Tool;
 use mcp_types::ToolInputSchema;
 use schemars::JsonSchema;
 use schemars::r#gen::SchemaSettings;
 use serde::Deserialize;
+use std::collections::HashMap;
+use std::path::PathBuf;
 
-use codex_core::protocol::AskForApproval;
-use codex_core::protocol::SandboxPolicy;
+use crate::json_to_toml::json_to_toml;
 
 /// Client-supplied configuration for a `codex` tool-call.
 #[derive(Debug, Clone, Deserialize, JsonSchema)]
@@ -41,12 +42,10 @@ pub(crate) struct CodexToolCallParam {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub sandbox_permissions: Option<Vec<CodexToolCallSandboxPermission>>,
 
-    /// Disable server-side response storage.
+    /// Individual config settings that will override what is in
+    /// CODEX_HOME/config.toml.
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub disable_response_storage: Option<bool>,
-    // Custom system instructions.
-    // #[serde(default, skip_serializing_if = "Option::is_none")]
-    // pub instructions: Option<String>,
+    pub config: Option<HashMap<String, serde_json::Value>>,
 }
 
 // Create custom enums for use with `CodexToolCallApprovalPolicy` where we
@@ -155,7 +154,7 @@ impl CodexToolCallParam {
             cwd,
             approval_policy,
             sandbox_permissions,
-            disable_response_storage,
+            config: cli_overrides,
         } = self;
         let sandbox_policy = sandbox_permissions.map(|perms| {
             SandboxPolicy::from(perms.into_iter().map(Into::into).collect::<Vec<_>>())
@@ -168,12 +167,17 @@ impl CodexToolCallParam {
             cwd: cwd.map(PathBuf::from),
             approval_policy: approval_policy.map(Into::into),
             sandbox_policy,
-            disable_response_storage,
             model_provider: None,
             codex_linux_sandbox_exe,
         };
 
-        let cfg = codex_core::config::Config::load_with_overrides(overrides)?;
+        let cli_overrides = cli_overrides
+            .unwrap_or_default()
+            .into_iter()
+            .map(|(k, v)| (k, json_to_toml(v)))
+            .collect();
+
+        let cfg = codex_core::config::Config::load_with_cli_overrides(cli_overrides, overrides)?;
 
         Ok((prompt, cfg))
     }
@@ -216,14 +220,15 @@ mod tests {
                 ],
                 "type": "string"
               },
+              "config": {
+                "description": "Individual config settings that will override what is in CODEX_HOME/config.toml.",
+                "additionalProperties": true,
+                "type": "object"
+              },
               "cwd": {
                 "description": "Working directory for the session. If relative, it is resolved against the server process's current working directory.",
                 "type": "string"
               },
-              "disable-response-storage": {
-                "description": "Disable server-side response storage.",
-                "type": "boolean"
-              },
               "model": {
                 "description": "Optional override for the model name (e.g. \"o3\", \"o4-mini\")",
                 "type": "string"

codex-rs/mcp-server/src/json_to_toml.rs

@@ -0,0 +1,84 @@
+use serde_json::Value as JsonValue;
+use toml::Value as TomlValue;
+
+/// Convert a `serde_json::Value` into a semantically equivalent `toml::Value`.
+pub(crate) fn json_to_toml(v: JsonValue) -> TomlValue {
+    match v {
+        JsonValue::Null => TomlValue::String(String::new()),
+        JsonValue::Bool(b) => TomlValue::Boolean(b),
+        JsonValue::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                TomlValue::Integer(i)
+            } else if let Some(f) = n.as_f64() {
+                TomlValue::Float(f)
+            } else {
+                TomlValue::String(n.to_string())
+            }
+        }
+        JsonValue::String(s) => TomlValue::String(s),
+        JsonValue::Array(arr) => TomlValue::Array(arr.into_iter().map(json_to_toml).collect()),
+        JsonValue::Object(map) => {
+            let tbl = map
+                .into_iter()
+                .map(|(k, v)| (k, json_to_toml(v)))
+                .collect::<toml::value::Table>();
+            TomlValue::Table(tbl)
+        }
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    #[test]
+    fn json_number_to_toml() {
+        let json_value = json!(123);
+        assert_eq!(TomlValue::Integer(123), json_to_toml(json_value));
+    }
+
+    #[test]
+    fn json_array_to_toml() {
+        let json_value = json!([true, 1]);
+        assert_eq!(
+            TomlValue::Array(vec![TomlValue::Boolean(true), TomlValue::Integer(1)]),
+            json_to_toml(json_value)
+        );
+    }
+
+    #[test]
+    fn json_bool_to_toml() {
+        let json_value = json!(false);
+        assert_eq!(TomlValue::Boolean(false), json_to_toml(json_value));
+    }
+
+    #[test]
+    fn json_float_to_toml() {
+        let json_value = json!(1.25);
+        assert_eq!(TomlValue::Float(1.25), json_to_toml(json_value));
+    }
+
+    #[test]
+    fn json_null_to_toml() {
+        let json_value = serde_json::Value::Null;
+        assert_eq!(TomlValue::String(String::new()), json_to_toml(json_value));
+    }
+
+    #[test]
+    fn json_object_nested() {
+        let json_value = json!({ "outer": { "inner": 2 } });
+        let expected = {
+            let mut inner = toml::value::Table::new();
+            inner.insert("inner".into(), TomlValue::Integer(2));
+
+            let mut outer = toml::value::Table::new();
+            outer.insert("outer".into(), TomlValue::Table(inner));
+            TomlValue::Table(outer)
+        };
+
+        assert_eq!(json_to_toml(json_value), expected);
+    }
+}

codex-rs/mcp-server/src/lib.rs

@@ -16,6 +16,7 @@ use tracing::info;
 
 mod codex_tool_config;
 mod codex_tool_runner;
+mod json_to_toml;
 mod message_processor;
 
 use crate::message_processor::MessageProcessor;

codex-rs/tui/Cargo.toml

@@ -16,6 +16,7 @@ workspace = true
 
 [dependencies]
 anyhow = "1"
+base64 = "0.22.1"
 clap = { version = "4", features = ["derive"] }
 codex-ansi-escape = { path = "../ansi-escape" }
 codex-core = { path = "../core" }
@@ -23,6 +24,7 @@ codex-common = { path = "../common", features = ["cli", "elapsed"] }
 codex-linux-sandbox = { path = "../linux-sandbox" }
 color-eyre = "0.6.3"
 crossterm = { version = "0.28.1", features = ["bracketed-paste"] }
+image = { version = "^0.25.6", default-features = false, features = ["jpeg"] }
 lazy_static = "1"
 mcp-types = { path = "../mcp-types" }
 path-clean = "1.0.1"
@@ -30,6 +32,7 @@ ratatui = { version = "0.29.0", features = [
     "unstable-widget-ref",
     "unstable-rendered-line-info",
 ] }
+ratatui-image = "8.0.0"
 regex = "1"
 serde_json = "1"
 shlex = "1.3.0"

codex-rs/tui/src/app.rs

@@ -7,6 +7,7 @@ use crate::mouse_capture::MouseCapture;
 use crate::scroll_event_helper::ScrollEventHelper;
 use crate::slash_command::SlashCommand;
 use crate::tui;
+// used by ChatWidgetArgs
 use codex_core::config::Config;
 use codex_core::protocol::Event;
 use codex_core::protocol::Op;
@@ -15,25 +16,43 @@ use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::MouseEvent;
 use crossterm::event::MouseEventKind;
+use std::path::PathBuf;
 use std::sync::mpsc::Receiver;
 use std::sync::mpsc::channel;
 
-/// Top‑level application state – which full‑screen view is currently active.
-enum AppState {
+/// Top-level application state: which full-screen view is currently active.
+#[allow(clippy::large_enum_variant)]
+enum AppState<'a> {
     /// The main chat UI is visible.
-    Chat,
-    /// The start‑up warning that recommends running codex inside a Git repo.
+    Chat {
+        /// Boxed to avoid a large enum variant and reduce the overall size of
+        /// `AppState`.
+        widget: Box<ChatWidget<'a>>,
+    },
+    /// The start-up warning that recommends running codex inside a Git repo.
     GitWarning { screen: GitWarningScreen },
 }
 
 pub(crate) struct App<'a> {
     app_event_tx: AppEventSender,
     app_event_rx: Receiver<AppEvent>,
-    chat_widget: ChatWidget<'a>,
-    app_state: AppState,
+    app_state: AppState<'a>,
+
+    /// Stored parameters needed to instantiate the ChatWidget later, e.g.,
+    /// after dismissing the Git-repo warning.
+    chat_args: Option<ChatWidgetArgs>,
 }
 
-impl App<'_> {
+/// Aggregate parameters needed to create a `ChatWidget`, as creation may be
+/// deferred until after the Git warning screen is dismissed.
+#[derive(Clone)]
+struct ChatWidgetArgs {
+    config: Config,
+    initial_prompt: Option<String>,
+    initial_images: Vec<PathBuf>,
+}
+
+impl<'a> App<'a> {
     pub(crate) fn new(
         config: Config,
         initial_prompt: Option<String>,
@@ -94,26 +113,33 @@ impl App<'_> {
             });
         }
 
-        let chat_widget = ChatWidget::new(
-            config,
-            app_event_tx.clone(),
-            initial_prompt.clone(),
-            initial_images,
-        );
-
-        let app_state = if show_git_warning {
-            AppState::GitWarning {
-                screen: GitWarningScreen::new(),
-            }
+        let (app_state, chat_args) = if show_git_warning {
+            (
+                AppState::GitWarning {
+                    screen: GitWarningScreen::new(),
+                },
+                Some(ChatWidgetArgs {
+                    config,
+                    initial_prompt,
+                    initial_images,
+                }),
+            )
         } else {
-            AppState::Chat
+            let chat_widget =
+                ChatWidget::new(config, app_event_tx.clone(), initial_prompt, initial_images);
+            (
+                AppState::Chat {
+                    widget: Box::new(chat_widget),
+                },
+                None,
+            )
         };
 
         Self {
             app_event_tx,
             app_event_rx,
-            chat_widget,
             app_state,
+            chat_args,
         }
     }
 
@@ -144,7 +170,15 @@ impl App<'_> {
                             modifiers: crossterm::event::KeyModifiers::CONTROL,
                             ..
                         } => {
-                            self.chat_widget.submit_op(Op::Interrupt);
+                            // Forward interrupt to ChatWidget when active.
+                            match &mut self.app_state {
+                                AppState::Chat { widget } => {
+                                    widget.submit_op(Op::Interrupt);
+                                }
+                                AppState::GitWarning { .. } => {
+                                    // No-op.
+                                }
+                            }
                         }
                         KeyEvent {
                             code: KeyCode::Char('d'),
@@ -167,20 +201,19 @@ impl App<'_> {
                 AppEvent::ExitRequest => {
                     break;
                 }
-                AppEvent::CodexOp(op) => {
-                    if matches!(self.app_state, AppState::Chat) {
-                        self.chat_widget.submit_op(op);
-                    }
-                }
-                AppEvent::LatestLog(line) => {
-                    if matches!(self.app_state, AppState::Chat) {
-                        self.chat_widget.update_latest_log(line);
-                    }
-                }
+                AppEvent::CodexOp(op) => match &mut self.app_state {
+                    AppState::Chat { widget } => widget.submit_op(op),
+                    AppState::GitWarning { .. } => {}
+                },
+                AppEvent::LatestLog(line) => match &mut self.app_state {
+                    AppState::Chat { widget } => widget.update_latest_log(line),
+                    AppState::GitWarning { .. } => {}
+                },
                 AppEvent::DispatchCommand(command) => match command {
-                    SlashCommand::Clear => {
-                        self.chat_widget.clear_conversation_history();
-                    }
+                    SlashCommand::Clear => match &mut self.app_state {
+                        AppState::Chat { widget } => widget.clear_conversation_history(),
+                        AppState::GitWarning { .. } => {}
+                    },
                     SlashCommand::ToggleMouseMode => {
                         if let Err(e) = mouse_capture.toggle() {
                             tracing::error!("Failed to toggle mouse mode: {e}");
@@ -199,8 +232,8 @@ impl App<'_> {
 
     fn draw_next_frame(&mut self, terminal: &mut tui::Tui) -> Result<()> {
         match &mut self.app_state {
-            AppState::Chat => {
-                terminal.draw(|frame| frame.render_widget_ref(&self.chat_widget, frame.area()))?;
+            AppState::Chat { widget } => {
+                terminal.draw(|frame| frame.render_widget_ref(&**widget, frame.area()))?;
             }
             AppState::GitWarning { screen } => {
                 terminal.draw(|frame| frame.render_widget_ref(&*screen, frame.area()))?;
@@ -213,12 +246,24 @@ impl App<'_> {
     /// with it.
     fn dispatch_key_event(&mut self, key_event: KeyEvent) {
         match &mut self.app_state {
-            AppState::Chat => {
-                self.chat_widget.handle_key_event(key_event);
+            AppState::Chat { widget } => {
+                widget.handle_key_event(key_event);
             }
             AppState::GitWarning { screen } => match screen.handle_key_event(key_event) {
                 GitWarningOutcome::Continue => {
-                    self.app_state = AppState::Chat;
+                    // User accepted – switch to chat view.
+                    let args = match self.chat_args.take() {
+                        Some(args) => args,
+                        None => panic!("ChatWidgetArgs already consumed"),
+                    };
+
+                    let widget = Box::new(ChatWidget::new(
+                        args.config,
+                        self.app_event_tx.clone(),
+                        args.initial_prompt,
+                        args.initial_images,
+                    ));
+                    self.app_state = AppState::Chat { widget };
                     self.app_event_tx.send(AppEvent::Redraw);
                 }
                 GitWarningOutcome::Quit => {
@@ -232,14 +277,16 @@ impl App<'_> {
     }
 
     fn dispatch_scroll_event(&mut self, scroll_delta: i32) {
-        if matches!(self.app_state, AppState::Chat) {
-            self.chat_widget.handle_scroll_delta(scroll_delta);
+        match &mut self.app_state {
+            AppState::Chat { widget } => widget.handle_scroll_delta(scroll_delta),
+            AppState::GitWarning { .. } => {}
         }
     }
 
     fn dispatch_codex_event(&mut self, event: Event) {
-        if matches!(self.app_state, AppState::Chat) {
-            self.chat_widget.handle_codex_event(event);
+        match &mut self.app_state {
+            AppState::Chat { widget } => widget.handle_codex_event(event),
+            AppState::GitWarning { .. } => {}
         }
     }
 }

codex-rs/tui/src/bottom_pane/command_popup.rs

@@ -4,6 +4,7 @@ use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use ratatui::style::Color;
 use ratatui::style::Style;
+use ratatui::style::Stylize;
 use ratatui::widgets::Block;
 use ratatui::widgets::BorderType;
 use ratatui::widgets::Borders;
@@ -147,8 +148,6 @@ impl CommandPopup {
 
 impl WidgetRef for CommandPopup {
     fn render_ref(&self, area: Rect, buf: &mut Buffer) {
-        let style = Style::default().bg(Color::Blue).fg(Color::White);
-
         let matches = self.filtered_commands();
 
         let mut rows: Vec<Row> = Vec::new();
@@ -157,21 +156,25 @@ impl WidgetRef for CommandPopup {
 
         if visible_matches.is_empty() {
             rows.push(Row::new(vec![
-                Cell::from("").style(style),
-                Cell::from("No matching commands").style(style.add_modifier(Modifier::ITALIC)),
+                Cell::from(""),
+                Cell::from("No matching commands").add_modifier(Modifier::ITALIC),
             ]));
         } else {
+            let default_style = Style::default();
+            let command_style = Style::default().fg(Color::LightBlue);
             for (idx, cmd) in visible_matches.iter().enumerate() {
-                let highlight = Style::default().bg(Color::White).fg(Color::Blue);
-                let cmd_style = if Some(idx) == self.selected_idx {
-                    highlight
+                let (cmd_style, desc_style) = if Some(idx) == self.selected_idx {
+                    (
+                        command_style.bg(Color::DarkGray),
+                        default_style.bg(Color::DarkGray),
+                    )
                 } else {
-                    style
+                    (command_style, default_style)
                 };
 
                 rows.push(Row::new(vec![
-                    Cell::from(cmd.command().to_string()).style(cmd_style),
-                    Cell::from(cmd.description().to_string()).style(style),
+                    Cell::from(format!("/{}", cmd.command())).style(cmd_style),
+                    Cell::from(cmd.description().to_string()).style(desc_style),
                 ]));
             }
         }
@@ -182,13 +185,11 @@ impl WidgetRef for CommandPopup {
             rows,
             [Constraint::Length(FIRST_COLUMN_WIDTH), Constraint::Min(10)],
         )
-        .style(style)
-        .column_spacing(1)
+        .column_spacing(0)
         .block(
             Block::default()
                 .borders(Borders::ALL)
-                .border_type(BorderType::Rounded)
-                .style(style),
+                .border_type(BorderType::Rounded),
         );
 
         table.render(area, buf);

codex-rs/tui/src/cell_widget.rs

@@ -0,0 +1,20 @@
+use ratatui::prelude::*;
+
+/// Trait implemented by every type that can live inside the conversation
+/// history list.  It provides two primitives that the parent scroll-view
+/// needs: how *tall* the widget is at a given width and how to render an
+/// arbitrary contiguous *window* of that widget.
+///
+/// The `first_visible_line` argument to [`render_window`] allows partial
+/// rendering when the top of the widget is scrolled off-screen.  The caller
+/// guarantees that `first_visible_line + area.height as usize` never exceeds
+/// the total height previously returned by [`height`].
+pub(crate) trait CellWidget {
+    /// Total height measured in wrapped terminal lines when drawn with the
+    /// given *content* width (no scrollbar column included).
+    fn height(&self, width: u16) -> usize;
+
+    /// Render a *window* that starts `first_visible_line` lines below the top
+    /// of the widget. The window’s size is given by `area`.
+    fn render_window(&self, first_visible_line: usize, area: Rect, buf: &mut Buffer);
+}

codex-rs/tui/src/chatwidget.rs

@@ -239,9 +239,11 @@ impl ChatWidget<'_> {
                 self.request_redraw();
             }
             EventMsg::AgentReasoning(AgentReasoningEvent { text }) => {
-                self.conversation_history
-                    .add_agent_reasoning(&self.config, text);
-                self.request_redraw();
+                if !self.config.hide_agent_reasoning {
+                    self.conversation_history
+                        .add_agent_reasoning(&self.config, text);
+                    self.request_redraw();
+                }
             }
             EventMsg::TaskStarted => {
                 self.bottom_pane.set_task_running(true);
@@ -343,11 +345,9 @@ impl ChatWidget<'_> {
                     .add_active_mcp_tool_call(call_id, server, tool, arguments);
                 self.request_redraw();
             }
-            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
-                call_id,
-                success,
-                result,
-            }) => {
+            EventMsg::McpToolCallEnd(mcp_tool_call_end_event) => {
+                let success = mcp_tool_call_end_event.is_success();
+                let McpToolCallEndEvent { call_id, result } = mcp_tool_call_end_event;
                 self.conversation_history
                     .record_completed_mcp_tool_call(call_id, success, result);
                 self.request_redraw();

codex-rs/tui/src/cli.rs

@@ -1,5 +1,6 @@
 use clap::Parser;
 use codex_common::ApprovalModeCliArg;
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 use std::path::PathBuf;
 
@@ -40,7 +41,6 @@ pub struct Cli {
     #[arg(long = "skip-git-repo-check", default_value_t = false)]
     pub skip_git_repo_check: bool,
 
-    /// Disable server‑side response storage (sends the full conversation context with every request)
-    #[arg(long = "disable-response-storage", default_value_t = false)]
-    pub disable_response_storage: bool,
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
 }

codex-rs/tui/src/conversation_history_widget.rs

@@ -1,3 +1,4 @@
+use crate::cell_widget::CellWidget;
 use crate::history_cell::CommandOutput;
 use crate::history_cell::HistoryCell;
 use crate::history_cell::PatchEventType;
@@ -236,11 +237,7 @@ impl ConversationHistoryWidget {
 
     fn add_to_history(&mut self, cell: HistoryCell) {
         let width = self.cached_width.get();
-        let count = if width > 0 {
-            wrapped_line_count_for_cell(&cell, width)
-        } else {
-            0
-        };
+        let count = if width > 0 { cell.height(width) } else { 0 };
 
         self.entries.push(Entry {
             cell,
@@ -284,9 +281,7 @@ impl ConversationHistoryWidget {
 
                     // Update cached line count.
                     if width > 0 {
-                        entry
-                            .line_count
-                            .set(wrapped_line_count_for_cell(cell, width));
+                        entry.line_count.set(cell.height(width));
                     }
                     break;
                 }
@@ -298,15 +293,8 @@ impl ConversationHistoryWidget {
         &mut self,
         call_id: String,
         success: bool,
-        result: Option<mcp_types::CallToolResult>,
+        result: Result<mcp_types::CallToolResult, String>,
     ) {
-        // Convert result into serde_json::Value early so we don't have to
-        // worry about lifetimes inside the match arm.
-        let result_val = result.map(|r| {
-            serde_json::to_value(r)
-                .unwrap_or_else(|_| serde_json::Value::String("<serialization error>".into()))
-        });
-
         let width = self.cached_width.get();
         for entry in self.entries.iter_mut() {
             if let HistoryCell::ActiveMcpToolCall {
@@ -323,14 +311,12 @@ impl ConversationHistoryWidget {
                         invocation.clone(),
                         *start,
                         success,
-                        result_val,
+                        result,
                     );
                     entry.cell = completed;
 
                     if width > 0 {
-                        entry
-                            .line_count
-                            .set(wrapped_line_count_for_cell(&entry.cell, width));
+                        entry.line_count.set(entry.cell.height(width));
                     }
 
                     break;
@@ -378,7 +364,7 @@ impl WidgetRef for ConversationHistoryWidget {
 
             let mut num_lines: usize = 0;
             for entry in &self.entries {
-                let count = wrapped_line_count_for_cell(&entry.cell, effective_width);
+                let count = entry.cell.height(effective_width);
                 num_lines += count;
                 entry.line_count.set(count);
             }
@@ -397,79 +383,69 @@ impl WidgetRef for ConversationHistoryWidget {
             self.scroll_position.min(max_scroll)
         };
 
-        // ------------------------------------------------------------------
-        // Build a *window* into the history so we only clone the `Line`s that
-        // may actually be visible in this frame. We still hand the slice off
-        // to a `Paragraph` with an additional scroll offset to avoid slicing
-        // inside a wrapped line (we don’t have per-subline granularity).
-        // ------------------------------------------------------------------
-
-        // Find the first entry that intersects the current scroll position.
-        let mut cumulative = 0usize;
-        let mut first_idx = 0usize;
-        for (idx, entry) in self.entries.iter().enumerate() {
-            let next = cumulative + entry.line_count.get();
-            if next > scroll_pos {
-                first_idx = idx;
-                break;
-            }
-            cumulative = next;
-        }
-
-        let offset_into_first = scroll_pos - cumulative;
-
-        // Collect enough raw lines from `first_idx` onward to cover the
-        // viewport. We may fetch *slightly* more than necessary (whole cells)
-        // but never the entire history.
-        let mut collected_wrapped = 0usize;
-        let mut visible_lines: Vec<Line<'static>> = Vec::new();
-
-        for entry in &self.entries[first_idx..] {
-            visible_lines.extend(entry.cell.lines().iter().cloned());
-            collected_wrapped += entry.line_count.get();
-            if collected_wrapped >= offset_into_first + viewport_height {
-                break;
-            }
-        }
-
-        // Build the Paragraph with wrapping enabled so long lines are not
-        // clipped. Apply vertical scroll so that `offset_into_first` wrapped
-        // lines are hidden at the top.
         // ------------------------------------------------------------------
         // Render order:
-        //   1. Clear the whole widget area so we do not leave behind any glyphs
-        //      from the previous frame.
+        //   1. Clear full widget area (avoid artifacts from prior frame).
         //   2. Draw the surrounding Block (border and title).
-        //   3. Draw the Paragraph inside the Block, **leaving the right-most
-        //      column free** for the scrollbar.
-        //   4. Finally draw the scrollbar (if needed).
+        //   3. Render *each* visible HistoryCell into its own sub-Rect while
+        //      respecting partial visibility at the top and bottom.
+        //   4. Draw the scrollbar track / thumb in the reserved column.
         // ------------------------------------------------------------------
 
-        // Clear the widget area to avoid visual artifacts from previous frames.
+        // Clear entire widget area first.
         Clear.render(area, buf);
 
-        // Draw the outer border and title first so the Paragraph does not
-        // overwrite it.
+        // Draw border + title.
         block.render(area, buf);
 
-        // Area available for text after accounting for the scrollbar.
-        let text_area = Rect {
-            x: inner.x,
-            y: inner.y,
-            width: effective_width,
-            height: inner.height,
-        };
+        // ------------------------------------------------------------------
+        // Calculate which cells are visible for the current scroll position
+        // and paint them one by one.
+        // ------------------------------------------------------------------
 
-        let paragraph = Paragraph::new(visible_lines)
-            .wrap(wrap_cfg())
-            .scroll((offset_into_first as u16, 0));
+        let mut y_cursor = inner.y; // first line inside viewport
+        let mut remaining_height = inner.height as usize;
+        let mut lines_to_skip = scroll_pos; // number of wrapped lines to skip (above viewport)
 
-        paragraph.render(text_area, buf);
+        for entry in &self.entries {
+            let cell_height = entry.line_count.get();
 
-        // Always render a scrollbar *track* so that the reserved column is
-        // visually filled, even when the content fits within the viewport.
-        // We only draw the *thumb* when the content actually overflows.
+            // Completely above viewport? Skip whole cell.
+            if lines_to_skip >= cell_height {
+                lines_to_skip -= cell_height;
+                continue;
+            }
 
+            // Determine how much of this cell is visible.
+            let visible_height = (cell_height - lines_to_skip).min(remaining_height);
+
+            if visible_height == 0 {
+                break; // no space left
+            }
+
+            let cell_rect = Rect {
+                x: inner.x,
+                y: y_cursor,
+                width: effective_width,
+                height: visible_height as u16,
+            };
+
+            entry.cell.render_window(lines_to_skip, cell_rect, buf);
+
+            // Advance cursor inside viewport.
+            y_cursor += visible_height as u16;
+            remaining_height -= visible_height;
+
+            // After the first (possibly partially skipped) cell, we no longer
+            // need to skip lines at the top.
+            lines_to_skip = 0;
+
+            if remaining_height == 0 {
+                break; // viewport filled
+            }
+        }
+
+        // Always render a scrollbar *track* so the reserved column is filled.
         let overflow = num_lines.saturating_sub(viewport_height);
 
         let mut scroll_state = ScrollbarState::default()
@@ -521,15 +497,6 @@ impl WidgetRef for ConversationHistoryWidget {
 /// Common [`Wrap`] configuration used for both measurement and rendering so
 /// they stay in sync.
 #[inline]
-const fn wrap_cfg() -> ratatui::widgets::Wrap {
+pub(crate) const fn wrap_cfg() -> ratatui::widgets::Wrap {
     ratatui::widgets::Wrap { trim: false }
 }
-
-/// Returns the wrapped line count for `cell` at the given `width` using the
-/// same wrapping rules that `ConversationHistoryWidget` uses during
-/// rendering.
-fn wrapped_line_count_for_cell(cell: &HistoryCell, width: u16) -> usize {
-    Paragraph::new(cell.lines().clone())
-        .wrap(wrap_cfg())
-        .line_count(width)
-}

codex-rs/tui/src/history_cell.rs

@@ -1,21 +1,32 @@
+use crate::cell_widget::CellWidget;
+use crate::exec_command::escape_command;
+use crate::markdown::append_markdown;
+use crate::text_block::TextBlock;
+use base64::Engine;
 use codex_ansi_escape::ansi_escape_line;
 use codex_common::elapsed::format_duration;
 use codex_core::config::Config;
 use codex_core::protocol::FileChange;
 use codex_core::protocol::SessionConfiguredEvent;
+use image::DynamicImage;
+use image::GenericImageView;
+use image::ImageReader;
+use lazy_static::lazy_static;
 use ratatui::prelude::*;
 use ratatui::style::Color;
 use ratatui::style::Modifier;
 use ratatui::style::Style;
 use ratatui::text::Line as RtLine;
 use ratatui::text::Span as RtSpan;
+use ratatui_image::Image as TuiImage;
+use ratatui_image::Resize as ImgResize;
+use ratatui_image::picker::ProtocolType;
 use std::collections::HashMap;
+use std::io::Cursor;
 use std::path::PathBuf;
 use std::time::Duration;
 use std::time::Instant;
-
-use crate::exec_command::escape_command;
-use crate::markdown::append_markdown;
+use tracing::error;
 
 pub(crate) struct CommandOutput {
     pub(crate) exit_code: i32,
@@ -34,16 +45,16 @@ pub(crate) enum PatchEventType {
 /// scrollable list.
 pub(crate) enum HistoryCell {
     /// Welcome message.
-    WelcomeMessage { lines: Vec<Line<'static>> },
+    WelcomeMessage { view: TextBlock },
 
     /// Message from the user.
-    UserPrompt { lines: Vec<Line<'static>> },
+    UserPrompt { view: TextBlock },
 
     /// Message from the agent.
-    AgentMessage { lines: Vec<Line<'static>> },
+    AgentMessage { view: TextBlock },
 
     /// Reasoning event from the agent.
-    AgentReasoning { lines: Vec<Line<'static>> },
+    AgentReasoning { view: TextBlock },
 
     /// An exec tool call that has not finished yet.
     ActiveExecCommand {
@@ -51,11 +62,11 @@ pub(crate) enum HistoryCell {
         /// The shell command, escaped and formatted.
         command: String,
         start: Instant,
-        lines: Vec<Line<'static>>,
+        view: TextBlock,
     },
 
     /// Completed exec tool call.
-    CompletedExecCommand { lines: Vec<Line<'static>> },
+    CompletedExecCommand { view: TextBlock },
 
     /// An MCP tool call that has not finished yet.
     ActiveMcpToolCall {
@@ -67,29 +78,41 @@ pub(crate) enum HistoryCell {
         /// exact same text without re-formatting.
         invocation: String,
         start: Instant,
-        lines: Vec<Line<'static>>,
+        view: TextBlock,
     },
 
-    /// Completed MCP tool call.
-    CompletedMcpToolCall { lines: Vec<Line<'static>> },
+    /// Completed MCP tool call where we show the result serialized as JSON.
+    CompletedMcpToolCallWithTextOutput { view: TextBlock },
 
-    /// Background event
-    BackgroundEvent { lines: Vec<Line<'static>> },
+    /// Completed MCP tool call where the result is an image.
+    /// Admittedly, [mcp_types::CallToolResult] can have multiple content types,
+    /// which could be a mix of text and images, so we need to tighten this up.
+    // NOTE: For image output we keep the *original* image around and lazily
+    // compute a resized copy that fits the available cell width.  Caching the
+    // resized version avoids doing the potentially expensive rescale twice
+    // because the scroll-view first calls `height()` for layouting and then
+    // `render_window()` for painting.
+    CompletedMcpToolCallWithImageOutput {
+        image: DynamicImage,
+        /// Cached data derived from the current terminal width.  The cache is
+        /// invalidated whenever the width changes (e.g. when the user
+        /// resizes the window).
+        render_cache: std::cell::RefCell<Option<ImageRenderCache>>,
+    },
+
+    /// Background event.
+    BackgroundEvent { view: TextBlock },
 
     /// Error event from the backend.
-    ErrorEvent { lines: Vec<Line<'static>> },
+    ErrorEvent { view: TextBlock },
 
-    /// Info describing the newly‑initialized session.
-    SessionInfo { lines: Vec<Line<'static>> },
+    /// Info describing the newly-initialized session.
+    SessionInfo { view: TextBlock },
 
     /// A pending code patch that is awaiting user approval. Mirrors the
     /// behaviour of `ActiveExecCommand` so the user sees *what* patch the
     /// model wants to apply before being prompted to approve or deny it.
-    PendingPatch {
-        /// Identifier so that a future `PatchApplyEnd` can update the entry
-        /// with the final status (not yet implemented).
-        lines: Vec<Line<'static>>,
-    },
+    PendingPatch { view: TextBlock },
 }
 
 const TOOL_CALL_MAX_LINES: usize = 5;
@@ -107,10 +130,13 @@ impl HistoryCell {
             history_entry_count: _,
         } = event;
         if is_first_event {
+            const VERSION: &str = env!("CARGO_PKG_VERSION");
+
             let mut lines: Vec<Line<'static>> = vec![
                 Line::from(vec![
                     "OpenAI ".into(),
                     "Codex".bold(),
+                    format!(" v{}", VERSION).into(),
                     " (research preview)".dim(),
                 ]),
                 Line::from(""),
@@ -132,9 +158,13 @@ impl HistoryCell {
                 lines.push(Line::from(vec![format!("{key}: ").bold(), value.into()]));
             }
             lines.push(Line::from(""));
-            HistoryCell::WelcomeMessage { lines }
+            HistoryCell::WelcomeMessage {
+                view: TextBlock::new(lines),
+            }
         } else if config.model == model {
-            HistoryCell::SessionInfo { lines: vec![] }
+            HistoryCell::SessionInfo {
+                view: TextBlock::new(Vec::new()),
+            }
         } else {
             let lines = vec![
                 Line::from("model changed:".magenta().bold()),
@@ -142,7 +172,9 @@ impl HistoryCell {
                 Line::from(format!("used: {}", model)),
                 Line::from(""),
             ];
-            HistoryCell::SessionInfo { lines }
+            HistoryCell::SessionInfo {
+                view: TextBlock::new(lines),
+            }
         }
     }
 
@@ -152,7 +184,9 @@ impl HistoryCell {
         lines.extend(message.lines().map(|l| Line::from(l.to_string())));
         lines.push(Line::from(""));
 
-        HistoryCell::UserPrompt { lines }
+        HistoryCell::UserPrompt {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_agent_message(config: &Config, message: String) -> Self {
@@ -161,7 +195,9 @@ impl HistoryCell {
         append_markdown(&message, &mut lines, config);
         lines.push(Line::from(""));
 
-        HistoryCell::AgentMessage { lines }
+        HistoryCell::AgentMessage {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_agent_reasoning(config: &Config, text: String) -> Self {
@@ -170,7 +206,9 @@ impl HistoryCell {
         append_markdown(&text, &mut lines, config);
         lines.push(Line::from(""));
 
-        HistoryCell::AgentReasoning { lines }
+        HistoryCell::AgentReasoning {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_active_exec_command(call_id: String, command: Vec<String>) -> Self {
@@ -187,7 +225,7 @@ impl HistoryCell {
             call_id,
             command: command_escaped,
             start,
-            lines,
+            view: TextBlock::new(lines),
         }
     }
 
@@ -226,7 +264,9 @@ impl HistoryCell {
         }
         lines.push(Line::from(""));
 
-        HistoryCell::CompletedExecCommand { lines }
+        HistoryCell::CompletedExecCommand {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_active_mcp_tool_call(
@@ -267,7 +307,51 @@ impl HistoryCell {
             fq_tool_name,
             invocation,
             start,
-            lines,
+            view: TextBlock::new(lines),
+        }
+    }
+
+    fn try_new_completed_mcp_tool_call_with_image_output(
+        result: &Result<mcp_types::CallToolResult, String>,
+    ) -> Option<Self> {
+        match result {
+            Ok(mcp_types::CallToolResult { content, .. }) => {
+                if let Some(mcp_types::CallToolResultContent::ImageContent(image)) = content.first()
+                {
+                    let raw_data =
+                        match base64::engine::general_purpose::STANDARD.decode(&image.data) {
+                            Ok(data) => data,
+                            Err(e) => {
+                                error!("Failed to decode image data: {e}");
+                                return None;
+                            }
+                        };
+                    let reader = match ImageReader::new(Cursor::new(raw_data)).with_guessed_format()
+                    {
+                        Ok(reader) => reader,
+                        Err(e) => {
+                            error!("Failed to guess image format: {e}");
+                            return None;
+                        }
+                    };
+
+                    let image = match reader.decode() {
+                        Ok(image) => image,
+                        Err(e) => {
+                            error!("Image decoding failed: {e}");
+                            return None;
+                        }
+                    };
+
+                    Some(HistoryCell::CompletedMcpToolCallWithImageOutput {
+                        image,
+                        render_cache: std::cell::RefCell::new(None),
+                    })
+                } else {
+                    None
+                }
+            }
+            _ => None,
         }
     }
 
@@ -276,8 +360,12 @@ impl HistoryCell {
         invocation: String,
         start: Instant,
         success: bool,
-        result: Option<serde_json::Value>,
+        result: Result<mcp_types::CallToolResult, String>,
     ) -> Self {
+        if let Some(cell) = Self::try_new_completed_mcp_tool_call_with_image_output(&result) {
+            return cell;
+        }
+
         let duration = format_duration(start.elapsed());
         let status_str = if success { "success" } else { "failed" };
         let title_line = Line::from(vec![
@@ -289,7 +377,14 @@ impl HistoryCell {
         lines.push(title_line);
         lines.push(Line::from(format!("$ {invocation}")));
 
-        if let Some(res_val) = result {
+        // Convert result into serde_json::Value early so we don't have to
+        // worry about lifetimes inside the match arm.
+        let result_val = result.map(|r| {
+            serde_json::to_value(r)
+                .unwrap_or_else(|_| serde_json::Value::String("<serialization error>".into()))
+        });
+
+        if let Ok(res_val) = result_val {
             let json_pretty =
                 serde_json::to_string_pretty(&res_val).unwrap_or_else(|_| res_val.to_string());
             let mut iter = json_pretty.lines();
@@ -304,7 +399,9 @@ impl HistoryCell {
 
         lines.push(Line::from(""));
 
-        HistoryCell::CompletedMcpToolCall { lines }
+        HistoryCell::CompletedMcpToolCallWithTextOutput {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_background_event(message: String) -> Self {
@@ -312,7 +409,9 @@ impl HistoryCell {
         lines.push(Line::from("event".dim()));
         lines.extend(message.lines().map(|l| Line::from(l.to_string()).dim()));
         lines.push(Line::from(""));
-        HistoryCell::BackgroundEvent { lines }
+        HistoryCell::BackgroundEvent {
+            view: TextBlock::new(lines),
+        }
     }
 
     pub(crate) fn new_error_event(message: String) -> Self {
@@ -320,7 +419,9 @@ impl HistoryCell {
             vec!["ERROR: ".red().bold(), message.into()].into(),
             "".into(),
         ];
-        HistoryCell::ErrorEvent { lines }
+        HistoryCell::ErrorEvent {
+            view: TextBlock::new(lines),
+        }
     }
 
     /// Create a new `PendingPatch` cell that lists the file‑level summary of
@@ -339,7 +440,9 @@ impl HistoryCell {
                 auto_approved: false,
             } => {
                 let lines = vec![Line::from("patch applied".magenta().bold())];
-                return Self::PendingPatch { lines };
+                return Self::PendingPatch {
+                    view: TextBlock::new(lines),
+                };
             }
         };
 
@@ -380,23 +483,85 @@ impl HistoryCell {
 
         lines.push(Line::from(""));
 
-        HistoryCell::PendingPatch { lines }
+        HistoryCell::PendingPatch {
+            view: TextBlock::new(lines),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// `CellWidget` implementation – most variants delegate to their internal
+// `TextBlock`.  Variants that need custom painting can add their own logic in
+// the match arms.
+// ---------------------------------------------------------------------------
+
+impl CellWidget for HistoryCell {
+    fn height(&self, width: u16) -> usize {
+        match self {
+            HistoryCell::WelcomeMessage { view }
+            | HistoryCell::UserPrompt { view }
+            | HistoryCell::AgentMessage { view }
+            | HistoryCell::AgentReasoning { view }
+            | HistoryCell::BackgroundEvent { view }
+            | HistoryCell::ErrorEvent { view }
+            | HistoryCell::SessionInfo { view }
+            | HistoryCell::CompletedExecCommand { view }
+            | HistoryCell::CompletedMcpToolCallWithTextOutput { view }
+            | HistoryCell::PendingPatch { view }
+            | HistoryCell::ActiveExecCommand { view, .. }
+            | HistoryCell::ActiveMcpToolCall { view, .. } => view.height(width),
+            HistoryCell::CompletedMcpToolCallWithImageOutput {
+                image,
+                render_cache,
+            } => ensure_image_cache(image, width, render_cache),
+        }
     }
 
-    pub(crate) fn lines(&self) -> &Vec<Line<'static>> {
+    fn render_window(&self, first_visible_line: usize, area: Rect, buf: &mut Buffer) {
         match self {
-            HistoryCell::WelcomeMessage { lines, .. }
-            | HistoryCell::UserPrompt { lines, .. }
-            | HistoryCell::AgentMessage { lines, .. }
-            | HistoryCell::AgentReasoning { lines, .. }
-            | HistoryCell::BackgroundEvent { lines, .. }
-            | HistoryCell::ErrorEvent { lines, .. }
-            | HistoryCell::SessionInfo { lines, .. }
-            | HistoryCell::ActiveExecCommand { lines, .. }
-            | HistoryCell::CompletedExecCommand { lines, .. }
-            | HistoryCell::ActiveMcpToolCall { lines, .. }
-            | HistoryCell::CompletedMcpToolCall { lines, .. }
-            | HistoryCell::PendingPatch { lines, .. } => lines,
+            HistoryCell::WelcomeMessage { view }
+            | HistoryCell::UserPrompt { view }
+            | HistoryCell::AgentMessage { view }
+            | HistoryCell::AgentReasoning { view }
+            | HistoryCell::BackgroundEvent { view }
+            | HistoryCell::ErrorEvent { view }
+            | HistoryCell::SessionInfo { view }
+            | HistoryCell::CompletedExecCommand { view }
+            | HistoryCell::CompletedMcpToolCallWithTextOutput { view }
+            | HistoryCell::PendingPatch { view }
+            | HistoryCell::ActiveExecCommand { view, .. }
+            | HistoryCell::ActiveMcpToolCall { view, .. } => {
+                view.render_window(first_visible_line, area, buf)
+            }
+            HistoryCell::CompletedMcpToolCallWithImageOutput {
+                image,
+                render_cache,
+            } => {
+                // Ensure we have a cached, resized copy that matches the current width.
+                // `height()` should have prepared the cache, but if something invalidated it
+                // (e.g. the first `render_window()` call happens *before* `height()` after a
+                // resize) we rebuild it here.
+
+                let width_cells = area.width;
+
+                // Ensure the cache is up-to-date and extract the scaled image.
+                let _ = ensure_image_cache(image, width_cells, render_cache);
+
+                let Some(resized) = render_cache
+                    .borrow()
+                    .as_ref()
+                    .map(|c| c.scaled_image.clone())
+                else {
+                    return;
+                };
+
+                let picker = &*TERMINAL_PICKER;
+
+                if let Ok(protocol) = picker.new_protocol(resized, area, ImgResize::Fit(None)) {
+                    let img_widget = TuiImage::new(&protocol);
+                    img_widget.render(area, buf);
+                }
+            }
         }
     }
 }
@@ -432,3 +597,120 @@ fn create_diff_summary(changes: HashMap<PathBuf, FileChange>) -> Vec<String> {
 
     summaries
 }
+
+// -------------------------------------
+// Helper types for image rendering
+// -------------------------------------
+
+/// Cached information for rendering an image inside a conversation cell.
+///
+/// The cache ties the resized image to a *specific* content width (in
+/// terminal cells).  Whenever the terminal is resized and the width changes
+/// we need to re-compute the scaled variant so that it still fits the
+/// available space.  Keeping the resized copy around saves a costly rescale
+/// between the back-to-back `height()` and `render_window()` calls that the
+/// scroll-view performs while laying out the UI.
+pub(crate) struct ImageRenderCache {
+    /// Width in *terminal cells* the cached image was generated for.
+    width_cells: u16,
+    /// Height in *terminal rows* that the conversation cell must occupy so
+    /// the whole image becomes visible.
+    height_rows: usize,
+    /// The resized image that fits the given width / height constraints.
+    scaled_image: DynamicImage,
+}
+
+lazy_static! {
+    static ref TERMINAL_PICKER: ratatui_image::picker::Picker = {
+        use ratatui_image::picker::Picker;
+        use ratatui_image::picker::cap_parser::QueryStdioOptions;
+
+        // Ask the terminal for capabilities and explicit font size.  Request the
+        // Kitty *text-sizing protocol* as a fallback mechanism for terminals
+        // (like iTerm2) that do not reply to the standard CSI 16/18 queries.
+        match Picker::from_query_stdio_with_options(QueryStdioOptions {
+            text_sizing_protocol: true,
+        }) {
+            Ok(picker) => picker,
+            Err(err) => {
+                // Fall back to the conservative default that assumes ~8×16 px cells.
+                // Still better than breaking the build in a headless test run.
+                tracing::warn!("terminal capability query failed: {err:?}; using default font size");
+                Picker::from_fontsize((8, 16))
+            }
+        }
+    };
+}
+
+/// Resize `image` to fit into `width_cells`×10-rows keeping the original aspect
+/// ratio. The function updates `render_cache` and returns the number of rows
+/// (<= 10) the picture will occupy.
+fn ensure_image_cache(
+    image: &DynamicImage,
+    width_cells: u16,
+    render_cache: &std::cell::RefCell<Option<ImageRenderCache>>,
+) -> usize {
+    if let Some(cache) = render_cache.borrow().as_ref() {
+        if cache.width_cells == width_cells {
+            return cache.height_rows;
+        }
+    }
+
+    let picker = &*TERMINAL_PICKER;
+    let (char_w_px, char_h_px) = picker.font_size();
+
+    // Heuristic to compensate for Hi-DPI terminals (iTerm2 on Retina Mac) that
+    // report logical pixels (≈ 8×16) while the iTerm2 graphics protocol
+    // expects *device* pixels.  Empirically the device-pixel-ratio is almost
+    // always 2 on macOS Retina panels.
+    let hidpi_scale = if picker.protocol_type() == ProtocolType::Iterm2 {
+        2.0f64
+    } else {
+        1.0
+    };
+
+    // The fallback Halfblocks protocol encodes two pixel rows per cell, so each
+    // terminal *row* represents only half the (possibly scaled) font height.
+    let effective_char_h_px: f64 = if picker.protocol_type() == ProtocolType::Halfblocks {
+        (char_h_px as f64) * hidpi_scale / 2.0
+    } else {
+        (char_h_px as f64) * hidpi_scale
+    };
+
+    let char_w_px_f64 = (char_w_px as f64) * hidpi_scale;
+
+    const MAX_ROWS: f64 = 10.0;
+    let max_height_px: f64 = effective_char_h_px * MAX_ROWS;
+
+    let (orig_w_px, orig_h_px) = {
+        let (w, h) = image.dimensions();
+        (w as f64, h as f64)
+    };
+
+    if orig_w_px == 0.0 || orig_h_px == 0.0 || width_cells == 0 {
+        *render_cache.borrow_mut() = None;
+        return 0;
+    }
+
+    let max_w_px = char_w_px_f64 * width_cells as f64;
+    let scale_w = max_w_px / orig_w_px;
+    let scale_h = max_height_px / orig_h_px;
+    let scale = scale_w.min(scale_h).min(1.0);
+
+    use image::imageops::FilterType;
+    let scaled_w_px = (orig_w_px * scale).round().max(1.0) as u32;
+    let scaled_h_px = (orig_h_px * scale).round().max(1.0) as u32;
+
+    let scaled_image = image.resize(scaled_w_px, scaled_h_px, FilterType::Lanczos3);
+
+    let height_rows = ((scaled_h_px as f64 / effective_char_h_px).ceil()) as usize;
+
+    let new_cache = ImageRenderCache {
+        width_cells,
+        height_rows,
+        scaled_image,
+    };
+    *render_cache.borrow_mut() = Some(new_cache);
+
+    height_rows
+}

codex-rs/tui/src/lib.rs

@@ -19,6 +19,7 @@ mod app;
 mod app_event;
 mod app_event_sender;
 mod bottom_pane;
+mod cell_widget;
 mod chatwidget;
 mod citation_regex;
 mod cli;
@@ -32,6 +33,7 @@ mod mouse_capture;
 mod scroll_event_helper;
 mod slash_command;
 mod status_indicator_widget;
+mod text_block;
 mod tui;
 mod user_approval_widget;
 
@@ -54,18 +56,23 @@ pub fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> std::io::
             model: cli.model.clone(),
             approval_policy,
             sandbox_policy,
-            disable_response_storage: if cli.disable_response_storage {
-                Some(true)
-            } else {
-                None
-            },
             cwd: cli.cwd.clone().map(|p| p.canonicalize().unwrap_or(p)),
             model_provider: None,
             config_profile: cli.config_profile.clone(),
             codex_linux_sandbox_exe,
         };
+        // Parse `-c` overrides from the CLI.
+        let cli_kv_overrides = match cli.config_overrides.parse_overrides() {
+            Ok(v) => v,
+            #[allow(clippy::print_stderr)]
+            Err(e) => {
+                eprintln!("Error parsing -c overrides: {e}");
+                std::process::exit(1);
+            }
+        };
+
         #[allow(clippy::print_stderr)]
-        match Config::load_with_overrides(overrides) {
+        match Config::load_with_cli_overrides(cli_kv_overrides, overrides) {
             Ok(config) => config,
             Err(err) => {
                 eprintln!("Error loading configuration: {err}");

codex-rs/tui/src/main.rs

@@ -1,11 +1,26 @@
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_tui::Cli;
 use codex_tui::run_main;
 
+#[derive(Parser, Debug)]
+struct TopCli {
+    #[clap(flatten)]
+    config_overrides: CliConfigOverrides,
+
+    #[clap(flatten)]
+    inner: Cli,
+}
+
 fn main() -> anyhow::Result<()> {
     codex_linux_sandbox::run_with_sandbox(|codex_linux_sandbox_exe| async move {
-        let cli = Cli::parse();
-        run_main(cli, codex_linux_sandbox_exe)?;
+        let top_cli = TopCli::parse();
+        let mut inner = top_cli.inner;
+        inner
+            .config_overrides
+            .raw_overrides
+            .splice(0..0, top_cli.config_overrides.raw_overrides);
+        run_main(inner, codex_linux_sandbox_exe)?;
         Ok(())
     })
 }

codex-rs/tui/src/text_block.rs

@@ -0,0 +1,32 @@
+use crate::cell_widget::CellWidget;
+use ratatui::prelude::*;
+
+/// A simple widget that just displays a list of `Line`s via a `Paragraph`.
+/// This is the default rendering backend for most `HistoryCell` variants.
+#[derive(Clone)]
+pub(crate) struct TextBlock {
+    pub(crate) lines: Vec<Line<'static>>,
+}
+
+impl TextBlock {
+    pub(crate) fn new(lines: Vec<Line<'static>>) -> Self {
+        Self { lines }
+    }
+}
+
+impl CellWidget for TextBlock {
+    fn height(&self, width: u16) -> usize {
+        // Use the same wrapping configuration as ConversationHistoryWidget so
+        // measurement stays in sync with rendering.
+        ratatui::widgets::Paragraph::new(self.lines.clone())
+            .wrap(crate::conversation_history_widget::wrap_cfg())
+            .line_count(width)
+    }
+
+    fn render_window(&self, first_visible_line: usize, area: Rect, buf: &mut Buffer) {
+        ratatui::widgets::Paragraph::new(self.lines.clone())
+            .wrap(crate::conversation_history_widget::wrap_cfg())
+            .scroll((first_visible_line as u16, 0))
+            .render(area, buf);
+    }
+}