Codex IDE Extension skill for Codex
Hand Codex the code you are already looking at. Codex uses the editor deliberately: it pulls the exact selection or file into the chat, checkpoints git before and after edits, routes long work to a worktree or cloud environment, reviews diffs in place with /review, and keeps chatgpt.* editor settings separate from the shared config.toml so the IDE and CLI behave consistently.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- codex-ide-extensionInstalls to ~/.agents/skills/codex-ide-extension/ for every project on this machine.
curl -fsSL codexskills.dev/cli.mjs -o codex-skills.mjsnode codex-skills.mjs install codex-ide-extensionThe CLI also searches, updates and removes skills. Run it with no arguments to pick from a list. Needs Node 20.12+.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- --project codex-ide-extensionInstalls to .agents/skills/codex-ide-extension/ in the current repository. Commit it and everyone who runs Codex there gets it.
curl -fsSLO codexskills.dev/downloads/codex-ide-extension.zipunzip -o codex-ide-extension.zip -d ~/.agents/skills/The archive holds the skill folder with its generated agents/openai.yaml. Unzip into .agents/skills/ to scope it to a repo.
& ([scriptblock]::Create((irm codexskills.dev/install.ps1))) codex-ide-extensionPowerShell 5.1 or 7. Installs to %USERPROFILE%\.agents\skills\. Add -Project for the current repo.
104-line POSIX script. No sudo, no telemetry. Read install.sh
Use it in Codex
Start a prompt with $codex-ide-extension, or pick it from /skills.
You can also just describe the task: Codex reads the description below and loads the playbook when your request matches.
What Codex reads before loading it
Works effectively with the Codex IDE extension in VS Code, Cursor and Windsurf (and Codex in JetBrains and Xcode), covering editor context (selections, open files, /ide-context, Add to Codex Thread), local versus cloud and worktree runs, in-editor diff review, /review, chatgpt.* editor settings, shared config.toml, WSL on Windows and keybindings. Use when the user works with Codex inside an editor, asks how to give Codex the code they are looking at, review its edits in place, delegate from the IDE to the cloud, or fix extension settings.
Use it when
- Working with Codex inside VS Code, Cursor, Windsurf, JetBrains or Xcode
- You want Codex to use the current selection or open files as context
- Reviewing Codex edits in the editor before committing
- Configuring chatgpt.* extension settings or WSL mode on Windows
Use something else when
- You need terminal-only, scripted runs: use codex-exec-ci
- Setting up parallel checkouts for several agents: use codex-parallel-worktrees
How to check the result
/status in the editor shows the expected model and context use, the selection appears as context before sending, and the resulting diff stays within the files the prompt named.
The mistake it prevents
Opening a parent folder that holds several repositories, so Codex finds no project root and never loads each repo's AGENTS.md.
IDE work is done well when Codex gets exactly the code the developer is looking at, edits land as small reviewable diffs with a git checkpoint on each side, and longer work is moved to a worktree or the cloud instead of blocking the editor.
Setup checklist
- [ ] Extension installed: VS Code, Cursor, Windsurf, VS Code Insiders use openai.chatgpt
- [ ] Signed in (ChatGPT account or API key) and the correct workspace selected
- [ ] Workspace folder is inside the git repo (not a parent folder holding many repos)
- [ ] Project trusted, otherwise project .codex/config.toml, hooks and rules are skipped
- [ ] Windows: repos in WSL2 -> chatgpt.runCodexInWindowsSubsystemForLinux = true
- [ ] Git working tree clean before the first taskJetBrains IDEs: open AI Chat and select Codex. Xcode: open the coding assistant, start a chat and choose Codex. The rest of this skill describes the VS Code-family extension.
Two settings layers
| Layer | Where | Controls |
|---|---|---|
| Codex settings | ~/.codex/config.toml plus trusted project .codex/config.toml (gear icon > Codex Settings > Open config.toml) | Model, reasoning effort, sandbox, approvals, MCP servers; shared with the CLI |
| Editor settings | VS Code settings, keys chatgpt.* | Extension behaviour inside the editor |
Useful editor settings:
| Key | Default | Use |
|---|---|---|
chatgpt.followUpQueueMode | queue | steer sends mid-run messages into the current run; Cmd/Ctrl+Shift+Enter inverts once |
chatgpt.composerEnterBehavior | enter | cmdIfMultiline to stop accidental sends of long prompts |
chatgpt.reviewDelivery | inline | detached runs /review in a separate chat |
chatgpt.commentCodeLensEnabled | true | CodeLens above TODO comments that hands them to Codex |
chatgpt.openOnStartup | false | Focus the Codex sidebar on start |
chatgpt.runCodexInWindowsSubsystemForLinux | false | Run the agent in WSL2 (reloads the window) |
Leave chatgpt.cliExecutable unset unless you develop Codex itself.
To make citations in Codex output open in the right editor, set file_opener in
config.toml (vscode, vscode-insiders, windsurf, cursor or none).
Give Codex the right context
| Want Codex to see | Do |
|---|---|
| A specific function or block | Select it, run Add to Codex Thread (chatgpt.addToThread) |
| A whole file | chatgpt.addFileToThread, or reference it from the composer |
| Whatever is open and selected, automatically | Leave IDE context on; /ide-context toggles it |
| Nothing from the editor (avoid bias) | Turn IDE context off with /ide-context |
| Editor context from a terminal TUI session | /ide in the Codex CLI |
Prompt pattern for selection-based work:
Write unit tests for the selected function. Follow the conventions in the
nearest existing *.test.ts file. Cover the empty-input and timeout branches.
Run only this test file and report the result.Close unrelated tabs before a task when automatic context is on; open files are context too.
Workflow for an edit
- Checkpoint:
git statusclean, or commit/stash. - Choose where it runs:
/local(default),/worktree(separate checkout, keeps your editor tree untouched), or/cloudwith/cloud-environmentfor long jobs. - Prompt with the selection, the constraint and the done-criteria.
- Review the diff in the editor: read the summary, open each changed file, keep only the hunks you want.
- Run the project’s checks yourself or ask Codex to (
npm test,pytest -q). - Run
/reviewfor a second pass against uncommitted changes or a base branch. - Commit. Repeat with a new checkpoint for the next change.
Commands worth binding
Assign keys via Preferences: Open Keyboard Shortcuts, search the command id.
| Command id | Default | Action |
|---|---|---|
chatgpt.newChat | Cmd+N / Ctrl+N (in Codex) | New chat |
chatgpt.addToThread | none | Add selection to current chat |
chatgpt.addFileToThread | none | Add current file |
chatgpt.openSidebar | none | Open the Codex sidebar |
chatgpt.openCommandMenu | none | Codex command menu |
chatgpt.newCodexPanel | none | Extra Codex panel |
IDE slash commands include /model, /reasoning, /plan, /goal, /review,
/compact, /status (chat id, context use, rate limits), /fork, /side,
/worktree, /local, /cloud, /mcp, /init and /fast when the model offers it.
Delegating to the cloud
Plan locally with full editor context, then click the cloud icon under the composer (or
/cloud), pick an environment, and send the next prompt; the cloud chat carries the
conversation and local changes. Cloud agent phases are offline unless the environment
enables internet access. Pull the result locally to test before merging.
Gotchas
- Opening a parent folder that contains several repositories (no
.gitof its own) means Codex finds no project root: it readsAGENTS.mdonly from that folder and misses each repo’s instructions. Open the repository itself, or setproject_root_markersif the repo uses another VCS marker. - The extension and CLI share
config.toml; a profile or-cflag used in the terminal does not apply to editor chats. - Plugins are not available in the IDE extension; skills and MCP servers are.
- The review pane reflects git state, so it shows changes Codex did not make. Commit before delegating to see only Codex’s edits.
- In workspace-write,
.gitis read-only: Codex asks for approval to commit. Approve deliberately or commit yourself. - On Windows without WSL mode, the agent runs with native Windows sandbox semantics; repos living in WSL should use the WSL setting.
- Two chats editing the same files in the same window overwrite each other; use
/worktreefor the second one.
Verification
/statusin the IDE shows the expected model, context use and chat id.- Selected code appears in the chat context chip before sending.
- The final diff touches only the files the prompt allowed, and the project’s checks pass.
What the zip contains
SKILL.md plus the interface file below. Nothing runs on install.
agents/openai.yaml
Gives the Codex app a display name, a one-line description and a starter prompt for this skill.
interface:
display_name: "Codex IDE Extension"
short_description: "Hand Codex the code you are already looking at"
default_prompt: "$codex-ide-extension Write tests for the function I have selected in VS Code"About this skill
Written and maintained by the Codex Skills editors to the same editorial standard as every skill here: a selective description, a real workflow, known pitfalls and a way to verify the work. First published , last updated . MIT licensed. Something wrong or out of date? Tell us.