Documentation — Spybara

app-server.md +224 −24

Details

239- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.239- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

240- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread. Returned threads include `forkedFromId` when available.240- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread. Returned threads include `forkedFromId` when available.

241- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.241- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.

242- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filters. Returned `thread` objects include runtime `status`.242- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, `searchTerm`, and experimental `parentThreadId` filters. Returned `thread` objects include runtime `status`.

243- `thread/turns/list` - page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.243- `thread/turns/list` - page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.

244- `thread/turns/items/list` - reserved for paged turn-item loading; currently returns unsupported.244- `thread/turns/items/list` - reserved for paged turn-item loading; currently returns unsupported.

245- `thread/loaded/list` - list the thread ids currently loaded in memory.245- `thread/loaded/list` - list the thread ids currently loaded in memory.

248- `thread/goal/get` - read the current goal for a thread.248- `thread/goal/get` - read the current goal for a thread.

249- `thread/goal/clear` - clear the goal for a thread; emits `thread/goal/cleared`.249- `thread/goal/clear` - clear the goal for a thread; emits `thread/goal/cleared`.

250- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.250- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.

251- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.251- `thread/archive` - move a thread's log file into the archived directory and attempt to archive spawned descendant thread logs that aren't already archived; returns `{}` on success and emits `thread/archived` for each archived thread.

252- `thread/delete` - permanently delete a persisted active or archived thread and any spawned descendant threads; returns `{}` on success and emits `thread/deleted` for each deleted thread.

252- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.253- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.

253- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.254- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

254- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.255- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

255- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.256- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

256- `thread/shellCommand` - run a user-initiated shell command against a thread. This runs outside the sandbox with full access and doesn't inherit the thread sandbox policy.257- `thread/shellCommand` - run a user-initiated shell command against a thread. This runs outside the sandbox with full access and doesn't inherit the thread sandbox policy.

257- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).258- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).

259- `thread/backgroundTerminals/list` - list running background terminals for a loaded thread (experimental; requires `capabilities.experimentalApi`).

260- `thread/backgroundTerminals/terminate` - terminate one running background terminal by app-server `processId` (experimental; requires `capabilities.experimentalApi`).

258- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.261- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

259- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."262- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

260- `thread/inject_items` - append raw Responses API items to a loaded thread's model-visible history without starting a user turn.263- `thread/inject_items` - append raw Responses API items to a loaded thread's model-visible history without starting a user turn.

281- `marketplace/add` - add a remote plugin marketplace and persist it into the user's marketplace config.284- `marketplace/add` - add a remote plugin marketplace and persist it into the user's marketplace config.

282- `marketplace/upgrade` - refresh a configured Git marketplace, or all configured Git marketplaces when you omit the marketplace name.285- `marketplace/upgrade` - refresh a configured Git marketplace, or all configured Git marketplaces when you omit the marketplace name.

283- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.286- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.

284- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.287- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, MCP server names, and a remote plugin `shareUrl` when the remote catalog provides one.

285- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.288- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.

286- `plugin/uninstall` - uninstall an installed plugin.289- `plugin/uninstall` - uninstall an installed plugin.

287- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.290- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

297- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).300- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

298- `config/read` - fetch the effective configuration on disk after resolving configuration layering.301- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

299- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).302- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

300- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; plugin imports emit `externalAgentConfig/import/completed`.303- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; non-empty imports emit `externalAgentConfig/import/progress` and `externalAgentConfig/import/completed` as work finishes. Plugin and session imports can complete asynchronously.

301- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.304- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

302- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.305- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

303- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).306- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

381- `thread/turns/list` pages through a stored thread's turn history without384- `thread/turns/list` pages through a stored thread's turn history without

382 resuming it. Use `itemsView` to choose whether turn items are omitted,385 resuming it. Use `itemsView` to choose whether turn items are omitted,

383 summarized, or fully loaded.386 summarized, or fully loaded.

384- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filtering.387- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, `searchTerm`, and experimental `parentThreadId` filtering.

385- `thread/loaded/list` returns the thread IDs currently in memory.388- `thread/loaded/list` returns the thread IDs currently in memory.

386- `thread/archive` moves the thread's persisted JSONL log into the archived directory.389- `thread/archive` moves the thread's persisted JSONL log into the archived directory and attempts to archive spawned descendant thread logs that aren't already archived.

390- `thread/delete` permanently deletes a persisted active or archived thread and its spawned descendant threads.

387- `thread/metadata/update` patches stored thread metadata, currently including persisted `gitInfo`.391- `thread/metadata/update` patches stored thread metadata, currently including persisted `gitInfo`.

388- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.392- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.

389- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.393- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.

537 541

538- `cursor` - opaque string from a prior response; omit for the first page.542- `cursor` - opaque string from a prior response; omit for the first page.

539- `limit` - server defaults to a reasonable page size if unset.543- `limit` - server defaults to a reasonable page size if unset.

540- `sortKey` - `created_at` (default) or `updated_at`.544- `sortKey` - `created_at` (default), `updated_at`, or `recency_at`.

545- `sortDirection` - `desc` (default) or `asc`.

541- `modelProviders` - restrict results to specific providers; unset, null, or an empty array includes all providers.546- `modelProviders` - restrict results to specific providers; unset, null, or an empty array includes all providers.

542- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.547- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.

543- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).548- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).

544- `cwd` - restrict results to threads whose session current working directory exactly matches this path.549- `cwd` - restrict results to threads whose session current working directory exactly matches this path.

545- `searchTerm` - search stored thread summaries and metadata before pagination.550- `searchTerm` - search stored thread summaries and metadata before pagination.

551- `parentThreadId` - restrict results to direct child threads of the given parent thread. This filter is experimental and requires `capabilities.experimentalApi = true`.

546 552

547`sourceKinds` accepts the following values:553`sourceKinds` accepts the following values:

548 554

643 649

644### Archive a thread650### Archive a thread

645 651

646Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.652Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory. Archiving a thread also attempts to archive spawned descendant threads that aren't already archived.

647 653

648```json654```json

649{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }655{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }

650{ "id": 22, "result": {} }656{ "id": 22, "result": {} }

651{ "method": "thread/archived", "params": { "threadId": "thr_b" } }657{ "method": "thread/archived", "params": { "threadId": "thr_b" } }

658{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

652```659```

653 660

654Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.661Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`. The server emits one `thread/archived` notification for each thread it actually archives; if a spawned descendant can't be archived, the request can still succeed without an archived notification for that descendant.

662

663### Delete a thread

664

665Use `thread/delete` to permanently delete a persisted active or archived thread

666and its spawned descendant threads. The server removes existing rollout files and

667associated metadata before returning success; missing rollout files are treated

668as already deleted. Ephemeral root threads can't be deleted.

669

670```json

671{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }

672{ "id": 23, "result": {} }

673{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }

674{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

675```

655 676

656### Unarchive a thread677### Unarchive a thread

657 678

696{ "id": 27, "result": {} }717{ "id": 27, "result": {} }

697```718```

698 719

720Use `thread/backgroundTerminals/list` to inspect running background terminals

721for a loaded thread. The request supports standard `cursor` and `limit`

722pagination, and the returned `processId` is the app-server process id. This

723method is experimental and requires `capabilities.experimentalApi = true`:

724

725```json

726{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }

727{ "id": 28, "result": { "data": [

728 {

729 "itemId": "item_456",

730 "processId": "42",

731 "command": "python3 -m http.server",

732 "cwd": "/workspace",

733 "osPid": null,

734 "cpuPercent": null,

735 "rssKb": null

736 }

737], "nextCursor": null } }

738```

739

740Use `thread/backgroundTerminals/terminate` with that `processId` to stop one

741background terminal. This method is experimental and requires

742`capabilities.experimentalApi = true`:

743

744```json

745{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }

746{ "id": 29, "result": { "terminated": true } }

747```

748

699### Roll back recent turns749### Roll back recent turns

700 750

701Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.751Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.

702 752

703```json753```json

704{ "method": "thread/rollback", "id": 28, "params": { "threadId": "thr_b", "numTurns": 1 } }754{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }

705{ "id": 28, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }755{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

706```756```

707 757

708## Turns758## Turns

1164 1214

1165When the client responds to `item/tool/requestUserInput`, app-server emits `serverRequest/resolved` with `{ threadId, requestId }`. If the pending request is cleared by turn start, turn completion, or turn interruption before the client answers, the server emits the same notification for that cleanup.1215When the client responds to `item/tool/requestUserInput`, app-server emits `serverRequest/resolved` with `{ threadId, requestId }`. If the pending request is cleared by turn start, turn completion, or turn interruption before the client answers, the server emits the same notification for that cleanup.

1166 1216

1217Request params include `autoResolutionMs` as an integer millisecond timeout or

1218`null`. When present, host clients can resolve the prompt automatically after that

1219interval if the user doesn't answer.

1220

1167### Dynamic tool calls (experimental)1221### Dynamic tool calls (experimental)

1168 1222

1169`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.1223`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.

1376 "_default": {1430 "_default": {

1377 "enabled": true,1431 "enabled": true,

1378 "destructive_enabled": true,1432 "destructive_enabled": true,

1379 "open_world_enabled": true1433 "open_world_enabled": true,

1434 "approvals_reviewer": "user",

1435 "default_tools_approval_mode": "auto"

1380 },1436 },

1381 "google_drive": {1437 "google_drive": {

1382 "enabled": true,1438 "enabled": true,

1383 "destructive_enabled": false,1439 "destructive_enabled": false,

1440 "approvals_reviewer": "auto_review",

1384 "default_tools_approval_mode": "prompt",1441 "default_tools_approval_mode": "prompt",

1385 "tools": {1442 "tools": {

1386 "files/delete": { "enabled": false, "approval_mode": "approve" }1443 "files/delete": { "enabled": false, "approval_mode": "approve" }

1391} }1448} }

1392```1449```

1393 1450

1451`apps._default.approvals_reviewer` sets the reviewer for all apps unless a

1452per-app value overrides it. When both are omitted, the app inherits the

1453top-level `approvals_reviewer` value. `apps._default.default_tools_approval_mode`

1454sets the fallback approval mode for tools without a per-app or per-tool

1455override. Managed approval-mode requirements override tool approval-mode

1456settings.

1457

1394Update a single app setting:1458Update a single app setting:

1395 1459

1396```json1460```json

1465 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",1529 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",

1466 "cwd": "/Users/me/project"1530 "cwd": "/Users/me/project"

1467 }1531 }

1532 ],

1533 "source": "claude-code"

1534} }

1535{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

1536```

1537

1538The optional top-level `source` import parameter labels the product that

1539produced the selected migration items.

1540

1541The server emits `externalAgentConfig/import/progress` as item types complete,

1542and `externalAgentConfig/import/completed` after all synchronous and background

1543imports finish. These notifications include the same `importId` from the

1544response and `itemTypeResults` with per-type `successes` and `failures`.

1545Completion may arrive immediately after the response or after background remote

1546imports complete.

1547

1548```json

1549{ "method": "externalAgentConfig/import/progress", "params": {

1550 "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",

1551 "itemTypeResults": [

1552 {

1553 "itemType": "AGENTS_MD",

1554 "successes": [

1555 { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }

1556 ],

1557 "failures": []

1558 }

1559 ]

1560} }

1561{ "method": "externalAgentConfig/import/completed", "params": {

1562 "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",

1563 "itemTypeResults": [

1564 {

1565 "itemType": "AGENTS_MD",

1566 "successes": [

1567 { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }

1568 ],

1569 "failures": []

1570 }

1468 ]1571 ]

1469} }1572} }

1470{ "id": 64, "result": {} }

1471```1573```

1472 1574

1473When a request includes plugin imports, the server emits `externalAgentConfig/import/completed` after the import finishes. This notification may arrive immediately after the response or after background remote imports complete.1575Read prior completed imports:

1576

1577```json

1578{ "method": "externalAgentConfig/import/readHistories", "id": 65 }

1579{ "id": 65, "result": { "data": [

1580 {

1581 "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",

1582 "completedAtMs": 1781784000000,

1583 "successes": [

1584 { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }

1585 ],

1586 "failures": []

1587 }

1588] } }

1589```

1474 1590

1475Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, `PLUGINS`,1591Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, `PLUGINS`,

1476and `MCP_SERVER_CONFIG`. For `PLUGINS` items, `details.plugins` lists each1592`MCP_SERVER_CONFIG`, `SUBAGENTS`, `HOOKS`, `COMMANDS`, and `SESSIONS`. For

1477`marketplaceName` and the `pluginNames` Codex can try to migrate. Detection1593`PLUGINS` items, `details.plugins` lists each `marketplaceName` and the

1478returns only items that still have work to do. For example, Codex skips AGENTS1594`pluginNames` Codex can try to migrate. Detection returns only items that still

1479migration when `AGENTS.md` already exists and is non-empty, and skill imports1595have work to do. For example, Codex skips AGENTS migration when `AGENTS.md`

1480don't overwrite existing skill directories.1596already exists and is non-empty, and skill imports don't overwrite existing

1597skill directories.

1481 1598

1482When detecting plugins from `.claude/settings.json`, Codex reads configured1599When detecting plugins from `.claude/settings.json`, Codex reads configured

1483marketplace sources from `extraKnownMarketplaces`. If `enabledPlugins` contains1600marketplace sources from `extraKnownMarketplaces`. If `enabledPlugins` contains

1495- **API key (`apikey`)** - the caller supplies an OpenAI API key with `type: "apiKey"`, and Codex stores it for API requests.1612- **API key (`apikey`)** - the caller supplies an OpenAI API key with `type: "apiKey"`, and Codex stores it for API requests.

1496- **ChatGPT managed (`chatgpt`)** - Codex owns the ChatGPT OAuth flow, persists tokens, and refreshes them automatically. Start with `type: "chatgpt"` for the browser flow or `type: "chatgptDeviceCode"` for the device-code flow.1613- **ChatGPT managed (`chatgpt`)** - Codex owns the ChatGPT OAuth flow, persists tokens, and refreshes them automatically. Start with `type: "chatgpt"` for the browser flow or `type: "chatgptDeviceCode"` for the device-code flow.

1497- **ChatGPT external tokens (`chatgptAuthTokens`)** - experimental and intended for host apps that already own the user's ChatGPT auth lifecycle. The host app supplies an `accessToken`, `chatgptAccountId`, and optional `chatgptPlanType` directly, and must refresh the token when asked.1614- **ChatGPT external tokens (`chatgptAuthTokens`)** - experimental and intended for host apps that already own the user's ChatGPT auth lifecycle. The host app supplies an `accessToken`, `chatgptAccountId`, and optional `chatgptPlanType` directly, and must refresh the token when asked.

1615- **Amazon Bedrock** - `account/read` reports Bedrock accounts as `type: "amazonBedrock"` and indicates whether credentials come from a Codex-managed Bedrock API key (`credentialSource: "codexManaged"`) or the external AWS credential chain (`credentialSource: "awsManaged"`). `account/updated.authMode` uses `bedrockApiKey` for Codex-managed Bedrock API keys.

1498 1616

1499### API overview1617### API overview

1500 1618

1503- `account/login/completed` (notify) - emitted when a login attempt finishes (success or error).1621- `account/login/completed` (notify) - emitted when a login attempt finishes (success or error).

1504- `account/login/cancel` - cancel a pending managed ChatGPT login by `loginId`.1622- `account/login/cancel` - cancel a pending managed ChatGPT login by `loginId`.

1505- `account/logout` - sign out; triggers `account/updated`.1623- `account/logout` - sign out; triggers `account/updated`.

1506- `account/updated` (notify) - emitted whenever auth mode changes (`authMode`: `apikey`, `chatgpt`, `chatgptAuthTokens`, or `null`) and includes `planType` when available.1624- `account/updated` (notify) - emitted whenever auth mode changes (`authMode`: `apikey`, `chatgpt`, `chatgptAuthTokens`, `agentIdentity`, `personalAccessToken`, `bedrockApiKey`, or `null`) and includes `planType` when available.

1507- `account/chatgptAuthTokens/refresh` (server request) - request fresh externally managed ChatGPT tokens after an authorization error.1625- `account/chatgptAuthTokens/refresh` (server request) - request fresh externally managed ChatGPT tokens after an authorization error.

1508- `account/rateLimits/read` - fetch ChatGPT rate limits.1626- `account/rateLimits/read` - fetch ChatGPT rate limits.

1509- `account/rateLimits/updated` (notify) - emitted whenever a user's ChatGPT rate limits change.1627- `account/rateLimits/updated` (notify) - emitted whenever a user's ChatGPT rate limits change.

1510- `account/sendAddCreditsNudgeEmail` - ask ChatGPT to email a workspace owner about depleted credits or a reached usage limit.1628- `account/sendAddCreditsNudgeEmail` - ask ChatGPT to email a workspace owner about depleted credits or a reached usage limit.

1629- `account/rateLimitResetCredit/consume` - consume one earned rate-limit reset using a caller-provided `idempotencyKey` value.

1630- `account/usage/read` - fetch ChatGPT account token-activity summaries and daily buckets.

1511- `mcpServer/oauthLogin/completed` (notify) - emitted after a `mcpServer/oauth/login` flow finishes; payload includes `{ name, success, error? }`.1631- `mcpServer/oauthLogin/completed` (notify) - emitted after a `mcpServer/oauth/login` flow finishes; payload includes `{ name, success, error? }`.

1512- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread; payload includes `{ name, status, error }`.1632- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread; payload includes `{ name, status, error }`.

1513 1633

1536}1656}

1537```1657```

1538 1658

1659```json

1660{

1661 "id": 1,

1662 "result": {

1663 "account": {

1664 "type": "amazonBedrock",

1665 "credentialSource": "codexManaged"

1666 },

1667 "requiresOpenaiAuth": false

1668 }

1669}

1670```

1671

1672```json

1673{

1674 "id": 1,

1675 "result": {

1676 "account": {

1677 "type": "amazonBedrock",

1678 "credentialSource": "awsManaged"

1679 },

1680 "requiresOpenaiAuth": false

1681 }

1682}

1683```

1684

1539```json1685```json

1540{1686{

1541 "id": 1,1687 "id": 1,

1554 1700

1555- `refreshToken` (boolean): set `true` to force a token refresh in managed ChatGPT mode. In external token mode (`chatgptAuthTokens`), app-server ignores this flag.1701- `refreshToken` (boolean): set `true` to force a token refresh in managed ChatGPT mode. In external token mode (`chatgptAuthTokens`), app-server ignores this flag.

1556- `requiresOpenaiAuth` reflects the active provider; when `false`, Codex can run without OpenAI credentials.1702- `requiresOpenaiAuth` reflects the active provider; when `false`, Codex can run without OpenAI credentials.

1703- Amazon Bedrock reports `credentialSource: "codexManaged"` when it uses a

1704 Bedrock API key managed by Codex. It reports `credentialSource: "awsManaged"`

1705 for the external AWS credential path. This identifies the selected credential

1706 source; it doesn't validate that the AWS credential chain can resolve

1707 credentials.

1557 1708

1558### 2) Log in with an API key1709### 2) Log in with an API key

1559 1710

1764 "secondary": null,1915 "secondary": null,

1765 "rateLimitReachedType": null1916 "rateLimitReachedType": null

1766 }1917 }

1767 }1918 },

1919 "rateLimitResetCredits": { "availableCount": 2 }

1768} }1920} }

1769{ "method": "account/rateLimits/updated", "params": {1921{ "method": "account/rateLimits/updated", "params": {

1770 "rateLimits": {1922 "rateLimits": {

1786- `planType` is included when the server returns the ChatGPT plan associated with a bucket.1938- `planType` is included when the server returns the ChatGPT plan associated with a bucket.

1787- `credits` is included when the server returns remaining workspace credit details.1939- `credits` is included when the server returns remaining workspace credit details.

1788- `rateLimitReachedType` identifies the server-classified limit state when one has been reached.1940- `rateLimitReachedType` identifies the server-classified limit state when one has been reached.

1941- `rateLimitResetCredits` contains the available earned-reset count when the service provides it. Fetch `account/rateLimits/read` after consuming a reset.

1942

1943### 7) Token usage (ChatGPT)

1944

1945Use `account/usage/read` to fetch ChatGPT token-activity summary fields and

1946optional daily buckets.

1947

1948```json

1949{ "method": "account/usage/read", "id": 7 }

1950{ "id": 7, "result": {

1951 "summary": {

1952 "lifetimeTokens": 1234567,

1953 "peakDailyTokens": 45678,

1954 "longestRunningTurnSec": 540,

1955 "currentStreakDays": 8,

1956 "longestStreakDays": 14

1957 },

1958 "dailyUsageBuckets": [

1959 { "startDate": "2026-06-18", "tokens": 12345 }

1960 ]

1961} }

1962```

1963

1964Field notes:

1965

1966- `summary` values may be `null` when the service hasn't returned that metric.

1967- `dailyUsageBuckets` may be `null`; when present, each bucket includes `startDate` and `tokens`.

1968- The endpoint requires authentication backed by Codex services. ChatGPT,

1969 external ChatGPT tokens, agent identity, and personal access token auth work;

1970 API-key-only and Bedrock auth don't.

1971

1972### 8) Earned rate-limit resets (ChatGPT)

1973

1974Use `account/rateLimitResetCredit/consume` to consume one earned reset.

1975

1976```json

1977{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

1978{ "id": 8, "result": { "outcome": "reset" } }

1979```

1980

1981Field notes:

1982

1983- `idempotencyKey` must be non-empty. Use a UUID for each logical redemption attempt and reuse the same value when retrying that attempt.

1984- `reset` means a credit was consumed.

1985- `alreadyRedeemed` means the same redemption completed previously. Treat it as an idempotent success and refresh account limits.

1986- `nothingToReset` means there is no eligible rate-limit window to reset.

1987- `noCredit` means the account has no earned reset credits available.

1988- Fetch `account/rateLimits/read` after consuming a reset instead of inferring updated windows from this response.

1789 1989

1790### 7) Notify a workspace owner about a limit1990### 9) Notify a workspace owner about a limit

1791 1991

1792Use `account/sendAddCreditsNudgeEmail` to ask ChatGPT to email a workspace owner when credits are depleted or a usage limit has been reached.1992Use `account/sendAddCreditsNudgeEmail` to ask ChatGPT to email a workspace owner when credits are depleted or a usage limit has been reached.

1793 1993

1794```json1994```json

1795{ "method": "account/sendAddCreditsNudgeEmail", "id": 7, "params": { "creditType": "credits" } }1995{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }

1796{ "id": 7, "result": { "status": "sent" } }1996{ "id": 9, "result": { "status": "sent" } }

1797```1997```

1798 1998

1799Use `creditType: "credits"` when workspace credits are depleted, or `creditType: "usage_limit"` when the workspace usage limit has been reached. If the owner was already notified recently, the response status is `cooldown_active`.1999Use `creditType: "credits"` when workspace credits are depleted, or `creditType: "usage_limit"` when the workspace usage limit has been reached. If the owner was already notified recently, the response status is `cooldown_active`.

app/commands.md +15 −5

Details

39search for a phrase from the thread or a branch such as `fix/login-redirect`.39search for a phrase from the thread or a branch such as `fix/login-redirect`.

40 40

41Use **Find in thread** (<kbd>Cmd</kbd> + <kbd>F</kbd>) after opening a thread41Use **Find in thread** (<kbd>Cmd</kbd> + <kbd>F</kbd>) after opening a thread

~~42to find text within that current conversation. It does not search across other~~42to find text within that current conversation. It doesn't search across other

43threads.43threads.

44 44

45## Slash commands45## Slash commands

115| `codex://settings/connections/<connection-type>` | Computer, device, or SSH connection settings. |

116| `codex://settings/connections/ssh/add?name=<ssh-config-host>` | Adds a host from your SSH config to Codex. |

117| `codex://plugins/install/<plugin-name>?marketplace=<marketplace-name>` | The install flow for a plugin from a known marketplace. |119| `codex://plugins/install/<plugin-name>?marketplace=<marketplace-name>` | The install flow for a plugin from a known marketplace. |

145Use these links when you need to open Settings or a specific settings page.147Use these links when you need to open Settings or a specific settings page.

146 148

147| Deep link | Opens |149| Deep link | Opens |

148| --------------------------------------------- | ---------------------------------------- |150| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |

155| `codex://settings/connections/computer` | Settings for controlling this Mac or PC from another device. |

156| `codex://settings/connections/devices` | Settings for controlling other devices. |

157| `codex://settings/connections/ssh` | SSH connection settings. |

158| `codex://settings/connections/ssh/add?name=<ssh-config-host>` | Adds the named host alias as a Codex-managed connection, then opens SSH connection settings. |

159

160The `name` value must match a host alias in `~/.ssh/config`. The link disables

161automatic connection for the added host. If Codex can't find the named host, it

162opens SSH connection settings and shows an error.

153 163

154Unsupported `codex://settings/...` paths open the main Settings page.164Unsupported `codex://settings/...` paths open the main Settings page.

155 165

185| -------------------------------- | -------- | ------------------------------------------------------------------------------- |195| -------------------------------- | -------- | ------------------------------------------------------------------------------- |

186| `marketplace=<marketplace-name>` | Yes | Identifies the marketplace. For an OpenAI-curated plugin, use `openai-curated`. |196| `marketplace=<marketplace-name>` | Yes | Identifies the marketplace. For an OpenAI-curated plugin, use `openai-curated`. |

187 197

188The install link accepts only the `marketplace` query parameter. If Codex cannot find the requested marketplace or plugin, it opens the Plugins page instead.198The install link accepts only the `marketplace` query parameter. If Codex can't find the requested marketplace or plugin, it opens the Plugins page instead.

189 199

190#### Plugin detail200#### Plugin detail

191 201

195 205

196`<plugin-id>` must identify the plugin. For an OpenAI-curated plugin, use the form `<plugin-name>@openai-curated`.206`<plugin-id>` must identify the plugin. For an OpenAI-curated plugin, use the form `<plugin-name>@openai-curated`.

197 207

198Codex-generated plugin links can also include these query parameters. Omit both when you handwrite a link.208Codex-generated plugin links can also include these query parameters. Omit both when you write a link manually.

199 209

201| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |211| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |

202| `hostId=<host-id>` | No | Identifies the Codex host that owns the plugin context, such as `local` or one of your configured remote connections. Codex provides these IDs. |212| `hostId=<host-id>` | No | Identifies the Codex host that owns the plugin context, such as `local` or one of your configured remote connections. Codex provides these IDs. |

203| `source=manage` | No | Preserves the app's plugin-management entry point. It is not admin-only. |213| `source=manage` | No | Preserves the app's plugin-management entry point. It's not admin-only. |

204 214

205Example: [Open the OpenAI Developers plugin](codex://plugins/openai-developers@openai-curated)215Example: [Open the OpenAI Developers plugin](codex://plugins/openai-developers@openai-curated)

206 216

cli/reference.md +52 −1

Details

88 key: "--remote",88 key: "--remote",

90 description:90 description:

~~91 "Connect the interactive TUI to a remote app-server endpoint over WebSocket or a Unix socket. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.",~~91 "Connect to a remote app-server endpoint over WebSocket or a Unix socket. Supported for `codex`, `codex resume`, `codex fork`, `codex archive`, `codex delete`, and `codex unarchive`; other subcommands reject remote mode.",

92 },92 },

93 {93 {

94 key: "--remote-auth-token-env",94 key: "--remote-auth-token-env",

180 description:180 description:

181 "Archive a saved interactive session by session ID or session name.",181 "Archive a saved interactive session by session ID or session name.",

182 },182 },

183 {

184 key: "codex delete",

185 href: "/codex/cli/reference#codex-delete",

186 type: "stable",

187 description:

188 "Permanently delete a saved interactive session by session ID or session name.",

189 },

183 {190 {

184 key: "codex cloud",191 key: "codex cloud",

185 href: "/codex/cli/reference#codex-cloud",192 href: "/codex/cli/reference#codex-cloud",

1060 },1067 },

1061];1068];

1062 1069

1070export const deleteOptions = [

1071 {

1072 key: "SESSION",

1073 type: "session ID | session name",

1074 description:

1075 "Saved session to delete. Session IDs take precedence over session names.",

1076 },

1077 {

1078 key: "--force",

1079 type: "boolean",

1080 defaultValue: "false",

1081 description:

1082 "Delete without prompting. The session argument must be a UUID; names still require interactive confirmation.",

1083 },

1084 {

1085 key: "--remote",

1086 type: "ws://host:port | wss://host:port | unix:// | unix://PATH",

1087 description:

1088 "Connect to a remote app-server endpoint before deleting the session.",

1089 },

1090 {

1091 key: "--remote-auth-token-env",

1092 type: "ENV_VAR",

1093 description:

1094 "Read a bearer token from this environment variable when `--remote` requires authentication.",

1095 },

1096];

1097

1063## How to read this reference1098## How to read this reference

1064 1099

1065This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.1100This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.

1161 1196

1162<ConfigTable client:load options={archiveOptions} />1197<ConfigTable client:load options={archiveOptions} />

1163 1198

1199### `codex delete`

1200

1201Permanently delete a saved interactive session by session ID or session name.

1202Use this only when you want to remove the transcript instead of hiding it from

1203active session lists.

1204

1205```bash

1206codex delete <SESSION>

1207codex delete <SESSION_UUID> --force

1208```

1209

1210<ConfigTable client:load options={deleteOptions} />

1211

1212Use `--force` only with a session UUID. Named sessions still require

1213confirmation so Codex doesn't delete a repeated or ambiguous name without a prompt.

1214

1164### `codex cloud`1215### `codex cloud`

1165 1216

1166Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.1217Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.

cli/slash-commands.md +34 −7

Details

33| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |33| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

34| [`/hooks`](#review-hooks-with-hooks) | Review lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |34| [`/hooks`](#view-and-manage-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |

35| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |35| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |

36| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |36| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |

37| [`/delete`](#delete-the-current-session-with-delete) | Permanently delete the current session and exit Codex. | Remove the transcript and descendant sessions when archiving isn't enough. |

37| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |38| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

38| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |39| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

42| [`/approve`](#approve-an-auto-review-denial-with-approve) | Approve one retry of a recent auto review denial. | Retry a command or action that the auto reviewer denied. |43| [`/approve`](#approve-an-auto-review-denial-with-approve) | Approve one retry of a recent auto review denial. | Retry a command or action that the auto reviewer denied. |

45| [`/hooks`](#view-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect hook configuration loaded into the current session. |46| [`/import`](#import-claude-code-configuration-with-import) | Import Claude Code setup, project files, and recent chats. | Migrate supported external-agent artifacts into Codex configuration and local files. |

47| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |48| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

64| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |65| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |

65| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |66| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |

67| [`/usage`](#view-account-usage-with-usage) | View account token usage or use a rate-limit reset. | Inspect daily, weekly, or cumulative ChatGPT token activity from inside the TUI. |

66| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |68| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |

67| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |69| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |

68| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |70| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |

171Expected: Codex inserts the selected skill context so the next request follows173Expected: Codex inserts the selected skill context so the next request follows

172that skill's instructions.174that skill's instructions.

173 175

174### View lifecycle hooks with `/hooks`176### Import Claude Code configuration with `/import`

175 177

1761. Type `/hooks`.1781. Type `/import`.

1772. Review the loaded lifecycle hook configuration.1792. Choose the Claude Code setup, project files, or recent chats you want to migrate.

180

181Expected: Codex opens the external-agent import picker and imports the selected

182supported artifacts into Codex configuration and local files.

178 183

179Expected: Codex shows the hooks that can run in the current session.184Run `/import` from a local TUI session. It's unavailable while a task is running,

185in remote sessions, and while connected to the local app-server daemon.

180 186

181### Clear the terminal and start a new chat with `/clear`187### Clear the terminal and start a new chat with `/clear`

182 188

201 207

202`/archive` is unavailable while a task is running.208`/archive` is unavailable while a task is running.

203 209

210### Delete the current session with `/delete`

211

2121. Type `/delete` and press Enter.

2132. Confirm that you want to delete the current session and exit Codex.

214

215Expected: Codex deletes the current session transcript and closes the

216interactive TUI. Deletion is permanent and also removes spawned descendant

217sessions.

218

219`/delete` is unavailable while a task is running or in a side conversation.

220

204### Update permissions with `/permissions`221### Update permissions with `/permissions`

205 222

2061. Type `/permissions` and press Enter.2231. Type `/permissions` and press Enter.

270Expected: Codex prints a summary confirming that it's operating where you287Expected: Codex prints a summary confirming that it's operating where you

271expect.288expect.

272 289

290### View account usage with `/usage`

291

2921. Type `/usage` to open the usage menu.

2932. Choose whether to show token activity or redeem an available earned reset.

2943. To open token activity directly, type `/usage daily`, `/usage weekly`, or `/usage cumulative`.

295

296Expected: Codex opens usage actions or shows account token activity for the

297selected view. If the session doesn't have Codex service account auth, Codex

298shows a sign-in requirement.

299

273### Inspect config layers with `/debug-config`300### Inspect config layers with `/debug-config`

274 301

2751. Type `/debug-config`.3021. Type `/debug-config`.

449discoverable plugins that your configuration allows, and installed plugin state.476discoverable plugins that your configuration allows, and installed plugin state.

450Press <kbd>Space</kbd> on an installed plugin to toggle its enabled state.477Press <kbd>Space</kbd> on an installed plugin to toggle its enabled state.

451 478

452### Review hooks with `/hooks`479### View and manage lifecycle hooks with `/hooks`

453 480

4541. Type `/hooks`.4811. Type `/hooks`.

4552. Choose a hook event to inspect the matching handlers.4822. Choose a hook event to inspect the matching handlers.

config-reference.md +67 −1

Details

284 description:284 description:

285 "Default allow/deny for app tools with `open_world_hint = true`.",285 "Default allow/deny for app tools with `open_world_hint = true`.",

286 },286 },

287 {

288 key: "apps._default.approvals_reviewer",

289 type: "user | auto_review",

290 description:

291 "Default reviewer for app tool approval prompts unless overridden per app. When omitted, apps inherit the top-level `approvals_reviewer` value.",

292 },

293 {

294 key: "apps._default.default_tools_approval_mode",

295 type: "auto | prompt | approve",

296 description:

297 "Default approval behavior for app tools without per-app or per-tool overrides.",

298 },

287 {299 {

288 key: "apps.<id>.destructive_enabled",300 key: "apps.<id>.destructive_enabled",

289 type: "boolean",301 type: "boolean",

302 description:314 description:

303 "Default enabled state for tools in this app unless a per-tool override exists.",315 "Default enabled state for tools in this app unless a per-tool override exists.",

304 },316 },

317 {

318 key: "apps.<id>.approvals_reviewer",

319 type: "user | auto_review",

320 description:

321 "Reviewer for this app's tool approval prompts. Overrides `apps._default.approvals_reviewer`.",

322 },

305 {323 {

306 key: "apps.<id>.default_tools_approval_mode",324 key: "apps.<id>.default_tools_approval_mode",

307 type: "auto | prompt | approve",325 type: "auto | prompt | approve",

348 description:366 description:

349 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",367 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",

350 },368 },

369 {

370 key: "features.code_mode.enabled",

371 type: "boolean",

372 description:

373 "Enable code mode feature configuration. This feature is under development and off by default.",

374 },

375 {

376 key: "features.code_mode.excluded_tool_namespaces",

377 type: "array<string>",

378 description:

379 "Tool namespaces code mode excludes from nested code-mode tool guidance and executor exposure.",

380 },

381 {

382 key: "features.code_mode.direct_only_tool_namespaces",

383 type: "array<string>",

384 description:

385 "Tool namespaces code mode can use only through direct tool calls.",

386 },

387 {

388 key: "features.rollout_budget.enabled",

389 type: "boolean",

390 description:

391 "Enable rollout budget tracking. This feature is under development and off by default. When enabled, `features.rollout_budget.limit_tokens` is required.",

392 },

393 {

394 key: "features.rollout_budget.limit_tokens",

395 type: "integer",

396 description:

397 "Positive token limit for rollout budget tracking. Required when rollout budget is enabled.",

398 },

399 {

400 key: "features.rollout_budget.reminder_interval_tokens",

401 type: "integer",

402 description:

403 "Positive token interval between rollout budget reminders. Defaults to 10% of `limit_tokens`, with a minimum of 1 token.",

404 },

405 {

406 key: "features.rollout_budget.sampling_token_weight",

407 type: "number",

408 description:

409 "Finite non-negative multiplier for sampled tokens in rollout budget accounting. Defaults to `1.0`.",

410 },

411 {

412 key: "features.rollout_budget.prefill_token_weight",

413 type: "number",

414 description:

415 "Finite non-negative multiplier for prefill tokens in rollout budget accounting. Defaults to `1.0`.",

416 },

351 {417 {

352 key: "hooks",418 key: "hooks",

353 type: "table",419 type: "table",

1675 key: "features.computer_use",1741 key: "features.computer_use",

1676 type: "boolean",1742 type: "boolean",

1677 description:1743 description:

1678 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",1744 "Set to `false` in `requirements.toml` to disable Computer Use, Record & Replay, and related install or enablement flows.",

1679 },1745 },

1680 {1746 {

1681 key: "features.workspace_dependencies",1747 key: "features.workspace_dependencies",

config-sample.md +36 −0

Details

677 677

678# prevent_idle_sleep = false678# prevent_idle_sleep = false

679 679

680# Code mode namespaces. This feature is under development and off by default.

681

682# [features.code_mode]

683

684# enabled = true

685

686# excluded_tool_namespaces = ["mcp__codex_apps"]

687

688# direct_only_tool_namespaces = ["mcp__history"]

689

690# Rollout budget tracking. This feature is under development and off by default.

691

692# limit_tokens is required when enabled.

693

694# Optional reminder_interval_tokens defaults to 10% of limit_tokens.

695

696# Token weights default to 1.0.

697

698# [features.rollout_budget]

699

700# enabled = true

701

702# limit_tokens = 100000

703

704# reminder_interval_tokens = 10000

705

706# sampling_token_weight = 1.0

707

708# prefill_token_weight = 1.0

709

680################################################################################710################################################################################

681 711

682# Memories (table)712# Memories (table)

915 945

916# open_world_enabled = true946# open_world_enabled = true

917 947

948# approvals_reviewer = "user" # user | auto_review

949

950# default_tools_approval_mode = "auto" # auto | prompt | approve

951

918#952#

919 953

920# [apps.google_drive]954# [apps.google_drive]

925 959

926# default_tools_enabled = true960# default_tools_enabled = true

927 961

962# approvals_reviewer = "auto_review"

963

928# default_tools_approval_mode = "prompt" # auto | prompt | approve964# default_tools_approval_mode = "prompt" # auto | prompt | approve

929 965

930#966#

enterprise/managed-configuration.md +3 −3

Details

269 269

270Use `[experimental_network]` in `requirements.toml` when administrators should270Use `[experimental_network]` in `requirements.toml` when administrators should

271define network access requirements centrally. These requirements are separate271define network access requirements centrally. These requirements are separate

272from the user `features.network_proxy` toggle: they can configure sandboxed272from the user `features.network_proxy` toggle: they can configure sandbox

273networking without that feature flag, but they don't grant command network273networking without that feature flag, but they don't grant command network

274access when the active sandbox keeps networking off.274access when the active sandbox keeps networking off.

275 275

291rules don't remain effective.291rules don't remain effective.

292 292

293The domain syntax, local/private destination rules, deny-over-allow behavior,293The domain syntax, local/private destination rules, deny-over-allow behavior,

294and DNS rebinding limitations are the same as the sandboxed networking behavior294and DNS rebinding limitations are the same as the sandbox networking behavior

295described in [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security#network-isolation).295described in [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security#network-isolation).

296 296

297### Pin feature flags297### Pin feature flags

319- `browser_use = false` disables Browser Use and Browser Agent availability.319- `browser_use = false` disables Browser Use and Browser Agent availability.

320- `browser_use_full_cdp_access = false` prevents users from enabling full CDP320- `browser_use_full_cdp_access = false` prevents users from enabling full CDP

321 access in Browser Developer mode.321 access in Browser Developer mode.

322- `computer_use = false` disables Computer Use availability and related322- `computer_use = false` disables Computer Use, Record & Replay, and related

323 install or setup flows.323 install or setup flows.

324 324

325If omitted, these features are allowed by policy, subject to normal client,325If omitted, these features are allowed by policy, subject to normal client,

plugins.md +4 −2

Details

160 160

161## Plugin guides161## Plugin guides

162 162

163- [Codex Security plugin](https://developers.openai.com/codex/security/plugin): Scan authorized code,163- [Record & Replay](https://developers.openai.com/codex/record-and-replay): Show Codex a workflow

164 confirm findings, and prepare reviewed fixes.164 once and turn it into a reusable skill.

165- [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin): Install the

166 plugin, scan authorized code, and review the result.

record-and-replay.md +81 −0 created

Details

1# Record & Replay

3Record & Replay is available on macOS. Initial availability excludes the

4 European Economic Area, the United Kingdom, and Switzerland. Computer Use must

5 also be available and enabled.

7Record & Replay lets you demonstrate a workflow on your

8Mac and turn it into a reusable skill. Use it when the workflow is repetitive,

9depends on your preferences, or is easier to show than to describe in a prompt.

11For example, you might record how you file an expense, book a parking space,

12create a correctly configured issue, publish a video, or download a recurring

13report. Codex can package the pattern into a skill that you can use again with

14Computer Use, browser actions, connected plugins, or a combination of them.

16## Before you start

18Pick a workflow that you already know how to complete. Record & Replay works

19best when the steps are stable and the success criteria are clear.

21## Start a recording

23<WorkflowSteps>

251. Open **Plugins** in the Codex app.

262. Open the **+** menu.

273. Select **Record a skill**.

284. Review the suggested prompt, give Codex any helpful context, and submit it.

295. When Codex asks for permission to record your actions, approve the request

30 once you are ready to demonstrate the workflow.

316. Perform the workflow on your Mac.

327. When you are done, stop recording from the menu bar, overlay, or tell Codex

33 that you are done.

35</WorkflowSteps>

37During recording, Codex observes the actions and window content needed to learn

38the workflow. Recording continues until you stop it. Keep the recording focused

39on the task you want Codex to learn.

41After you stop recording, Codex inspects the captured workflow and drafts a

42skill. The skill explains when to use the workflow, what inputs it needs, what

43steps to follow, and how to verify the result. You can also ask Codex to

44refine the skill further.

46## Replay the workflow

48Start a new thread and ask Codex to use the generated skill. Give it the

49values that are different this time, such as the file to upload, the issue to

50create, or the date range for the report.

52Codex uses the skill as reusable context for the task. It can then complete the

53workflow with the tools available in the current environment, including

54Computer Use, browser actions, and installed plugins.

56## Tips for better recordings

58- Keep the demonstration short and complete.

59- Let Codex know your goal and any specific inputs that might vary between

60 skill uses before you start recording.

61- Use realistic inputs, but avoid secrets and sensitive data.

62- Refine the skill after recording to call out hidden preferences that matter,

63 such as naming conventions, field defaults, or decision points.

64- Stop recording when the workflow is complete instead of continuing into

65 unrelated cleanup.

67## When to build another plugin

69Record & Replay is a fast way to create a skill from a demonstrated workflow.

70If you want to distribute a separate stable package across a team, bundle

71multiple skills, include app integrations, add MCP servers, or manage install

72metadata, package that workflow as its own plugin. See

73[Build plugins](https://developers.openai.com/codex/plugins/build).

75## Troubleshooting

77### I don't see Record & Replay

79If your organization manages Codex with `requirements.toml`, the

80`[features].computer_use` requirement controls Record & Replay too. Setting

81`computer_use = false` makes both features unavailable.

security.md +11 −7

Details

7 class="my-8"7 class="my-8"

8/>8/>

9 9

~~10For installation steps, supported skills, and review boundaries, see the~~10For a prescriptive first local scan, start with the [Codex Security plugin

~~11[Codex Security plugin guide](https://developers.openai.com/codex/security/plugin).~~11quickstart](https://developers.openai.com/codex/security/plugin).

12 12

13### Explore plugin use cases13### Explore plugin use cases

14 14

~~15- [Run a deep security scan](https://developers.openai.com/codex/use-cases/deep-security-scan) to perform a higher-recall repository-wide audit.~~15- [Run a security scan](https://developers.openai.com/codex/security/plugin/scans) for a repository or one scoped folder.

~~16- [Scan code changes for security](https://developers.openai.com/codex/use-cases/scan-code-changes-for-security) before you merge a pull request or branch.~~16- [Run a deep security scan](https://developers.openai.com/codex/security/plugin/deep-scans) when you need a more comprehensive scan and can wait longer for it to finish.

~~17- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog) with bounded fixes for approved findings.~~17- [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes) before you merge a pull request or branch.

18- [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog) when you have existing security findings to review.

19- [Fix and verify findings](https://developers.openai.com/codex/security/plugin/fix-findings) with bounded patches for approved findings.

20- [Export or track findings](https://developers.openai.com/codex/security/plugin/export-findings) as portable artifacts or approval-gated tracking destinations.

21- [See what's new](https://developers.openai.com/codex/security/plugin/changelog) in the Codex Security plugin.

18 22

19The plugin runs in your Codex thread. Codex Security cloud scans connected23The plugin runs in your Codex thread. Codex Security cloud scans connected

20 GitHub repositories through Codex Web. For Codex sandboxing, approvals,24 GitHub repositories through Codex Web. For Codex sandboxing, approvals,

49 53

50## Related docs54## Related docs

51 55

~~52- [Codex Security plugin guide](https://developers.openai.com/codex/security/plugin) covers local repository and diff-review workflows in Codex.~~56- [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin) walks through installation and a first local scan.

~~53- [Codex Security cloud setup](https://developers.openai.com/codex/security/setup) covers setup, scanning, and findings review.~~57- [Codex Security cloud setup](https://developers.openai.com/codex/security/setup) details setup, scanning, and findings review.

54- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.58- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.

55- [FAQ](https://developers.openai.com/codex/security/faq) covers common product questions.59- [FAQ](https://developers.openai.com/codex/security/faq) covers common product questions.

security/plugin.md +109 −114

Details

~~1# Codex Security plugin~~1# Codex Security plugin quickstart

2 2

~~3The Codex Security plugin adds security-review workflows to Codex for code that~~3Codex Security is a security-review plugin for Codex that scans your code for

~~4you have authorization to assess. Use it from an open repository to investigate~~4vulnerabilities, validates plausible findings, and presents evidence and

~~5a codebase, review a change set for security regressions, confirm plausible~~5remediation guidance in a reviewable workspace. Use it to find security issues

~~6findings, and prepare minimal fixes for review.~~6in code you own or have authorization to assess before they reach production.

7 7

~~8This page covers the installable plugin that runs in your Codex thread. For~~8This quickstart takes you through one recommended first run: an ordinary,

~~9 the research-preview product that scans connected GitHub repositories through~~9read-only scan of a local repository in the Codex app.

~~10 Codex Web, see [Codex Security](https://developers.openai.com/codex/security).~~10

11This page covers the plugin that runs in a local Codex thread. To scan a

12 connected GitHub repository in Codex web, see [Codex Security cloud

13 setup](https://developers.openai.com/codex/security/setup).

11 14

12## Install the plugin15## Install the plugin

13 16

~~14<Tabs~~17Open the repository you want to assess in the Codex app, then install Codex

~~15 param="install"~~18Security:

~~16 tabs={[~~19

~~17 {~~20<div className="not-prose my-6">

~~18 id: "app",~~

~~19 label: "Codex app",~~

~~20 },~~

~~21 {~~

~~22 id: "cli",~~

~~23 label: "Codex CLI",~~

~~24 },~~

~~25 ]}~~

~~26>~~

~~27 <div slot="app">~~

28 <ButtonLink21 <ButtonLink

29 href="codex://plugins/install/codex-security?marketplace=openai-curated"22 href="codex://plugins/install/codex-security?marketplace=openai-curated"

30 color="primary"23 color="primary"

31 variant="solid"24 variant="solid"

32 size="lg"25 size="lg"

33 pill26 pill

~~34 className="mt-2"~~

35 >27 >

36 Install the Codex Security plugin28 Install the Codex Security plugin

37 </ButtonLink>29 </ButtonLink>

30</div>

38 31

~~39 <br />~~32After installation, start a new thread in that repository. Codex loads plugins

40 33when the thread starts, so don't continue in a thread that was already open.

~~41 After installation, start a new thread in the repository you want to~~

~~42 assess.~~

43 34

~~44 </div>~~35## Run your first scan

45 36

~~46 <div slot="cli">~~37For the best scan quality, use `gpt-5.5`

~~47 <WorkflowSteps variant="headings">~~38with `high` or `xhigh` reasoning effort.

~~48 1. Open Codex~~

49 39

~~50 Start Codex from your repository:~~40<VideoPlayer

41 src="/videos/codex/security/scan-setup-to-findings.mp4"

42 poster="/videos/codex/security/scan-setup-to-findings-poster.webp"

43/>

51 44

~~52 ```bash~~45<WorkflowSteps variant="headings">

~~53 codex~~

~~54 ```~~

55 46

~~56 2. Open the plugin browser~~471. Ask for an ordinary scan

57 48

~~58 Enter:~~49 Send this prompt in the new thread:

59 50

60 ```text51 ```text

~~61 /plugins~~52 Run a Codex Security scan on this repository.

62 ```53 ```

63 54

~~64 3. Install Codex Security~~552. Confirm the setup

65 56

~~66 Search for **Codex Security**, open it, and select `Install plugin`.~~57 Codex opens a setup workspace before it starts. For your first run, use these

67 58 settings:

~~68 4. Start a new thread~~59 - **Scan type:** `Codebase`

69 60 - **Deep scan:** Off

~~70 Start a new thread in the repository you are authorized to review.~~61 - **Scan area:** `Entire codebase`

~~71 </WorkflowSteps>~~62 - **Threat model scoping guidance:** Leave blank unless you already know a

72 63 specific attack vector or application area that deserves priority.

65 Confirm that **Codebase**, **Current branch**, and **Last commit** identify

66 the repository you intended to scan. Then select **Start scan**.

68 <figure className="not-prose my-6">

69 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

70 <img

71 src={scanSetup.src}

72 alt="Codex Security setup workspace configured to scan an entire codebase"

73 className="block h-auto w-full"

74 />

73 </div>75 </div>

~~74</Tabs>~~76 <figcaption className="mt-3 text-sm text-secondary">

75 77 Configure the scan target, scan area, branch, and optional threat model

~~76## Choose a security workflow~~78 guidance before starting the scan.

77 79 </figcaption>

~~78Choose the narrowest workflow that answers your question. A diff-focused scan~~80 </figure>

~~79is faster to review than a repository-wide scan; a deep scan intentionally uses~~81

~~80more time and tokens to search for more candidate findings.~~823. Let the scan finish

81 83

82| Goal | Skill | Scope and output |84 The scan can take time. Keep the thread running until the workspace reports

83| -------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |85 completion. If Codex identifies a configuration limitation, review the exact

84| Review a repository or one scoped path | `$codex-security:security-scan` | Runs threat modeling, finding discovery, validation, attack-path analysis, and produces Markdown and HTML reports. |86 limitation and proposed change before allowing it to update your

85| Run a higher-recall audit | `$codex-security:deep-security-scan` | Repeats repository-wide discovery with delegated workers before validation and reporting. Use it only for an entire repository. |87 configuration.

86| Review a change before merge | `$codex-security:security-diff-scan` | Reviews a pull request, commit, branch diff, or working-tree patch and produces a Markdown report grounded in changed code. |88

87| Fix one finding | `$codex-security:fix-finding` | Reproduces or validates one plausible finding, makes a minimal fix when needed, and checks that the vulnerable behavior no longer reproduces. |894. Review the result

91 Use the UI to browse findings or open the generated report for a complete,

92 portable review.

94 <figure className="not-prose my-6">

95 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

96 <img

97 src={findingsWorkspace.src}

98 alt="Completed Codex Security findings workspace for OWASP Juice Shop"

99 className="block h-auto w-full"

100 />

101 </div>

102 <figcaption className="mt-3 text-sm text-secondary">

103 Browse findings by severity, category, directory, patch status, and

104 review status.

105 </figcaption>

106 </figure>

88 107

~~89For example, to scan a repository:~~108</WorkflowSteps>

90 109

~~91```text~~110## What the scan creates

~~92Use $codex-security:security-scan to scan this repository for security~~

~~93vulnerabilities. Keep the scan grounded in code evidence, validate plausible~~

~~94findings where feasible, and return the final report paths. Do not modify code.~~

~~95```~~

96 111

~~97To review the current change instead:~~112Every completed scan opens a findings workspace. Use it to review findings and

113coverage without inspecting raw artifacts. The scan also creates:

98 114

~~99```text~~115- `report.md`, a complete portable report for sharing or archiving.

100Use $codex-security:security-diff-scan to review the current branch diff for116- Structured scan data in `scan-manifest.json`, `findings.json`, and

101security regressions. Keep the review scoped to changed code and directly117 `coverage.json` for automation and integrations. You normally don't need to

102supporting files. Do not modify code.118 open these files yourself.

103```

104 119

105## Review the result and fix findings120## Choose your next workflow

106 121

107Repository scans use a staged workflow:122- [Run a standard or scoped scan](https://developers.openai.com/codex/security/plugin/scans) when you want

123 to scan a repository or one folder with the default workflow.

124- [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans) when you need a more

125 comprehensive scan and can wait longer for it to finish.

126- [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes) when the target is

127 a pull request, commit, branch range, or working-tree patch.

128- [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog) when you have

129 existing security findings to review.

130- [Fix and verify a finding](https://developers.openai.com/codex/security/plugin/fix-findings) after you

131 accept one finding for remediation.

132- [Export or track findings](https://developers.openai.com/codex/security/plugin/export-findings) when you

133 need JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a

134 private draft GitHub Security Advisory.

108 135

1091. **Threat modeling** identifies entry points, trust boundaries, sensitive136## Install from Codex CLI

110 actions, and risky components.

1112. **Finding discovery** looks for concrete source-to-sink paths or broken

112 controls in the requested scope.

1133. **Validation** tests or otherwise verifies plausible findings and records

114 evidence or proof gaps.

1154. **Attack-path analysis** traces exploitable paths and rates severity for

116 findings that survive validation.

1175. **Reporting** writes findings, affected locations, validation evidence,

118 remediation guidance, and review directives to artifacts.

119 137

120An ordinary repository scan or a deep scan writes `report.md` and a readable138To install the same plugin from the CLI, start Codex in the repository and open

121`report.html` within its scan directory. A diff scan writes a focused Markdown139the plugin browser:

122report. Review affected files, evidence, assumptions, and severity before

123starting remediation.

~~124~~

125When a finding is actionable, ask for a bounded fix:

126 140

127```text141```text

128Use $codex-security:fix-finding to fix finding [finding ID or report142codex

129reference]. Add focused regression coverage, verify legitimate behavior still143/plugins

130works, and show that the original issue no longer reproduces. Do not broaden

131the change beyond this finding.

132```144```

133 145

134## Keep security work authorized and reviewable146Search for **Codex Security**, select `Install plugin`, and start a new thread.

~~135~~ 147Then use the same first-scan prompt.

136Run scans only against repositories, diffs, and systems that you own or that

137your organization authorizes you to assess. A finding is an input to review,

138not an instruction to merge code or test unrelated targets.

~~139~~

140- Keep the first scan read-only unless you explicitly ask Codex to prepare a

141 fix.

142- Review commands that build, run, or reproduce behavior before approving

143 them, especially in unfamiliar repositories.

144- Review every proposed patch and validation result before merging it.

145- Keep repository instructions and approval policies in place while using the

146 plugin. For details, see [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security).

~~147~~

148## Explore security use cases

~~149~~

150- [Run a deep security scan](https://developers.openai.com/codex/use-cases/deep-security-scan)

151- [Scan code changes for security](https://developers.openai.com/codex/use-cases/scan-code-changes-for-security)

152- [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)

security/plugin/changelog.md +46 −0 created

Details

1# Codex Security plugin changelog

3This changelog highlights changes that affect how you run scans, review

4results, and move findings toward remediation.

6## 0.1.9 (June 2026)

8### Review scans in the findings workspace

10- Review completed scans in a dedicated workspace that brings findings,

11 coverage, severity, confidence, and scan artifacts together.

12- Filter and sort findings, including sorting by highest confidence, while

13 preserving your workspace state during refreshes.

14- Open a finding to review source evidence, validation details, reachability,

15 impact, and remediation guidance in one place.

17### Run scans with less setup

19- Run standard scans against Git repositories, individual folders, or

20 codebases without Git history. Deep scans can also target a specific folder.

21- Cancel an active scan explicitly, resume an interrupted scan without another

22 setup prompt, and receive a warning before starting concurrent deep scans.

23- Follow clearer setup and progress states, with more compact progress

24 summaries and errors that remain visible until you address them.

26### Export portable, verifiable results

28- Use a consistent completed-scan format with a manifest, structured findings,

29 coverage data, and a Markdown report derived from the same canonical result.

30- Export findings as JSON, CSV, or SARIF for analysis, archiving, and integration

31 with other security tools.

32- Improved scan completion and filesystem handling, including fixes for Windows

33 paths and scan locking.

35### Triage and track existing findings

37- Triage existing findings from scanners, advisories, bug bounty reports,

38 GitHub, Jira, Linear, or Codex Security results against the current codebase.

39 The triage workflow returns an evidence-backed verdict and a prioritized

40 action queue.

41- Track selected validated findings in Linear, Jira, or GitHub issues, or create

42 a private draft GitHub Security Advisory when the repository meets the

43 advisory requirements.

44- Review duplicate checks, source context, destination visibility, and the

45 exact proposed content before approving a write. Codex reads the result back

46 after creation or update to verify it.

security/plugin/code-changes.md +161 −0 created

Details

1# Review code changes for security

3Use a security change review when you need evidence about regressions introduced

4by one Git-backed change set. The workflow reviews every changed source-like

5file and directly supporting code without turning the task into a general

6repository audit.

8If you want to scan a full repository instead of a specific change, see [Run a

9security scan](https://developers.openai.com/codex/security/plugin/scans).

11## Run a manual review

13For uncommitted changes, send:

15```text

16Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

17```

19For a commit or branch range, identify both ends when needed:

21```text

22Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

23```

25You can also name a pull request when its base and head revisions are available

26in the local checkout.

28## Confirm the change in setup

30<WorkflowSteps>

321. Confirm **Scan type** is `Changes`.

332. Confirm the checked-out **Codebase**, **Current branch**, and **Last commit**.

343. Under **Changes to review**, choose:

35 - `Uncommitted changes` for the current working tree.

36 - The latest commit for a single-commit review.

37 - A base and head revision for a branch or pull-request range.

384. Confirm that the summary describes the change you intended to review.

395. Select **Start scan**.

41</WorkflowSteps>

43The workflow doesn't check out another branch or change the selected working

44tree. If a requested revision isn't available locally, fetch it before the

45review or provide a locally available base and head.

47## Act on findings

49After reviewing the results, [fix and verify an accepted

50finding](https://developers.openai.com/codex/security/plugin/fix-findings) or [export and track

51findings](https://developers.openai.com/codex/security/plugin/export-findings).

53## Automate reviews in CI/CD

55You can run a change review from any CI/CD system that can check out the target

56revisions and invoke the Codex CLI without interaction. Resolve the exact base

57and head revisions, use a read-only sandbox, save the Markdown result, and

58publish it through your CI/CD system.

60### GitHub Actions example

62The following GitHub Actions workflow is one implementation of this pattern. It

63uses `openai/codex-action` to install the Codex CLI and run `codex exec` with a

64read-only sandbox. It produces a Markdown review for every in-scope pull

65request.

67Before you add the workflow:

691. Create an `OPENAI_API_KEY` repository or organization secret.

702. Save the workflow as `.github/workflows/codex-security-review.yml`.

713. Start with advisory comments. Tune the prompt and review the results before

72 making the workflow a required check.

74```yaml

75name: Codex Security pull request review

77on:

78 pull_request:

79 types: [opened, synchronize, reopened]

81jobs:

82 security_review:

83 if: github.event.pull_request.head.repo.full_name == github.repository

84 runs-on: ubuntu-latest

85 permissions:

86 contents: read

87 outputs:

88 final_message: ${{ steps.run_codex.outputs.final-message }}

90 steps:

91 - uses: actions/checkout@v5

92 with:

93 ref: refs/pull/${{ github.event.pull_request.number }}/merge

94 fetch-depth: 0

95 persist-credentials: false

97 - name: Fetch pull request refs

98 env:

99 PR_BASE_REF: ${{ github.event.pull_request.base.ref }}

100 PR_NUMBER: ${{ github.event.pull_request.number }}

101 run: |

102 git fetch --no-tags origin \

103 "$PR_BASE_REF" \

104 "+refs/pull/$PR_NUMBER/head"

105

106 - name: Run Codex Security review

107 id: run_codex

108 uses: openai/codex-action@v1

109 with:

110 openai-api-key: ${{ secrets.OPENAI_API_KEY }}

111 sandbox: read-only

112 output-file: codex-security-review.md

113 prompt: |

114 Review the pull request changes from

115 ${{ github.event.pull_request.base.sha }} to

116 ${{ github.event.pull_request.head.sha }} for security regressions.

117

118 Focus on authentication, authorization, input handling, filesystem

119 access, network requests, secrets, and changes to shared security

120 controls. Return a concise Markdown review with affected paths and

121 lines, evidence, impact, and remediation guidance. If there are no

122 findings, summarize the security-sensitive surfaces reviewed and

123 any coverage gaps.

124

125 - name: Upload the review

126 uses: actions/upload-artifact@v4

127 with:

128 name: codex-security-review

129 path: codex-security-review.md

130

131 post_review:

132 needs: security_review

133 if: needs.security_review.outputs.final_message != ''

134 runs-on: ubuntu-latest

135 permissions:

136 issues: write

137 pull-requests: write

138

139 steps:

140 - name: Post the review

141 uses: actions/github-script@v7

142 env:

143 CODEX_FINAL_MESSAGE: ${{ needs.security_review.outputs.final_message }}

144 with:

145 github-token: ${{ github.token }}

146 script: |

147 await github.rest.issues.createComment({

148 owner: context.repo.owner,

149 repo: context.repo.repo,

150 issue_number: context.payload.pull_request.number,

151 body: process.env.CODEX_FINAL_MESSAGE,

152 });

153```

154

155This workflow checks out the pull request merge commit and fetches the base and

156head refs so Codex can resolve the exact change. The security review job has

157read-only repository permissions. A separate job receives permission to post

158the final Markdown review, but it never receives the OpenAI API key.

159

160For action inputs, privilege controls, and troubleshooting, see the [Codex

161GitHub Action guide](https://developers.openai.com/codex/github-action).

security/plugin/deep-scans.md +67 −0 created

Details

1# Run a deep security scan

3A deep scan is slower but more thorough than a standard scan. Use it when you

4want to reduce variability and search more comprehensively.

6Start with a [standard scan](https://developers.openai.com/codex/security/plugin/scans). Once you're

7satisfied with the results, run a deep scan for a more thorough assessment.

9## Choose between standard and deep scans

11| | Standard scan | Deep scan |

12| ----------------------- | -------------------------------------------------- | ----------------------------------------------------- |

13| Best for | First runs and routine repository or folder review | More thorough reviews after a standard scan |

14| Variability | Standard | Reduced |

15| Scope | Repository or explicit folder | Repository or explicit folder |

16| Runtime and resources | Lower | Higher |

17| Pull requests and diffs | Use the change-review workflow | Not supported; use the change-review workflow instead |

19## Start the deep scan

21For a repository-wide review, send:

23```text

24Use $codex-security:deep-security-scan to run a deep security scan of this repository.

25```

27For one component in a monorepo, identify the folder explicitly:

29```text

30Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.

31```

33In the Codex app, a scoped deep scan resolves the selected folder as the

34**Codebase** and shows its scan area as the entire selected target.

36## Confirm setup and preflight

38<WorkflowSteps>

401. Confirm **Scan type** is `Codebase` and **Deep scan** is on.

412. Confirm that **Codebase** is the repository or exact folder you intended to

42 scan.

433. Add threat-model guidance only for concrete attack vectors, sensitive

44 application areas, or repository context that the code can't reveal.

454. Select **Start scan**.

465. Review the capability preflight. If it proposes a configuration change,

47 review the exact change and let Codex apply it only if it matches your

48 environment. Start a new thread if Codex tells you a restart is required.

50</WorkflowSteps>

52<VideoPlayer

53 src="/videos/codex/security/deep-scan-progress.mp4"

54 poster="/videos/codex/security/deep-scan-progress-poster.webp"

55/>

57## Review the result

59Deep scans use the same findings workspace and generated `report.md` as standard

60scans. Review the coverage summary before the findings. A deep scan searches

61the code more extensively, but any deferred surface or proof gap still limits

62the conclusion. For a finding you accept, continue with [Fix and verify a

63finding](https://developers.openai.com/codex/security/plugin/fix-findings).

65To review a pull request, commit, branch range, or local patch, use [Review code

66changes](https://developers.openai.com/codex/security/plugin/code-changes). A deep scan never substitutes

67for the diff-focused workflow.

security/plugin/export-findings.md +132 −0 created

Details

1# Export and track security findings

3Use a completed Codex Security scan as the source for two different handoffs:

5- **Export** creates a portable JSON, CSV, or SARIF file.

6- **Track findings** prepares selected findings as Linear, GitHub, or Jira issues

7 or one private draft GitHub Security Advisory, checks for duplicates, and

8 waits for your approval before writing.

10These workflows don't change the sealed scan bundle.

12## Export a portable artifact

14Open the completed findings workspace, select **Export**, and choose a format:

16| Format | Use it for |

17| ------ | ----------------------------------------------------------------- |

18| JSON | Preserve the sealed structured findings for tools and scripts. |

19| CSV | Review findings and current local triage state in a spreadsheet. |

20| SARIF | Send findings to tools that support the SARIF interchange format. |

22Select **Export findings** and use the returned artifact path. Keep the

23original `scan-manifest.json`, `findings.json`, and `coverage.json` together

24when another tool needs the complete scan context rather than a findings-only

25projection.

27<figure className="not-prose my-8">

28 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

29 <img

30 src={exportFindingsFormats.src}

31 alt="Export findings dialog with JSON, CSV, and SARIF format options"

32 className="block h-auto w-full"

33 />

34 </div>

35 <figcaption className="mt-3 text-sm text-secondary">

36 Export completed findings as JSON, CSV, or SARIF for downstream review and

37 tooling.

38 </figcaption>

39</figure>

41## Track selected findings

43The `$codex-security:track-findings` workflow accepts one validated finding or

44an explicitly selected batch of up to 25 findings from one sealed scan for

45issue tracking. Draft GitHub Security Advisories accept one finding only. One

46run uses one provider and one destination.

48For Linear, send a prompt like:

50```text

51Use $codex-security:track-findings to prepare finding [finding ID] from

52[completed scan directory] for the Linear team [team] and project [project, if

53any]. Check for duplicates and show me the exact issue title, body, metadata,

54and destination. Do not create or update anything until I approve that payload.

55```

57For GitHub issues, send:

59```text

60Use $codex-security:track-findings to prepare finding [finding ID] from

61[completed scan directory] for GitHub repository [owner/repository]. Check open

62and closed issues for duplicates and show me the exact issue title, body,

63metadata, repository visibility, and authenticated transport. Do not create or

64update anything until I approve that payload.

65```

67For Jira, send:

69```text

70Use $codex-security:track-findings to prepare finding [finding ID] from

71[completed scan directory] for Jira project [project key] as [issue type].

72Check for duplicates and show me the exact issue summary, description,

73metadata, and destination. Do not create or update anything until I approve

74that payload.

75```

77Jira tracking requires the native Atlassian Rovo app in Codex. Reusing an issue

78requires read access; creating or updating one requires read and write access.

80For a private draft GitHub Security Advisory, send:

82```text

83Use $codex-security:track-findings to prepare finding [finding ID] from

84[completed scan directory] as a private draft GitHub Security Advisory in

85[owner/repository]. Verify the sealed source revision, repository, affected

86paths, package metadata, and duplicate state. Show me the exact advisory

87payload, authenticated GitHub CLI identity, and disclosure warnings. Do not

88create anything until I approve that payload.

89```

91Draft advisories require one finding from a sealed `git_revision` scan, the

92 verified public canonical source repository, and administrator access. The

93 workflow doesn't batch, update, publish, or close advisories. Use an approved

94 private issue destination when the source doesn't meet those requirements.

96## Review the proposed write

98<WorkflowSteps>

1001. Confirm the finding ID and fingerprint came from the intended sealed scan.

1012. Confirm the provider, exact Linear team, GitHub repository, Jira project, or

102 advisory repository, and the live destination visibility.

1033. Review the duplicate outcome: `create`, `reuse`, `update`, or `blocked`.

1044. Read the complete proposed title, body, source locations, and provider

105 metadata. Remove exploit detail or internal evidence that the destination

106 shouldn't expose.

1075. Approve only that exact payload. A changed destination, visibility, finding

108 set, or body requires a new preview.

109

110</WorkflowSteps>

111

112Sensitive findings should go to a private destination. Creating an issue in an

113internal or public GitHub repository requires an explicit visibility warning

114and approval of the complete content. Treat a draft advisory description as

115eventually public and remove credentials, private evidence, and unnecessary

116exploit details before approval.

117

118<VideoPlayer

119 src="/videos/codex/security/issue-preview-before-approval.mp4"

120 poster="/videos/codex/security/issue-preview-before-approval-poster.webp"

121/>

122

123## Verify the tracked item

124

125After approval, Codex revalidates the sealed source, destination, access, and

126duplicate state. It processes a batch serially and stops on the first uncertain

127result. A create, update, or reuse is complete only after Codex reads the exact

128issue back and verifies its binding identifiers and content.

129

130Keep the returned canonical issue or advisory URL with your triage record.

131Continue with [Fix and verify a finding](https://developers.openai.com/codex/security/plugin/fix-findings)

132when the owner accepts the item for remediation.

security/plugin/fix-findings.md +113 −0 created

Details

1# Fix and verify security findings

3Codex Security helps you turn a backlog of accepted findings into tested code

4changes. You can fix findings in the findings workspace UI or invoke the

5remediation workflow from a prompt, the command line, or CI/CD. In each case,

6Codex validates the issue, proposes a focused patch, adds regression coverage,

7and verifies that legitimate behavior still works.

9Start by fixing one accepted finding so you can evaluate the patch and

10verification quality. Once the workflow meets your standards, scale it across

11more accepted findings by processing each finding in a separate task or CI/CD

12job. Keeping each fix scoped makes the code changes and evidence easier to

13review.

15## Fix a finding in the UI

17Open an accepted finding in the findings workspace to generate, review, apply,

18and verify its patch.

20<WorkflowSteps variant="headings">

221. Generate a focused patch

24 Open the finding, select the **Patch** tab, and select **Generate patch**.

25 Codex validates or reproduces the issue when feasible and writes a patch

26 artifact without modifying the selected checkout.

282. Review the proposed diff

30 Read every changed source and regression-test file. Use **Open diff in

31 editor** when you want the full patch in the editor. Reject broad refactors,

32 unrelated cleanup, or changes that weaken another security control.

343. Apply the patch locally

36 Select **Apply patch locally** only after the diff is acceptable. Codex

37 applies the exact generated patch to the working tree and records that state.

38 Review the working-tree diff before continuing.

404. Verify the fix

42 Select **Verify fix**. Codex reruns the original reproducer or strongest

43 available exploit check, focused regression coverage, legitimate-behavior

44 checks, nearby bypass checks, and relevant repository tests.

465. Close the finding deliberately

48 Verification doesn't automatically close a finding. Review the commands,

49 results, and remaining proof gap, then close the finding with an accurate

50 reason or keep it open for more work.

52</WorkflowSteps>

54<figure className="not-prose my-8">

55 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

56 <img

57 src={fixFindingPatch.src}

58 alt="Codex Security proposed patch for an accepted finding"

59 className="block h-auto w-full"

60 />

61 </div>

62 <figcaption className="mt-3 text-sm text-secondary">

63 Review the proposed source and test changes before applying the patch

64 locally.

65 </figcaption>

66</figure>

68## Fix a finding from the CLI

70Use the Codex CLI when you already have a finding from a scan, ticket, advisory,

71disclosure, security assessment, or internal review:

73```text

74Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, add focused regression coverage, and verify that the issue no longer reproduces.

75```

77Include the known source, sink, attacker input, impact, expected invariant,

78reproducer, affected files, and validation command. Codex can inspect the

79repository for missing technical details, but it should ask before guessing a

80product policy or intended security invariant.

82For an automated run, pass the prompt to `codex exec` after checking out the code

83and making the finding report available:

85```bash

86codex exec 'Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, add focused regression coverage, and verify that the issue no longer reproduces.'

87```

89## Scan and fix findings in CI/CD

91In CI/CD, use one Codex run to scan the diff and generate fixes for every

92finding it discovers. The job doesn't need finding IDs or report paths as

93inputs. Codex carries the findings from the scan into remediation within the

94same run.

96The all-in-one run should:

981. Resolve the base and head revisions for the change.

992. Run `$codex-security:security-diff-scan` against that diff.

1003. Invoke `$codex-security:fix-finding` for every finding returned by the scan.

1014. Generate focused patches and regression coverage, then verify each fix.

1025. Return the scan results, patches, tests, verification commands, and any

103 finding it couldn't fix.

104

105For example:

106

107```bash

108codex exec 'Use $codex-security:security-diff-scan to review changes from <base-revision> to HEAD. For every finding returned by the scan, use $codex-security:fix-finding to generate and verify a minimal fix. Continue until every finding has either a verified fix or an explicit explanation of why it could not be fixed. Return the scan results, patches, tests, verification commands, and remaining failures.'

109```

110

111After verification, merge the patch through your normal code-review and release

112process. To hand findings to another team before remediation, see [Export or

113track findings](https://developers.openai.com/codex/security/plugin/export-findings).

security/plugin/scans.md +126 −0 created

Details

1# Run a Codex Security scan

3Use a Codex Security scan for your first review and for most routine repository

4or component assessments. It runs the complete scan workflow once.

6Once you're satisfied with the results, run a [deep scan](https://developers.openai.com/codex/security/plugin/deep-scans)

7for a more comprehensive assessment. Deep scans take longer, but they're more

8thorough.

10## Choose the scan area

12Scan the whole repository when you need broad coverage and the repository is a

13reasonable review unit:

15```text

16Use $codex-security:security-scan to scan this repository for security vulnerabilities.

17```

19Scan a folder when a monorepo is too large or one service, package, or component

20has a clear owner and security boundary:

22```text

23Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.

24```

26For a large monorepo, start with one meaningful product or service boundary.

28## Configure the scan

30<WorkflowSteps>

321. Confirm **Scan type** is `Codebase` and leave **Deep scan** off.

332. Confirm the **Codebase**, **Current branch**, and **Last commit**.

343. Set **Scan area** to `Entire codebase` or enter one repository-relative

35 folder.

364. Add threat-model guidance only when it changes the review. Useful guidance

37 names attacker-controlled inputs, trust boundaries, sensitive actions, or a

38 specific area to prioritize.

395. Select **Start scan**.

41</WorkflowSteps>

43Repository-specific guidance in `AGENTS.md` can also establish the product

44surfaces, trust boundaries, supported validation commands, and out-of-scope

45areas. Prefer concrete repository context over a generic planning step before

46the scan.

48## Let the phases complete

50A scan runs these phases in order:

521. **Threat modeling** identifies assets, entry points, trust boundaries, and

53 security invariants.

542. **Finding discovery** reviews the requested code for plausible broken

55 controls and source-to-sink paths.

563. **Validation** tests or otherwise checks each candidate and records evidence

57 or proof gaps.

584. **Attack-path analysis** evaluates realistic reachability, impact, and

59 severity.

605. **Finalization** validates the structured scan contract and generates

61 `report.md`.

63Codex reports phase and coverage progress as the scan runs. Don't judge the

64result from early candidates or stop the scan because one phase takes longer

65than another.

67## Review the completed scan

69Review the result in this order:

711. Confirm the target, revision, and scan area.

722. Read reviewed surfaces and every explicit deferred or follow-up area.

733. For each finding, inspect the root control or sink, attacker-controlled

74 input, validation method, remaining uncertainty, realistic reachability,

75 severity rationale, and proposed remediation.

764. Dismiss findings whose evidence doesn't support the claimed path or impact.

775. Select one accepted finding before starting a fix.

79<div className="not-prose my-8 grid gap-6">

80 <figure>

81 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

82 <img

83 src={findingsWorkspace.src}

84 alt="Completed Codex Security findings workspace for OWASP Juice Shop"

85 className="block h-auto w-full"

86 />

87 </div>

88 <figcaption className="mt-3 text-sm text-secondary">

89 The completed workspace summarizes scan status, coverage, severity, and

90 artifacts before listing the findings.

91 </figcaption>

92 </figure>

94 <figure>

95 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">

96 <img

97 src={findingAttackPath.src}

98 alt="Codex Security finding evidence and attack-path analysis for OWASP Juice Shop"

99 className="block h-auto w-full"

100 />

101 </div>

102 <figcaption className="mt-3 text-sm text-secondary">

103 A finding connects the relevant source to its entry point, reachability,

104 likelihood, impact, and any limits or counterevidence.

105 </figcaption>

106 </figure>

107</div>

108

109## Use the results

110

111Use the findings workspace for normal review. It presents findings, coverage,

112and follow-up areas without requiring you to inspect raw JSON. Open `report.md`

113when you need a complete portable review for sharing or archiving.

114

115Behind the workspace, each scan preserves `scan-manifest.json`, `findings.json`,

116and `coverage.json` for automation and integrations. You normally don't need to

117open these files yourself.

118

119The findings workspace can also create portable JSON, CSV, and SARIF files. See

120[Export or track findings](https://developers.openai.com/codex/security/plugin/export-findings).

121

122## Next step

123

124After a person accepts a finding, use [Fix and verify a finding](https://developers.openai.com/codex/security/plugin/fix-findings)

125to generate and review one bounded patch. Don't ask Codex to fix every finding

126from a scan in one task.

security/plugin/triage-backlog.md +160 −0 created

Details

1# Triage a backlog

3Use `$codex-security:triage-finding` to review existing security findings

4against the current repository. This workflow performs a read-only static

5analysis: Codex treats each finding as an unproven claim and inspects repository

6evidence without executing the code.

8Run this workflow from a Codex project scoped to the repository you want to

9assess. Codex must be able to read the repository's source code. Jira, Linear,

10and GitHub connectors provide finding data, but they don't replace access to

11the source code.

13Under the hood, Codex starts from the cited code or version information. It

14traces the claimed attacker-controlled source, relevant security controls,

15dangerous sink, and reachable path. It also checks the product surface and trust

16boundary, looks for counterevidence, and records proof gaps. Codex then returns

17one verdict per finding and ranks the findings that need action or further

18review.

20This differs from `$codex-security:validation`, which can build or run code,

21create a focused test or proof of concept, or exercise a real interface to

22reproduce or disprove a finding. Use triage to classify and prioritize an

23existing backlog. Use validation when runtime evidence could resolve a finding

24that static evidence leaves uncertain.

26Backlog triage starts from existing findings. To search the repository for new

27 vulnerabilities, [run a security scan](https://developers.openai.com/codex/security/plugin/scans). Triage

28 doesn't modify the repository or implement fixes.

30## Choose the findings to triage

32You can supply one finding or a collection from these sources:

34| Source | What to provide | Requirements |

35| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

36| Pasted or local findings | SARIF results, a CVE or GHSA, an advisory, a scanner ticket, a bug bounty report, a Codex Security finding artifact, or a plain-language vulnerability claim. | No connector required. |

37| Jira or Linear | Exact security or vulnerability issue URLs or identifiers, Jira JQL, or a Linear team, project, or search phrase. Codex retrieves the selected issue content before triage. | [Jira through Atlassian Rovo](codex://plugins/plugin_connector_692de805e3ec8191834719067174a384) or [Linear](codex://plugins/plugin_asdk_app_69a089a326dc8191b32a3f2553f5be2c) with read access. |

38| GitHub | A repository and one finding source: code scanning, `Dependabot` vulnerabilities and malware, security advisories and private vulnerability reports, or all sources. If you don't specify a repository, Codex uses the GitHub repository attached to the current Codex project when available. GitHub Issues aren't included in the default GitHub sources; provide a specific issue or ask for GitHub Issues explicitly when you want to triage them. | [GitHub](codex://plugins/plugin_connector_1p_1a69035c238881919c4190932b2df699) with access to the selected repository and finding type. |

40Codex keeps one result for every supplied finding, in input order, so each

41source finding stays traceable. It doesn't merge or drop findings that look

42like duplicates.

44## Run read-only triage

46For pasted findings or local artifacts, send a prompt like:

48```text

49Use $codex-security:triage-finding to triage these existing security findings against this repository:

51[Paste the findings or provide the artifact path.]

52```

54For Jira or Linear issues, identify the issue set and keep the source system

55read-only:

57```text

58Use $codex-security:triage-finding to import and triage the security findings from [Jira or Linear issue URLs, identifiers, or query] against this repository.

59Do not change the source issues.

60```

62For GitHub findings, name the repository and source:

64```text

65Use $codex-security:triage-finding to import and triage [code scanning, Dependabot vulnerabilities and malware, security advisories and private vulnerability reports, or all] from [owner/repository] against this repository.

66```

68To use the GitHub repository attached to the current Codex project, specify

69only the finding source:

71```text

72Use $codex-security:triage-finding to import and triage [code scanning, Dependabot vulnerabilities and malware, security advisories and private vulnerability reports, or all] from GitHub against this repository. Use the GitHub repository attached to the current Codex project.

73```

75The workflow proceeds in this order:

77<WorkflowSteps variant="headings">

791. Collect and organize the findings

81 Codex retrieves any requested issue or GitHub content, preserves source

82 identifiers and references, and creates one triage item per input. It builds

83 the complete item list before assigning verdicts.

852. Confirm the repository context

87 Codex resolves the current repository and revision when available. It reads

88 `SECURITY.md` when present so supported versions, trusted inputs, product

89 boundaries, and out-of-scope surfaces inform the assessment.

913. Inspect the static evidence

93 For each finding, Codex traces the claimed attacker-controlled source,

94 relevant security control, vulnerable sink, reachable path, and supported

95 security boundary. It records supporting evidence, evidence against the

96 claim, and proof gaps.

984. Assign verdicts and ranks

100 Codex assigns a verdict and confidence to every finding. It ranks

101 `confirmed` and `needs_review` findings by exploitability in separate queues.

102

103</WorkflowSteps>

104

105## Review the results

106

107| Verdict | What it means |

108| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

109| `confirmed` | Repository evidence shows that the vulnerable path is reachable under the stated preconditions and crosses a supported security boundary. |

110| `not_actionable` | Repository evidence rules out the claim, such as by showing an unaffected version, unreachable path, effective guard, or non-shipped surface. |

111| `needs_review` | Repository evidence isn't enough to decide because required information is missing, ambiguous, runtime-dependent, environment-dependent, or policy-dependent. |

112

113Exploitability ranks use `P0`, `P1`, `P2`, and so on, independently within

114 each verdict queue. This keeps remediation priorities separate from unresolved

115 review work. `P0` is the most exploitable `confirmed` finding or the

116 highest-priority `needs_review` finding in that result set. The rank isn't a

117 scanner severity score, and `not_actionable` findings aren't ranked.

118

119For each finding, review:

120

121- the rationale for the verdict and rank

122- supporting evidence and evidence against the claim

123- open questions and remaining proof gaps

124- the affected location and component

125- the product surface and source trust level

126- the recommended next step

127- the [`$codex-security:fix-finding`](https://developers.openai.com/codex/security/plugin/fix-findings)

128 handoff, when the finding is `confirmed`

129

130Triage is complete when every supplied finding has one result, Codex preserves

131its source identifier, and any uncertainty is explicit. Jira, Linear, and other

132backlog records remain unchanged unless you ask Codex to write back after

133reviewing the triage results.

134

135## Next steps

136

137- `confirmed`: After a person accepts the finding for remediation, use

138 [`$codex-security:fix-finding`](https://developers.openai.com/codex/security/plugin/fix-findings) to fix and

139 verify it. Triage prepares a prompt-ready handoff but doesn't invoke the skill

140 automatically.

141- `needs_review`: If running code can resolve the proof gap, use

142 `$codex-security:validation` to perform bounded dynamic validation. Pass

143 the finding claim, affected locations, preconditions, static evidence, and

144 proof gaps from the triage result:

145

146 ```text

147 Use $codex-security:validation to dynamically validate finding [triage item ID or source ID] from the backlog triage result. Use the strongest realistic, bounded method, record exactly what was tested, and preserve any remaining proof gaps.

148 ```

149

150 Unlike triage, validation may build or run code, create a focused test or

151 proof of concept, or exercise a real interface. Review the proposed commands

152 before approving them and keep [Codex approval and security

153 policies](https://developers.openai.com/codex/agent-approvals-security) in place.

154

155- `needs_review`: If the finding depends on product policy or deployment

156 context, answer the listed open questions before changing code.

157- `not_actionable`: Keep the evidence with your triage record. Codex doesn't

158 automatically close or update the source ticket.

159- To look for vulnerabilities beyond the supplied backlog, [run a security

160 scan](https://developers.openai.com/codex/security/plugin/scans).

skills.md +61 −28

Details

~~1# Agent Skills – Codex~~1# Agent Skills

2 2

3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).

4 4

6 6

7Skills are available in the Codex CLI, IDE extension, and Codex app.7Skills are available in the Codex CLI, IDE extension, and Codex app.

8 8

9Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill’s name, description, and file path. Codex loads the full `SKILL.md` instructions only when it decides to use a skill.9Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill's name, description, and file path. Codex loads the full `SKILL.md` instructions only when it decides to use a skill.

10 10

11Codex includes an initial list of available skills in context so it can choose the right skill for a task. To avoid crowding out the rest of the prompt, this list is capped at roughly 2% of the model’s context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens skill descriptions first. For very large skill sets, some skills may be omitted from the initial list, and Codex will show a warning.11Codex includes an initial list of available skills in context so it can choose the right skill for a task. To avoid crowding out the rest of the prompt, this list uses at most 2% of the model’s context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens skill descriptions first. For large skill sets, Codex may omit some skills from the initial list and show a warning.

12 12

13This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.13This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.

14 14

15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.

16 16

~~17- my-skill/~~17<FileTree

18 18 class="mt-4"

~~19 - SKILL.md Required: instructions + metadata~~19 tree={[

~~20 - scripts/ Optional: executable code~~20 {

~~21 - references/ Optional: documentation~~21 name: "my-skill/",

~~22 - assets/ Optional: templates, resources~~22 open: true,

~~23 - agents/~~23 children: [

24 24 {

~~25 - openai.yaml Optional: appearance and dependencies~~25 name: "SKILL.md",

26 comment: "Required: instructions + metadata",

27 },

28 {

29 name: "scripts/",

30 comment: "Optional: executable code",

31 },

32 {

33 name: "references/",

34 comment: "Optional: documentation",

35 },

36 {

37 name: "assets/",

38 comment: "Optional: templates, resources",

39 },

40 {

41 name: "agents/",

42 open: true,

43 children: [

44 {

45 name: "openai.yaml",

46 comment: "Optional: appearance and dependencies",

47 },

48 ],

49 },

50 ],

51 },

53]}

54/>

26 55

27## How Codex uses skills56## How Codex uses skills

28 57

35 64

36## Create a skill65## Create a skill

37 66

~~38Use the built-in creator first:~~67If you already know the workflow and it's easier to show than describe, use

68[Record & Replay](https://developers.openai.com/codex/record-and-replay). Codex records the workflow,

69inspects the steps, and drafts a reusable skill from the demonstration.

39 70

~~40```~~71If you want to describe the skill instead, use the built-in creator:

73```text

41$skill-creator74$skill-creator

42```75```

43 76

45 78

46You can also create a skill manually by creating a folder with a `SKILL.md` file:79You can also create a skill manually by creating a folder with a `SKILL.md` file:

47 80

~~48```~~81```md

49---82---

50name: skill-name83name: skill-name

51description: Explain exactly when this skill should and should not trigger.84description: Explain exactly when this skill should and should not trigger.

54Skill instructions for Codex to follow.87Skill instructions for Codex to follow.

55```88```

56 89

~~57Codex detects skill changes automatically. If an update doesn’t appear, restart Codex.~~90Codex detects skill changes automatically. If an update doesn't appear, restart Codex.

58 91

59## Where to save skills92## Where to save skills

60 93

61Codex reads skills from repository, user, admin, and system locations. For repositories, Codex scans `.agents/skills` in every directory from your current working directory up to the repository root. If two skills share the same `name`, Codex doesn’t merge them; both can appear in skill selectors.94Codex reads skills from repository, user, admin, and system locations. For repositories, Codex scans `.agents/skills` in every directory from your current working directory up to the repository root. If two skills share the same `name`, Codex doesn't merge them; both can appear in skill selectors.

62 95

~~64| --- | --- | --- |~~97| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

65| `REPO` | `$CWD/.agents/skills` Current working directory: where you launch Codex. | If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module. |98| `REPO` | `$CWD/.agents/skills` <br /> Current working directory: where you launch Codex. | If you're in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module. |

66| `REPO` | `$CWD/../.agents/skills` A folder above CWD when you launch Codex inside a Git repository. | If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder. |99| `REPO` | `$CWD/../.agents/skills` <br /> A folder above CWD when you launch Codex inside a Git repository. | If you're in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder. |

67| `REPO` | `$REPO_ROOT/.agents/skills` The topmost root folder when you launch Codex inside a Git repository. | If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository. |100| `REPO` | `$REPO_ROOT/.agents/skills` <br /> The topmost root folder when you launch Codex inside a Git repository. | If you're in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository. |

~~68| `USER` | `$HOME/.agents/skills` Any skills checked into the user’s personal folder. | Use to curate skills relevant to a user that apply to any repository the user may work in. |~~101| `USER` | `$HOME/.agents/skills` <br /> Any skills checked into the user's personal folder. | Use to curate skills relevant to a user that apply to any repository the user may work in. |

69| `ADMIN` | `/etc/codex/skills` Any skills checked into the machine or container in a shared, system location. | Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine. |102| `ADMIN` | `/etc/codex/skills` <br /> Any skills checked into the machine or container in a shared, system location. | Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine. |

70| `SYSTEM` | Bundled with Codex by OpenAI. | Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex. |103| `SYSTEM` | Bundled with Codex by OpenAI. | Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex. |

71 104

72Codex supports symlinked skill folders and follows the symlink target when scanning these locations.105Codex supports symlinked skill folders and follows the symlink target when scanning these locations.

90 123

91To add curated skills beyond the built-ins for your own local Codex setup, use `$skill-installer`. For example, to install the `$linear` skill:124To add curated skills beyond the built-ins for your own local Codex setup, use `$skill-installer`. For example, to install the `$linear` skill:

92 125

~~93```~~126```bash

94$skill-installer linear127$skill-installer linear

95```128```

96 129

97You can also prompt the installer to download skills from other repositories.130You can also prompt the installer to download skills from other repositories.

~~98Codex detects newly installed skills automatically; if one doesn’t appear,~~131Codex detects newly installed skills automatically; if one doesn't appear,

99restart Codex.132restart Codex.

100 133

101Use this for local setup and experimentation. For reusable distribution of your134Use this for local setup and experimentation. For reusable distribution of your

105 138

106Use `[[skills.config]]` entries in `~/.codex/config.toml` to disable a skill without deleting it:139Use `[[skills.config]]` entries in `~/.codex/config.toml` to disable a skill without deleting it:

107 140

108```141```toml

109[[skills.config]]142[[skills.config]]

110path = "/path/to/skill/SKILL.md"143path = "/path/to/skill/SKILL.md"

111enabled = false144enabled = false

117 150

118Add `agents/openai.yaml` to configure UI metadata in the [Codex app](https://developers.openai.com/codex/app), to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill.151Add `agents/openai.yaml` to configure UI metadata in the [Codex app](https://developers.openai.com/codex/app), to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill.

119 152

120```153```yaml

121interface:154interface:

122 display_name: "Optional user-facing name"155 display_name: "Optional user-facing name"

123 short_description: "Optional user-facing description"156 short_description: "Optional user-facing description"

138 url: "https://developers.openai.com/mcp"171 url: "https://developers.openai.com/mcp"

139```172```

140 173

141`allow_implicit_invocation` (default: `true`): When `false`, Codex won’t implicitly invoke the skill based on user prompt; explicit `$skill` invocation still works.174`allow_implicit_invocation` (default: `true`): When `false`, Codex won't implicitly invoke the skill based on user prompt; explicit `$skill` invocation still works.

142 175

143## Best practices176## Best practices

144 177

use-cases/collections/security.md +3 −2

Details

9 9

10## Assess a repository10## Assess a repository

11 11

~~12Use the Codex Security plugin to run a higher-recall scan across an authorized~~12Use the Codex Security plugin to run a comprehensive scan across an authorized

13repository, review plausible findings, and produce reports that support human13repository, review plausible findings, and produce reports that support human

~~14triage.~~14triage. Comprehensive scans take longer because they repeat discovery across

15independent workers.

15 16

16- https://developers.openai.com/codex/use-cases/deep-security-scan17- https://developers.openai.com/codex/use-cases/deep-security-scan

17 18

use-cases/deep-security-scan.md +33 −31

Details

1---1---

2name: Run a deep security scan2name: Run a deep security scan

3tagline: Search an authorized repository deeply for plausible vulnerabilities.3tagline: Search an authorized repository deeply for plausible vulnerabilities.

~~4summary: Use the Codex Security plugin to run a higher-recall, repository-wide~~4summary: Use the Codex Security plugin to run a more comprehensive audit of a

~~5 audit that repeats discovery, validates candidates, and produces reviewable~~5 repository or scoped folder that repeats discovery, validates candidates, and

~~6 report artifacts.~~6 produces reviewable coverage and findings.

7skills:7skills:

8 - token: $codex-security:deep-security-scan8 - token: $codex-security:deep-security-scan

~~9 url: /codex/security/plugin~~9 url: /codex/security/plugin/deep-scans

~~10 description: Run repeated repository-wide security discovery passes, validate~~10 description: Run repeated discovery passes over a repository or scoped folder,

~~11 surviving findings, analyze attack paths, and create reviewable reports.~~11 validate surviving findings, analyze attack paths, and generate reviewable

12 artifacts.

12bestFor:13bestFor:

~~13 - Application security reviews of a complete repository that you own or are~~14 - Application security reviews of a repository or component that you own or

~~14 authorized to assess.~~15 are authorized to assess.

~~15 - High-recall reviews where additional runtime and token use are appropriate~~16 - More comprehensive reviews where additional runtime and token use are

~~16 for finding more candidate issues.~~17 appropriate for finding more candidate issues.

17 - Security teams that need traceable finding evidence before deciding what to18 - Security teams that need traceable finding evidence before deciding what to

18 remediate.19 remediate.

19starterPrompt:20starterPrompt:

20 title: Run a Deep Security Scan21 title: Run a Deep Security Scan

21 body: >-22 body: >-

~~22 /goal Run a deep security scan on this repository. Do not stop until all~~23 Use $codex-security:deep-security-scan to run a deep security scan on [this

~~23 required steps are complete and the final report is ready.~~24 repository / absolute path to a scoped folder].

24 25

25 26

26 Scope and rules:27 Scope and rules:

27 28

28 - I am authorized to assess this repository.29 - I am authorized to assess this repository.

29 30

~~30 - Treat the entire repository as in scope.~~31 - Keep the scan within [the entire repository / the exact folder named

32 above].

31 33

~~32 - Use the Codex Security plugin's deep scan workflow; do not broaden this~~34 - Use the Codex Security plugin's deep-scan workflow; do not reinterpret

~~33 into a diff or scoped-path review.~~35 this as a pull request or diff review.

34 36

~~35 - Keep the scan read-only; do not modify code, open pull requests, or test~~

~~36 external targets.~~

37 37

38 38 Return the generated report path. Summarize the findings, reviewed surfaces,

~~39 Return the final Markdown and HTML report paths and summarize the findings~~39 and proof gaps that require human review first.

~~40 that require human review first.~~

41 suggestedEffort: high40 suggestedEffort: high

42relatedLinks:41relatedLinks:

~~43 - label: Codex Security plugin~~42 - label: Deep-scan guide

~~44 url: /codex/security/plugin~~43 url: /codex/security/plugin/deep-scans

45 - label: Agent approvals and security44 - label: Agent approvals and security

46 url: /codex/agent-approvals-security45 url: /codex/agent-approvals-security

47 - label: Codex cyber safety46 - label: Codex cyber safety

50 49

51## Choose a deep repository review50## Choose a deep repository review

52 51

~~53Use a deep scan when you need high-recall vulnerability discovery across a~~52Use a deep scan when you need a more comprehensive vulnerability review across

~~54complete repository and can budget for a longer run. The Codex Security plugin~~53a repository or explicit folder and can budget for a longer run. The Codex

~~55repeats discovery passes before validating and prioritizing findings, so this~~54Security plugin repeats discovery passes before validating and prioritizing

~~56workflow takes more time and tokens than an ordinary scan.~~55findings, so this workflow takes more time and resources than an ordinary scan.

57 56

~~58A deep scan is for an entire repository. To review one package or directory,~~57A deep scan can review an entire repository or one explicitly named package or

~~59use `$codex-security:security-scan`. To review a pull request, commit, branch~~58directory. To review a pull request, commit, branch diff, or working-tree patch,

~~60diff, or working-tree patch, use~~59use

61[$codex-security:security-diff-scan](https://developers.openai.com/codex/use-cases/scan-code-changes-for-security).60[$codex-security:security-diff-scan](https://developers.openai.com/codex/use-cases/scan-code-changes-for-security).

62 61

63## Prepare an authorized scan62## Prepare an authorized scan

64 63

65 64

66 65

~~671. Open the repository in Codex and install the [Codex Security plugin](https://developers.openai.com/codex/security/plugin).~~661. Open the repository in Codex and complete the [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin).

682. Confirm that you own the repository or have authorization to assess it.672. Confirm that you own the repository or have authorization to assess it.

693. Add repository-specific architecture, trust-boundary, build, test, and validation guidance in `AGENTS.md` when it will improve the review.683. Add repository-specific architecture, trust-boundary, build, test, and validation guidance in `AGENTS.md` when it will improve the review.

704. Run the starter prompt and let the scan complete its repeated discovery, validation, attack-path analysis, and final reporting stages.694. Run the starter prompt and let the scan complete its repeated discovery, validation, attack-path analysis, and final reporting stages.

~~715. Review the final reports before asking Codex to change code or reproduce a finding further.~~705. Review the findings workspace and any proof gaps before asking Codex to change code or reproduce a finding further.

72 71

73 72

74 73

82Start remediation only for a finding you have selected and reviewed. Use81Start remediation only for a finding you have selected and reviewed. Use

83[Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)82[Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)

84to fix findings one at a time with focused regression validation.83to fix findings one at a time with focused regression validation.

85For setup, preflight, scoped targets, and runtime expectations, see [Run a deep

86security scan](https://developers.openai.com/codex/security/plugin/deep-scans).

use-cases/remediate-vulnerability-backlog.md +6 −3

Details

6 them one at a time with bounded patches and regression evidence.6 them one at a time with bounded patches and regression evidence.

7skills:7skills:

8 - token: $codex-security:fix-finding8 - token: $codex-security:fix-finding

~~9 url: /codex/security/plugin~~9 url: /codex/security/plugin/fix-findings

10 description: Fix and verify one validated or plausible security finding with10 description: Fix and verify one validated or plausible security finding with

11 focused tests or reproduction evidence.11 focused tests or reproduction evidence.

12bestFor:12bestFor:

64 change code.64 change code.

65 suggestedEffort: high65 suggestedEffort: high

66relatedLinks:66relatedLinks:

~~67 - label: Codex Security plugin~~67 - label: Fix-finding guide

~~68 url: /codex/security/plugin~~68 url: /codex/security/plugin/fix-findings

69 - label: Run a deep security scan69 - label: Run a deep security scan

70 url: /codex/use-cases/deep-security-scan70 url: /codex/use-cases/deep-security-scan

71 - label: Scan code changes for security71 - label: Scan code changes for security

104reference; the exact code change; the checks run; and any proof gap. If Codex104reference; the exact code change; the checks run; and any proof gap. If Codex

105finds that the issue is already fixed or it can't reproduce it, record that105finds that the issue is already fixed or it can't reproduce it, record that

106evidence instead of forcing an unnecessary code change.106evidence instead of forcing an unnecessary code change.

107

108For the findings workspace and prompt-driven remediation paths, see [Fix and

109verify security findings](https://developers.openai.com/codex/security/plugin/fix-findings).

use-cases/scan-code-changes-for-security.md +9 −9

Details

6 before merge.6 before merge.

7skills:7skills:

8 - token: $codex-security:security-diff-scan8 - token: $codex-security:security-diff-scan

~~9 url: /codex/security/plugin~~9 url: /codex/security/plugin/code-changes

10 description: Review a pull request, commit, branch diff, or working-tree patch10 description: Review a pull request, commit, branch diff, or working-tree patch

11 for security regressions with validation and attack-path evidence.11 for security regressions with validation and attack-path evidence.

12bestFor:12bestFor:

19starterPrompt:19starterPrompt:

20 title: Review a Change for Security Regressions20 title: Review a Change for Security Regressions

21 body: >-21 body: >-

~~22 /goal Scan this PR, commit, branch diff, or working-tree patch for security~~22 Use $codex-security:security-diff-scan to review this PR, commit, branch

~~23 regressions. Do not stop until all in-scope changed files are covered and~~23 diff, or working-tree patch for security regressions.

~~24 all required steps are complete.~~

25 24

26 25

27 Scope and rules:26 Scope and rules:

34 - Pay particular attention to [auth, input handling, secrets, filesystem,33 - Pay particular attention to [auth, input handling, secrets, filesystem,

35 network, dependencies, or other sensitive surface].34 network, dependencies, or other sensitive surface].

36 35

~~37 - Keep this pass read-only; do not modify code or open a pull request.~~

39 36

40 Return the final Markdown report and any Codex app review directives for37 Return the final Markdown report and any Codex app review directives for

41 findings that require human review.38 findings that require human review.

42 suggestedEffort: high39 suggestedEffort: high

43relatedLinks:40relatedLinks:

~~44 - label: Codex Security plugin~~41 - label: Security change-review guide

~~45 url: /codex/security/plugin~~42 url: /codex/security/plugin/code-changes

46 - label: Review GitHub pull requests43 - label: Review GitHub pull requests

47 url: /codex/use-cases/github-code-reviews44 url: /codex/use-cases/github-code-reviews

48 - label: Agent approvals and security45 - label: Agent approvals and security

64 61

65 62

661. Open the repository and check out or describe the exact Git-backed change set to review.631. Open the repository and check out or describe the exact Git-backed change set to review.

~~672. Install the [Codex Security plugin](https://developers.openai.com/codex/security/plugin) and specify the pull request, commit, branch diff, or working-tree patch in the starter prompt.~~642. Complete the [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin) and specify the pull request, commit, branch diff, or working-tree patch in the starter prompt.

683. Name high-risk surfaces in the change, such as authentication, parsers, file paths, network requests, or credential handling.653. Name high-risk surfaces in the change, such as authentication, parsers, file paths, network requests, or credential handling.

694. Run the prompt without requesting a fix so the first result remains a review artifact.664. Run the prompt without requesting a fix so the first result remains a review artifact.

705. Check each reported affected line, validation result, and stated proof gap before deciding whether to remediate.675. Check each reported affected line, validation result, and stated proof gap before deciding whether to remediate.

79fix task with the finding identifier or the relevant report section.76fix task with the finding identifier or the relevant report section.

80See [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)77See [Remediate a vulnerability backlog](https://developers.openai.com/codex/use-cases/remediate-vulnerability-backlog)

81for the fix-and-validation loop.78for the fix-and-validation loop.

80For change selectors, diff scope, and result review, see [Review code changes

81for security](https://developers.openai.com/codex/security/plugin/code-changes).

Documentation 2026-06-17 17:02 UTC to 2026-06-18 23:01 UTC