Codex Knowledge Patch

Codex Knowledge Patch

Use this skill when working with the Codex desktop app, CLI, TUI, remote app server, MCP integrations, cloud tasks, plugins, or collaborative agent workflows.

Reference index

Replace deprecated approval behavior

Choose among the supported untrusted, on-request, and never approval policies. on-failure is deprecated. --full-auto combines the workspace-write sandbox with on-request approvals. --yolo bypasses sandboxing and approval prompts, so reserve it for an externally isolated environment.

Read security-and-configuration.md before changing approval, sandbox, authentication, policy, or search settings.

Account for hosted Code Mode approvals

Since 0.144.0, Code Mode defaults to hosted mode. Every approval request causes an elicitation pause. The writes app-approval mode lets declared read-only app actions proceed without prompting but requires approval for writes.

Use interactive MCP authentication directly

Since 0.144.0, MCP tools may request interactive authentication without an experimental opt-in. App-server hosts may provide authentication at runtime, hosted login may redirect success to a hosted page, and long-running app sessions refresh expired authentication for the hosted codex_apps connector.

Read remote-mcp-and-connectors.md before configuring remote listeners, bearer tokens, MCP servers, connectors, or plugin authentication.

Expect image-generation routing

Since 0.144.0, image requests use the image-generation extension by default. Attach a reference with --image for edits, and quote the literal $imagegen name when invoking it from a shell:

codex --image existing.png '$imagegen Extend this asset'

The desktop image viewer also supports Focused and Canvas views, annotations, individual selection, and targeted follow-up edits.

Run scripted work with explicit output contracts

Use codex exec for non-interactive work. Pass a prompt as an argument or use - to read stdin:

printf '%s\n' 'Inventory package licenses' | \
  codex exec - --json --output-schema result.schema.json \
  --output-last-message final.txt

• --json emits JSONL state-change events.
• --output-schema constrains the final response with JSON Schema.
• --output-last-message writes the final natural-language response alone.
• --ephemeral avoids saving rollout files.
• --skip-git-repo-check permits execution outside a Git repository.

Resume the latest scripted session for the current directory with:

codex exec resume --last "Continue with the implementation"

Interactive and scripted resume retain transcript, plan history, and approvals. Use --all to include other directories; use fork when a new thread should retain the source transcript without continuing the same session.

Connect a remote TUI safely

Run the app server where the workspace lives and connect a TUI through an explicit ws:// or wss:// URL:

codex app-server --listen ws://127.0.0.1:4500
codex --remote ws://127.0.0.1:4500

For non-local use, put authenticated connections behind TLS. Capability-token authentication uses --ws-token-file on the server and --remote-auth-token-env on the client. Signed bearer authentication uses an HS256 JWT with an exp claim and a shared secret of at least 32 bytes. The client sends bearer tokens only over wss:// or loopback ws://.

Apply invocation and feature overrides correctly

Global options inherited by a subcommand go after the subcommand name. Repeatable -c key=value overrides parse JSON when possible and otherwise remain strings.

codex exec --profile work -c 'features.unified_exec=true' \
  --full-auto "Run the checks"

Use --cd to choose the working root without changing the parent shell, and repeat --add-dir for additional writable roots:

codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

Persist feature choices with codex features list, enable, and disable. Settings go to ~/.codex/config.toml or the selected profile. --search requests live web search for one run; web_search = "live" or "disabled" persists the choice.

Submit, inspect, and apply cloud work

codex cloud opens the task picker. Submit directly to an environment with one to four independent attempts:

codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs"
codex cloud list --env ENV_ID --limit 20 --json
codex apply TASK_ID

Submission failures exit nonzero. Listing supports cursor pagination, a limit from 1 through 20, and JSON containing a tasks array plus an optional cursor. Applying a task uses its latest diff, reports changed files, and exits nonzero on git apply conflicts.

Use the desktop collaboration boundary

Desktop projects share projects, session history, and configuration with the CLI and IDE extension. Built-in Git worktrees isolate parallel agent threads. In a multi-folder project, the primary folder controls new chats, Git operations, and automatic discovery of AGENTS.md, skills, and config.toml; secondary folders remain searchable, readable, and editable.

Automations combine instructions with optional skills and send scheduled results to a review queue. They require the local computer to remain open. Review aggregates repositories and changed lines across a multi-folder project.

Use interactive controls deliberately

• Press Enter during a turn to inject instructions; press Tab to queue a prompt, slash command, or ! command for the next turn.
• Use Ctrl+G for VISUAL/EDITOR, @ for workspace-file search, and an empty composer followed by Esc twice to edit and fork from prior prompts.
• Use /clear for a new conversation and cleared view, /new for a new conversation without clearing, and Ctrl+L to clear only the display.
• Use /copy or Ctrl+O for the latest completed output, /fork to clone the current transcript, and /agent to inspect or continue spawned threads.
• Use /plan [PROMPT] before a task starts and /fast on, /fast off, or /fast status for supported threads.
• With unified_exec, use /ps to inspect background commands and /stop to stop all background terminals for the session; /clean remains an alias.

Subagents are created only when explicitly requested. Configure roles under [agents] in config.toml, and account for the separate model and tool work performed by every spawned agent.

Read tui-and-session-controls.md for the complete interaction, appearance, status, terminal, and thread controls.