Codex CLI and VS Code integration: a practical developer workflow

Codex CLI and the Codex IDE extension are not competing products. They are two surfaces for the same development system.

The CLI is strongest when the task is expressed through files, commands, tests, and scripts. The VS Code extension is strongest when the important context is already visible in an editor: an open file, a selected function, a diagnostic, or an inline diff.

The useful integration is therefore not “keep both windows open.” It is a division of labor with shared configuration and one Git history.

The recommended split

Start where the task context is richest. Move only when the next surface adds a real capability.

Install and sign in

Codex CLI

The current Codex CLI quickstart recommends the standalone installer on macOS and Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Open a project directory and run:

codex

On first run, select an available sign-in method. For a script that needs to check authentication without opening the interface:

codex login status

The developer command reference documents browser OAuth, device authentication, API-key input, and access-token input. Avoid putting credentials directly in shell history.

VS Code

Install the official extension from the link on the Codex IDE page. In VS Code and compatible editors, open the Codex icon. If it is hidden, use the Command Palette:

Codex: Open Codex Sidebar

Open the repository before starting the chat so the editor and Codex agree about the project context.

One configuration model

Codex CLI and the IDE extension share configuration layers on the same host.

User defaults:

~/.codex/config.toml

Trusted project overrides:

.codex/config.toml

In the extension, the settings menu can open config.toml directly. The current configuration guide documents the precedence: launch flags first, then trusted project config, selected profile, user config, system config, and built-in defaults.

This shared model is particularly useful for:

• approval and sandbox defaults;
• MCP server definitions;
• model and reasoning defaults;
• shell environment policy;
• feature flags.

It also means a broken user-level setting affects more than the CLI. Test changes with /status, codex mcp list, or a fresh session before assuming the editor has a separate configuration.

A practical day-to-day workflow

1. Start with a verifiable task

Good:

Trace why the invoice import rejects rows without a tax code. Add a failing test, make the smallest fix, and run the focused suite.

Weak:

Improve the billing system.

The first prompt defines a boundary, expected evidence, and a stopping condition. This matters more than whether it is typed in the terminal or editor.

2. Give Codex durable repository guidance

Keep project-specific commands, boundaries, and conventions in AGENTS.md. Use it for facts a new developer would need:

• package manager and test commands;
• branch rules;
• generated files;
• areas that must remain read-only;
• privacy or deployment constraints.

Do not turn it into an expired project diary.

3. Use the editor for local context

Select the failing function, open the related test, and ask Codex to explain or patch that scope. Review the inline diff before expanding the task.

The editor is particularly effective for:

• focused refactors;
• type errors;
• component changes;
• adding tests next to an implementation;
• reviewing generated code in place.

4. Use the CLI for repository and command context

The CLI is natural for:

• running a search across packages;
• reproducing a failing command;
• inspecting Git state;
• applying a multi-file change;
• collecting validation output;
• working over SSH or in a terminal-first environment.

Inside the interactive CLI, /status, /permissions, /model, and /review make the active state explicit.

5. Make verification part of the request

Ask for the focused test first, then the broader checks proportionate to risk. A clean diff with no fresh test output is still an unverified proposal.

For example:

Run the failing unit test first. After the fix, run the package test, typecheck,
and lint. Do not change generated snapshots unless the behavior change requires it.

6. Review one Git diff

Whether the work started in the editor or CLI, review the same repository diff. Keep normal branch, commit, and pull-request controls. Codex is a contributor to the change, not a replacement for review.

Non-interactive work with codex exec

The current CLI uses codex exec for non-interactive runs:

codex exec "Review the current diff for missing tests and unsafe error handling"

Use non-interactive mode when:

• the prompt and expected output are stable;
• the environment is prepared;
• permissions are intentionally constrained;
• the result can be checked automatically or reviewed as a diff.

Do not use it as an unattended wrapper around an ambiguous production operation.

Permissions: configure both axes

Codex safety combines an approval policy with a sandbox boundary. For normal repository work, a practical baseline is:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Use read-only access for planning and unfamiliar code. Use broader access only where the surrounding environment provides the real isolation.

The dedicated Codex approvals and sandbox guide explains the current values and precedence.

Shared MCP tools

MCP can expose documentation, browsers, design tools, databases, and other controlled services to Codex. The desktop app, CLI, and IDE extension share MCP configuration on the same host.

Check the active servers from the CLI:

codex mcp list

Keep the tool set small and credentials outside committed configuration. The Codex MCP configuration guide covers STDIO, Streamable HTTP, OAuth, and troubleshooting.

When cloud work is a better fit

Local work is ideal when you need immediate feedback from the current machine. Cloud work is useful when a task should run in a prepared container at a selected branch or commit, without occupying the local checkout.

Good cloud candidates:

• a well-scoped change with a reliable setup script;
• an isolated reproduction;
• a task that benefits from running separately while you continue locally;
• a reviewable result that can return as a diff or pull request.

Bad cloud candidates:

• a task that depends on uncommitted local files not present in the remote environment;
• an operation that requires unrestricted production credentials;
• an ambiguous rewrite with no review criteria.

See Codex local versus cloud workflows for the environment and security differences.

A small-team rollout that produces signal

Do not measure success by prompt count. Pick a narrow task set:

1. test repair;
2. dependency upgrade;
3. repetitive migration;
4. code review;
5. documentation tied to code.

For each task, track:

• whether the result was accepted;
• review time;
• regressions or follow-up fixes;
• which checks caught problems;
• which repository instructions were missing.

Update the code, tests, and AGENTS.md from that evidence. Avoid creating a new process document for every experiment.

Common failure patterns

• Using the editor and CLI in different repository roots
• Expecting project config to load before the project is trusted
• Giving unrestricted access because one command needs network access
• Keeping stale MCP servers enabled everywhere
• Asking for broad changes without tests or boundaries
• Treating generated explanations as proof that a command ran
• Delegating uncommitted local state to a cloud environment
• Accepting a large diff without reading it

Where to go next

• Install Codex in VS Code and set permissions
• Troubleshoot Codex in VS Code
• Configure approvals and sandboxing
• Configure MCP once for local clients

The integration works when each surface has a clear job, configuration is shared deliberately, and every useful task ends in evidence you can review.