Using Codex in VS Code: Scope, Recovery Points and the Fixes for the Usual Stalls

Getting Codex running in VS Code takes a few minutes: install the official openai.chatgpt extension, sign in, open a project folder, switch to Agent mode and give it one narrowly scoped task that names the files involved. Every workspace change and test result needs a human look before it is kept. Longer jobs suit cloud delegation, and the problems that stall most people, namely repeated approvals, remote sign-in and a Windows WSL loading freeze, each have a specific fix covered below.

The scope here is the VS Code surface only: a first bounded task, then the controls that keep the agent predictable. Terminal installation, the Cursor plugin, usage dashboards and comparisons with other tools are separate subjects.

From suggestions to an agent that moves files

Plenty of developers are used to ghost text: a suggestion pops up as characters are typed, gets kept or ignored, and nothing else in the tree stirs. Agent mode in Codex is another animal. A side panel reads files, edits the working tree and runs checks while its user fetches a coffee. Mistaking one for the other makes the first Agent run feel like a break-in, though it is simply a different kind of work.

An analogy helps. A passenger who points at a road sign leaves both of the driver's hands on the wheel, and the car only moves because the driver moves it. Handing over the keys is another matter: come back from the kitchen and the car sits in a new parking space with a rearranged trunk and more miles on the clock, and nobody asked about the route. Inline autocomplete is the passenger pointing. Agent mode is the set of keys. Skipping a recovery point means lending write access to a repository that still holds an uncommitted afternoon of work.

What the current extension actually is

Today's Codex IDE extension acts as an asynchronous coding agent. It is a worker running in the background with permission to read the repository, rewrite files on disk and execute terminal commands, where autocomplete would only propose the next token. It has nothing to do with the 2021 Codex completion API or with Copilot's ghost text, and any tutorial describing it as a better tab key is talking about something else.

In Agent mode, work spreads across the repository and the terminal, which is why scope and recovery matter more than they ever did with autocomplete. A one-line suggestion stays in the editor until accepted. An agent task can land in src/ while the first paragraph of its plan is still being read.

Chat mode, when the composer offers it, is discussion only, with no file edits and no command execution. It suits a read of the problem. Agent is the choice for when the tree should actually move.

Scope, evidence and a way back

OpenAI's own IDE documentation and practical write-ups agree on one blunt fact about the interface: local Agent mode applies edits directly to the workspace directory. The extension does not present an inline accept-or-reject diff the way some other editors do. Git is the undo button, and without an initialised repository there is no clean way back.

Three things should happen before the first prompt:

1. Open a real project folder and not a single file.
2. Commit or stash anything that must not be lost. git stash push -u -m "pre-codex" is enough.
3. Put the acceptance check inside the prompt: which tests must pass, which file is in bounds and what "done" looks like.

A tidy prompt on an uncommitted tree is riskier than a sloppy prompt on a clean branch.

When things go wrong, the damage usually looks mundane: a minor rename, a helper pulled into the wrong file, tests that never ran. Nothing exotic is involved. It is simply what an agent does once it has a working tree and the user pictured a suggestion box. Opening no folder, using no Git, or asking to "improve the codebase" without naming files does not stop the extension from running, and that is the danger.

Installing the real extension

The clean path is short. The identity check is what most install videos skip.

Confirm the publisher and identifier

The correct package is the official Codex extension from the Marketplace, not a similarly named community wrapper. It is listed as Codex - OpenAI's coding agent, published by OpenAI, with the unique identifier openai.chatgpt. The identifier is what tells the genuine article from a stray autocomplete plugin.

Quick Open is Cmd+P on macOS and Ctrl+P on Windows and Linux. Paste this and press Enter:

ext install openai.chatgpt

The Extensions view works too: search the exact title and compare publisher and identifier before clicking Install. Counts of installs, star ratings and version numbers are no evidence, since they shift constantly.

The Visual Studio Marketplace page for openai.chatgpt and OpenAI's Codex IDE extension documentation are worth bookmarking. The workflow described here sits around them and does not replace them.

Once installed, the Codex icon can move to the right-hand activity bar so code stays on the left and the agent on the right, a layout most people keep. A vanished icon after an update does not call for a reinstall. The sidebar recovery below covers it.

Signing in with a ChatGPT account

Open the Codex panel and choose Sign in with ChatGPT. Finish the browser redirect on the account that actually holds the plan. The Marketplace listing names Plus, Pro, Business, Edu and Enterprise.

GitHub Copilot Pro+ and Copilot Max have a separate Insiders path, with Sign in with Copilot and an Agent Sessions view. The two login stories are both real and should not be mixed, since they are different buttons.

Some first-run carousels include a sandbox setup step. A widely watched install video clicks through the welcome screens and then picks the backup-sandbox option so the local container can start. If that control appears, it is initialising the isolated environment the agent will use and is not installing a second product.

Access through ChatGPT is tied to a subscription. Message budgets, model pickers and dollar figures change, so any specific Plus or Pro allowance quoted in a mid-2026 roundup should be treated as dated. The account's current usage screen is the authority before planning a long session.

When an API key makes sense

Bring-your-own-key means authenticating with an OpenAI API key and not a ChatGPT login. The sign-in card exposes a Use API Key button. This route helps when a ChatGPT quota runs out or a team already bills through the API.

It is no silent stand-in for a Plus plan. Pricing coverage from 2026 reports that billing by API key in the extension and CLI loses cloud delegation and GitHub code review, so anyone needing those stays on a ChatGPT plan.

When the button is not enough, the shared config can be set explicitly:

preferred_auth_method = "apikey"

A placeholder-only key file then goes at ~/.codex/auth.json:

{"OPENAI_API_KEY": "YOUR_API_KEY_HERE"}

If the panel keeps demanding ChatGPT, export the key in the very shell that starts the editor, then open the folder from there:

export OPENAI_API_KEY="your-api-key-here"
code .

PowerShell on Windows uses $env:OPENAI_API_KEY="your-api-key-here" followed by code .. Real keys must stay out of screenshots, tickets and comments. The JSON shown is a template.

Reports from the community also describe a WSL-specific fault with the Use API Key button. On Windows Subsystem for Linux, a dead button means falling back to config.toml plus the environment variable, or starting the editor from a shell that already holds the key.

A first controlled task

The first task is not meant to impress anyone. Its purpose is to prove that Codex in VS Code touches the files that were named, runs the check that was named and leaves a diff that can be read.

Open the folder and state a testable result

Choose File > Open Folder and select the project root, meaning the folder holding the lockfile, pyproject.toml or the solution file that actually gets built. Initialise Git if absent, open the Codex panel and set the composer to Agent.

Word the goal so that a tired colleague could verify it at six in the evening. It needs:

• One behaviour change.
• One family of files.
• One command or test that proves it.

A first-session prompt can look like this teaching example:

Update token expiry handling in @src/auth.ts. Run the existing tests and summarize changed files.

The sentence carries a file, an outcome and the proof. "Make auth better" carries none.

A hidden panel is reached through the Command Palette with Codex: Open Codex Sidebar. Hunting along the left activity bar wastes time, because updates have shifted the icon to the upper-right toolbar more than once.

Point the agent at the right files

Typing @filename hands the agent a single file without flooding context with the whole tree. Attach what matters and say which files are off limits. Conventions can move into an AGENTS.md at the repository root for later sessions, though the prompt alone suffices for the first task.

Keep the first job to one concern, for example expiry handling, one failing test, a log line or a type fix. Larger multi-file refactors come later, often as cloud work. Local Agent mode will happily begin one, and the reviewer's patience will not keep up.

Reviewing edits and test evidence

When the run finishes, three things deserve inspection in this order:

1. Changed files: whether the agent stayed inside the named path.
2. Tests: whether they were run at all, and whether they passed.
3. Git: git diff and git status act as the review screen, since the extension has already written to disk.

A result card reading Passed with src/auth.ts as the only changed file still leaves the diff to be read. Green tests say nothing about whether an added comment belongs in a public API.

The outcome of all this is an authenticated panel, a scoped Agent run and a change visible in Git. With a clean repository the whole sequence takes about eight minutes. Then comes the decision to keep the change or reset it, followed by a stop. A second task straight away is how people drift into an accidental rewrite.

Local, cloud or CLI

Three routes share the Codex name inside VS Code, and they do not share the same blast radius. The practical question is which one today's job needs.

The local agent

Local Agent mode is the default route here. The work happens in the workspace and review goes through changed files, tests and Git. Its main limit was already stated: edits land directly in the working tree. It suits bounded edits that can be watched.

Cloud delegation

Cloud delegation sends a longer job to an isolated cloud environment, leaving the editor free or even closed. The Marketplace calls this "Delegate to Codex in the cloud". Guides from 2026 describe linking a repository under chatgpt.com/codex/settings/environments, selecting that environment in the sidebar and choosing Run in the cloud against a base branch such as main or the current one.

It fits work that is large, slow or better returned as a diff than as live writes. It needs cloud access on the ChatGPT side, so a setup limited to an API key is the wrong auth route for this feature.

The integrated terminal and the CLI

The Codex CLI is the terminal-native agent, from the same family of models but driven from a shell and not from the sidebar. It can run in VS Code's integrated terminal. Platform installation, updates and sandbox flags belong in a CLI install guide and are not repeated here.

The decision is what counts here. The CLI is the pick for terminal-first control, for moments when the sidebar misbehaves and for long /review runs that keep dying in the extension. Write-ups from 2026 show plain codex opening an interactive session, while a quoted instruction passed to codex exec runs once without interaction, for example asking it to fix all linting errors under src/. Install the CLI only if it is missing.

The question of which tool to prefer overall is separate from how the VS Code agent runs, and a comparison of Claude Code and Codex addresses it.

One configuration layer for both

One architectural fact rarely appears on Marketplace pages: the VS Code extension is closed source, and maintainers describe it as a UI shell around the open-source Codex CLI. That explains why one folder can steer behaviour in both.

The shared ~/.codex/ directory

On macOS and Linux the common folder is ~/.codex/, where config.toml holds defaults and auth.json holds credentials. Both the extension and the CLI read it, so one edit reaches both surfaces.

The Windows equivalent sits under the user profile. Remote and code-server setups add further copies of auth.json inside the extension folder, which are workarounds and not a second source of truth. ~/.codex/ is the better place whenever possible. Text is easier to get right than a screenshot of this folder.

Source-backed defaults

One global example circulates in 2026 guides for the editor:

# ~/.codex/config.toml
model = "gpt-5.3-codex"
approval_mode = "agent"

Treat the model string as perishable. Names in tutorials have already drifted from GPT-5.1 through GPT-5.3-Codex to later GPT-5.x releases. When the panel answers unexpected status 400 Bad Request: {"detail":"Unsupported model"}, the picker holds a name this extension build cannot serve. Pick a supported model in the interface first, and if a default is still wanted, write the one actually chosen.

The approval_mode = "agent" setting is the default shape: reads and edits in the workspace, commands in the working directory and a restricted network. Chat only discusses. Agent Full Access widens local execution and permits internet lookups. The mode should match the task, and Full Access should not stay on just because one npm install last week needed the network.

The API-key preference from the earlier section lives in the same file. Keeping authentication policy and approval policy together means the whole contract can be read in twenty seconds.

Approval loops and the Windows spinner

These are the problems that setup guides skip and that people search for once Codex stops working in VS Code. Both resemble product bugs, and sometimes they are. At other times the sandbox is warning that the agent is about to do something nobody watched. Smoother is not the same as safer.

Cutting approval friction without dropping boundaries

Windows users in particular describe a permission loop, with a pause for a click on every file read or write. The composer offers Chat, Agent and Agent Full Access. The last one silences most prompts, because it authorises wider local action and network use. That is the real trade, and it is also how a request to rename a function becomes an unplanned package download.

A community workaround that recurs in write-ups is this config line:

approval_mode = "auto"

Some threads propose a middle setting called workspace-write and, at the loud end, danger-full-access. Both names originate in community posts, and neither is a reason to aim the agent at a home directory.

Auto or a wider composer mode is reasonable only when all of the following hold:

• Git shows a clean tree, or the changes are stashed.
• No secrets sit in the workspace, or they are ignored by Git.
• The file scope fits in one sentence.
• git diff will be read before anything is pushed.

If any item fails, keep the prompts. The loop is annoying, but a silent write to .env is worse.

Experience shows the limits of the blunt option. Switching to Full Access as a "just stop asking" fix did end the nags, but the session also gained a route to the network that a local rename never needed. The config line works like a scalpel and Full Access works like a bucket.

The Windows 11 WSL loading case

One documented Windows 11 case leaves the panel stuck on Loading. In openai/codex issue #7082, users narrowed it to the WSL integration setting. Early maintainer replies blamed a regional outage, and later ones held the fix still cited today.

In Settings, search for Codex WSL, find Run Codex In Windows Subsystem For Linux and switch it off, then reopen the panel in the runtime actually wanted. It is a Settings change and not a CLI flag, so a codex --no-wsl switch should not be invented, since no source mentions one.

Anyone who really wants Codex inside WSL2 should keep the project on the Linux filesystem and the tools within that environment. A Windows-path repository paired with a Linux agent is the recipe for file-limit and permission bugs that make the panel seem haunted.

After the change, check that the CLI still starts in the trusted terminal. A healthy CLI beside a sick panel points to a WebView or extension fault and not authentication. If both hang, authentication comes first.

Keeping runtimes and histories apart

Codex chat histories are isolated between the Windows and WSL filesystems. Switching modes shows different threads. That is not a sync bug but two separate homes.

One runtime per repository, kept for the week, avoids the confusion. When a switch is unavoidable, assume the conversation will not follow. Durable instructions belong in AGENTS.md in the repository, and not in a sidebar thread that will be lost by Tuesday.

Matching the symptom to the repair

Start from the symptom. Using the WSL fix on a hidden icon burns twenty minutes. A missing panel, a refused model name, a failing review and a remote login that never returns are four different repairs, tried one at a time and never stacked.

Hidden sidebar or unsupported model

If the icon has left the left-hand bar, glance to the upper right before reinstalling. Issue #14586 reports updates leaving access through an Open Codex Sidebar control in the toolbar there, and the Command Palette offers Codex: Open Codex Sidebar as well.

Should the panel open and fail straight away with unexpected status 400 Bad Request: {"detail":"Unsupported model"}, the chosen model is invalid for the installed build. The picker at the bottom of the panel lists supported ones. After choosing, ~/.codex/config.toml needs an update so an outdated model = "..." line does not bring the same error back.

Blank panels and sign-in loops live a layer lower, in the WebView, cookies or a dead token. The dull cure is signing out, clearing the ChatGPT session in the browser and signing in anew. Reinstalling over a bad token just puts a fresh icon above the same auth file.

Long reviews belong in the CLI

The extension's /review command has a reported timeout near five minutes. On a big repository the run can end with the agent explaining that it has applied many fixes already and lacks time to pin down the exact issues.

Five minutes applies in the sidebar, while no matching cap is reported for the same review in the CLI. Anyone who came for review and watches the panel die should run it from the Codex CLI in the integrated terminal and inspect the result in Git. Retrying /review in the sidebar will not change the clock. A deeper review workflow, including asking for a review without triggering a rewrite, deserves its own guide.

Remote SSH and headless machines

Browser OAuth fails predictably on remote SSH, Docker, vscode-server and other headless machines, since the login page cannot return to the host that needs the token. GitHub Discussion #4650 collects community experience.

The most official-feeling workaround is port forwarding in VS Code: in the PORTS view choose Forward a Port, enter 1455, check that the address reads localhost:1455, then run:

codex login

The browser step is completed on the machine that can open a browser, and the forwarded port carries the callback to the remote session.

Credential copying is the heavier option. Sign in on a laptop where OAuth works, then move ~/.codex/auth.json into the remote extension path. For code-server, the target is the folder ~/.local/share/code-server/extensions/openai.chatgpt-[version]/. On Windows, the matching folder sits in the user profile under .vscode\extensions. In both cases [version] stands for whatever suffix the installed folder carries, and the file goes inside as auth.json. The file stays out of commits and chat logs, because it behaves like a session cookie. Forwarding first, copying only when forwarding is impossible.

Whether VS Code is the right editor

Old pages can send readers on a hunt for a dead plugin, so a current boundary helps.

JetBrains and VS Code

VS Code relies on the official Codex IDE extension, identifier openai.chatgpt. JetBrains IDEs form a separate surface. Older PyCharm posts claimed there was no native Codex there, which is out of date: JetBrains announced native support in January 2026, from IDE version 2025.3, covering IntelliJ IDEA, PyCharm, WebStorm and Rider. Searches for IntelliJ or PyCharm Codex lead to that native route and not to the Marketplace identifier. JetBrains users should follow JetBrains' own AI Assistant and Codex documentation.

Cursor users face yet another install and panel. The Marketplace VS Code flow should not be forced into Cursor's extension host, and Cursor has its own plugin route.

Visual Studio Community 2022

Visual Studio Community 2022 does not appear in the list of supported GPT-5.1-Codex clients. A GitHub community discussion lists four surfaces in that preview: VS Code, JetBrains, Xcode and Eclipse. C# developers who still build in Visual Studio often keep it for compiling and run VS Code next to it for the extension on the same files, which is awkward and also the documented split for now.

One bounded task today

A good start is a repository that is already understood. Quieten the working tree with a commit or stash until git status shows nothing, install the extension if missing, sign in and open the folder. Then send one Agent task naming one file and one test and fitting into a single screen of diff.

Watch the files change, read the diff and keep it or reset it. That loop is what using Codex in VS Code means, as opposed to merely installing it.

Editors will keep sprouting buttons, cloud delegation will get smoother and model names will churn again. What stays expensive is handing write access to a tree that cannot be unwound. Once that part is boring, the rest of the agent is free to be interesting.

One habit is worth adopting. The next time the panel requests approval for a file write, say aloud the Git command that would undo it. When the sentence cannot be finished, stash first and ask again, because that pause is the whole review.