Codex VS Code extension: installation, sign-in, and permissions

The current Codex setup in VS Code is straightforward:

1. install the official extension;
2. open the intended repository;
3. open the Codex sidebar;
4. sign in;
5. confirm project context and permissions;
6. start with one small, verifiable task.

Avoid old setup guides that describe separate editor-only permission modes or manual extension packages. The current Codex IDE documentation should be the source of truth for supported editors and the install link.

Install the official extension

Open the Codex IDE page and follow the official marketplace link for your editor.

VS Code and compatible editors such as Cursor and Windsurf use the Codex extension. Xcode and JetBrains provide their own integrations, so do not apply VS Code-specific steps to those environments.

After installation, reload the editor if the Codex icon does not appear.

Open Codex

Use the Codex icon in the activity bar. If it is hidden, open the Command Palette and run:

Codex: Open Codex Sidebar

Before starting a chat, confirm that VS Code opened the repository root you intend Codex to inspect. Opening only a nested file or the wrong workspace is a common cause of missing instructions and unexpected Git state.

Sign in

The extension prompts you to sign in through an available account flow. Follow the current in-product options rather than storing credentials in editor settings.

If you also use the CLI, check its authentication state with:

codex login status

The CLI and extension are separate surfaces, but they use the same local Codex host and configuration layers. A valid CLI login check is useful diagnostic evidence; it is not a reason to paste tokens into the editor.

Understand shared configuration

User-level configuration:

~/.codex/config.toml

Trusted project configuration:

.codex/config.toml

In the extension, use the settings gear and choose the option to open config.toml. According to the current configuration guide, the CLI and IDE extension share these layers.

Project settings load only after the project is trusted. CLI flags and launch overrides have higher precedence than project and user files.

Set a safe permission baseline

Codex permissions are two controls, not one label:

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

This is a practical daily baseline. Codex can edit within the workspace and request broader access when needed.

For explanation, planning, or an unfamiliar repository:

approval_policy = "untrusted"
sandbox_mode = "read-only"

Do not use unrestricted access merely to silence prompts. If a task needs wider access, decide whether a narrow writable root, network exception, worktree, or isolated environment solves the actual problem.

The approval and sandbox guide explains the current values and their trade-offs.

Verify setup with a small first task

Choose something easy to review:

Explain how this repository runs tests. Do not edit files.

Then:

Add one failing test for the empty-state bug in this component. Stop after the test fails for the expected reason.

Finally:

Implement the smallest fix and rerun the focused test.

This sequence verifies read access, repository understanding, editing, command execution, and diff review without handing the extension an ambiguous project-wide change.

Add project guidance, not project history

If the repository needs specific commands or boundaries, add an AGENTS.md file at the relevant root. Useful content includes:

• package manager;
• focused test commands;
• generated files;
• branch rules;
• protected directories;
• required privacy checks.

Do not paste a finished migration plan or old product strategy into AGENTS.md. Codex needs current operating rules.

Connect MCP only after the base setup works

The extension, CLI, and desktop app share MCP configuration on the same host. Verify the extension works before adding external servers.

Inspect configured servers from the CLI:

codex mcp list

If you need a new server, add and test one at a time. The Codex MCP guide covers local STDIO, remote Streamable HTTP, and authentication.

Review every proposed change

The extension brings the diff close to the code, but it does not replace Git review.

For each meaningful task:

1. inspect the changed files;
2. check for unrelated edits;
3. run the relevant tests;
4. review generated files separately;
5. commit only the intended scope.

If the diff is larger than expected, ask Codex to explain the scope before accepting it.

Common setup problems

The Codex icon is missing

Confirm the official extension is installed and enabled. Then run Codex: Open Codex Sidebar from the Command Palette.

Project instructions are ignored

Confirm the correct repository root is open and the project is trusted. Project .codex layers do not load for untrusted projects.

Permissions do not match config.toml

Check the active session state, project config, selected profile, and any launch override. Configuration precedence can legitimately override the user file.

The CLI works but the extension does not

Start a fresh editor session, confirm both surfaces use the same local project, and run codex doctor for a structured diagnostic report.

MCP tools are missing

Run codex mcp list --json. If the server is absent there, fix configuration before debugging the editor.

The full Codex VS Code troubleshooting guide provides an ordered diagnostic ladder.

Final setup checklist

• Official extension installed and enabled
• Correct repository root open
• Codex sidebar visible
• Sign-in completed
• Project trust decision understood
• config.toml location verified
• Approval and sandbox defaults selected
• One read-only task completed
• One small edit reviewed and tested

Once those steps work, expand deliberately into MCP tools, non-interactive CLI tasks, and cloud delegation. A minimal verified setup is more useful than a powerful configuration you cannot debug.