Codex Setup Guide for Windows, WSL, VS Code, and CLI

What is this about?

This guide is for a developer setup where the Codex app runs on Windows, the agent runs in WSL2, VS Code uses Remote WSL, and the Codex CLI is installed inside WSL. The goal is a setup where app, IDE, and CLI work from the same rules, tools, and skills instead of drifting apart.

1. Recommended target setup

If your code, Node/Yarn, Python, Git, and shell workflow already run in Linux, WSL2 is the cleanest shared working environment:

Area	Recommendation
Repo location	Store repos in WSL under /home/<user>/code/..., not under /mnt/c/...
Codex App	Use the Windows app, set Agent Environment to WSL2, then restart the app
VS Code	Open the folder from WSL with code .; the status bar should show WSL: ...
CLI	Install and run Codex in the WSL shell
Project rules	Repo-level AGENTS.md in the Git root
Personal rules	~/.codex/AGENTS.md in the environment Codex actually uses
Project skills	.agents/skills/<skill-name>/SKILL.md in the repo
Personal skills	$HOME/.agents/skills/<skill-name>/SKILL.md
Settings	~/.codex/config.toml plus optional .codex/config.toml in the repo

The key point: the Windows app and WSL CLI use different home directories by default. The Windows app normally uses %USERPROFILE%\.codex; the CLI inside WSL uses /home/<user>/.codex. If you expect skills, auth, sessions, memories, or config to appear in both worlds, you must either unify the paths deliberately or maintain them separately.

2. Why WSL can be a good Agent Environment

WSL is useful when your project expects a Linux toolchain:

• same shell and path behavior as many CI/CD systems,
• faster and more stable I/O when the repo lives under /home/...,
• fewer problems with symlinks, permissions, and Linux-native tools,
• VS Code Remote WSL, integrated terminal, and Codex all work in the same filesystem,
• Codex uses the Linux sandbox in WSL instead of the Windows sandbox.

WSL is less useful when your project is Windows-native, for example .NET desktop, PowerShell-first automation, Visual Studio-heavy workflows, or repositories stored on the Windows filesystem. In those cases, the native Windows agent is often more direct.

Avoid half-WSL setups

Do not keep Linux projects under /mnt/c/... just because Windows can see them more easily. That is often slower and causes more path, symlink, and permission issues. For Windows access, use \\wsl$\Ubuntu\home\<user>\... instead.

3. Installation in WSL

Start WSL2 from Windows once if it is not installed yet:

wsl --install
wsl

Install Codex in the WSL shell:

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

For WSL/Linux sandboxing, bubblewrap should be installed:

sudo apt update
sudo apt install bubblewrap

Typical base tools for this repo:

sudo apt update
sudo apt install git curl nodejs npm python3
corepack enable
yarn --version

Depending on your Node setup, nvm, fnm, or a NodeSource install can be cleaner than the Ubuntu package. The important part: this project expects Node 20+ and Yarn.

4. Open the repo and VS Code correctly

Keep repos inside WSL:

mkdir -p ~/code
cd ~/code
git clone <repo-url>
cd <repo>
code .

Check VS Code:

• bottom-left status bar says WSL: <distro>,
• the integrated terminal shows Linux paths such as /home/...,
• echo $WSL_DISTRO_NAME prints your distribution,
• which codex points to a Linux install, not C:\....

If VS Code is not running in WSL: Ctrl+Shift+P -> WSL: Reopen Folder in WSL.

5. Connect the Codex app to WSL

In the Windows app:

1. Open Settings.
2. Switch Agent Environment from Windows native to WSL.
3. Restart the app, because the change only applies after restart.
4. Open the project from the WSL filesystem. If the picker does not show it, type \\wsl$ and navigate to the distro.
5. Optionally set the integrated terminal to WSL as well. Agent Environment and terminal are separate settings.

The app can work with WSL projects, but its Windows-side app configuration is not automatically the same as the WSL CLI configuration. That is where most "why do I not see X?" issues come from.

6. Link app and CLI sensibly

App, CLI, and IDE share Codex concepts: config.toml, MCP, skills, plugins, AGENTS.md, approvals, sandbox, models, and feature flags. In practice, you link them through shared files and the same working environment.

Function	In the app	In the CLI
Start desktop	Open the app directly	codex app
Feature flags	Settings or prompt	codex features list, codex features enable goals
Check MCP	Settings or /mcp	codex mcp ... and ~/.codex/config.toml
Use skills	$skill-name or skill list	$skill-name, /skills, skill metadata
Project rules	Loaded automatically from AGENTS.md	Loaded automatically from AGENTS.md
Review	Diff panel or /review	/review
Status	/status	/status
Goal mode	/goal	/goal

Shared CODEX_HOME

If you want the WSL CLI and Windows app to see the same config/auth/sessions, you have two options:

Option	Advantage	Drawback
Keep them separate	Clean OS separation, fewer path surprises	Config, skills, auth, and sessions must be maintained twice
Point WSL CODEX_HOME to the Windows home	App and WSL CLI see the same Codex home	WSL accesses /mnt/c/...; can be slower and needs path discipline

Example for a shared CODEX_HOME in WSL:

export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex

Make it persistent:

echo 'export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex' >> ~/.zshrc

I would only use a shared CODEX_HOME when you truly want to share sessions/auth/config. For team and repo rules, it is more robust to keep AGENTS.md and .agents/skills directly in the repo.

7. Why do I not see skills in the app?

It is usually one of these:

Cause	Check	Fix
Skills exist only in WSL	Run find ~/.agents/skills -maxdepth 2 -name SKILL.md in WSL	Move repo skills to .agents/skills or sync Windows/WSL homes
App uses another Codex home	Windows: %USERPROFILE%\.codex; WSL: ~/.codex	Set CODEX_HOME deliberately or maintain config separately
App was not reloaded after skill changes	Skill appears after restart	Restart the app or reload skills
Skill is in the wrong shape	Expected: <dir>/SKILL.md with name and description	Fix the directory structure
Project was opened from another path	App shows Windows path, VS Code shows WSL path	Open the same repo from \\wsl$ or /home/...
Project is not trusted	Project config/rules/skills are ignored	Mark the project as trusted in Codex
Skill comes from a plugin	Plugin is not installed or disabled	App: open Plugins; CLI: /plugins
Too many skills are installed	Not every skill appears in initial context	Invoke the skill explicitly with $skill-name

A minimal repo-local skill looks like this:

.agents/
  skills/
    docs-review/
      SKILL.md

---
name: docs-review
description: Review MDX documentation for structure, broken links, tone, and Docusaurus build risks.
---

1. Read the changed MDX files.
2. Check links, headings, admonitions, code fences, and sidebar metadata.
3. Run the documented build command if possible.
4. Report issues before style suggestions.

Repo skills are best for teams because app, CLI, and IDE can all see them as soon as they run in the same repo context.

8. Personalization, AGENTS.md, and config

The Codex app has personalization settings such as personality and custom instructions. Whether the WSL CLI sees them depends on whether app and CLI load the same files.

Goal	Right place
Personal working style for all repos	~/.codex/AGENTS.md
Temporary personal override	~/.codex/AGENTS.override.md
Repo rules for the whole team	AGENTS.md in the repo root
Directory-specific repo rules	AGENTS.md or AGENTS.override.md in subdirectories
Codex settings	~/.codex/config.toml
Project settings	.codex/config.toml in the repo, trusted projects only
Reusable workflows	.agents/skills/.../SKILL.md or $HOME/.agents/skills/.../SKILL.md

Usually you do not want /.codex directly in the Linux root. You almost always want ~/.codex, meaning your home directory.

A good global ~/.codex/AGENTS.md:

# Personal Codex defaults

## Working style

- Answer in German unless the repository or user asks for English.
- Prefer concise final summaries with validation status.
- Before editing, inspect the local conventions.
- Do not add dependencies without calling out why they are needed.

## Verification

- For documentation-only changes, run the project's documented build command when practical.
- If validation cannot run, explain why.

A good repo-local AGENTS.md is more technical and less personal:

# Repository Guidelines

## Commands

- Use `yarn build` to validate Docusaurus docs changes.
- Use `yarn start` for manual UI checks.

## Docs

- Keep filenames lowercase and descriptive.
- Use MDX frontmatter with `title`, `description`, and `sidebar_position`.
- Keep source docs in English and put German translations under `i18n/de/`.

9. Useful config.toml baseline

Start small. This file lives in WSL under ~/.codex/config.toml, unless you set CODEX_HOME differently:

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
web_search = "cached"
personality = "pragmatic"

[features]
goals = true
hooks = true
memories = false

[sandbox_workspace_write]
network_access = false

Important rules:

• approval_policy = "on-request" is a good start because Codex can work but asks for risky actions.
• sandbox_mode = "workspace-write" allows repo work without opening the whole system.
• network_access = false is safer; grant package installs or web access deliberately.
• memories are optional and unavailable in some regions. Team rules still belong in AGENTS.md, not only in memories.
• Use project config in .codex/config.toml only for settings that truly belong to the repo.

10. VS Code Extension

The Codex VS Code Extension uses the same agent as CLI and app and shares Codex configuration. Limited to VS Code, these features matter most:

Feature	Meaning
IDE Context	Codex can use open files, selections, and explicitly added files as context
Auto Context	Codex automatically includes current editor signals; controlled with /auto-context
@file	Reference a file directly in the prompt
Add selected text to thread	Add highlighted code as context to the current thread
Add file to thread	Add the whole file as context
Implement TODO	Start a task from the selected TODO comment
Model selector	Change model and reasoning effort in the UI
Approval mode	Switch between Chat, Agent, and Agent Full Access
Cloud delegation	Delegate larger jobs to Codex Cloud
/review	Review uncommitted changes or a branch diff
/goal	Start goal mode for a persistently pursued task

Agent, Chat, and Plan Mode

In the VS Code Extension, the Agent/Chat mode switch means the mode inside the Codex panel, not "ChatGPT window vs Codex window".

Mode	What happens	When to use it
Chat	Codex answers, explains, and plans without automatically changing code or running commands	Questions, architecture, planning, debugging conversation
Agent	Codex may read, edit, and run local commands in the workspace; it asks for external paths/network	Normal implementation
Agent Full Access	Codex works with broader access and fewer interruptions	Only for trusted repos and clear tasks

Plan Mode means "gather context and create a plan first, then implement". In the app and CLI, use /plan. In VS Code, you get the same effect through Chat mode or, if your version exposes it, through the slash command. Good prompts are explicit:

Plan only first. Read the relevant files, ask open questions, and give me an implementation plan. Do not edit files yet.

Pursue Goal / Goal Mode

/goal starts a persistent objective. Codex works toward it until the goal is done, paused, or needs more input. This is useful for tasks like "finish this migration and validate it".

If /goal does not appear:

[features]
goals = true

Or in the CLI:

codex features enable goals

Configuration Tools in VS Code

The most important configuration entry points:

• Gear/menu in the Codex panel -> Codex Settings -> open config.toml.
• Model selector below the prompt -> model and reasoning effort.
• Approval/mode switch -> Chat, Agent, Full Access.
• /status -> thread ID, context, limits.
• /mcp or MCP Settings -> inspect connected MCP servers.
• VS Code setting chatgpt.runCodexInWindowsSubsystemForLinux -> run Codex in WSL when Windows and WSL are available.

11. CLI in WSL

The CLI is your fastest path for repo-adjacent work:

# Interactive session in the current repo
codex

# Short task with repo context
codex "Explain the structure of this project"

# Non-interactive automation
codex exec "Check the docs for broken links and summarize the findings"

# Resume the last session
codex resume --last

# Set the model for this run
codex --model gpt-5.5

# Show active version info
codex --version

Login:

codex login

Use ChatGPT login when you want your ChatGPT/Codex entitlements, Codex Cloud, or workspace policies. Use API-key login mostly for CI/CD or clearly billed API workflows.

Good CLI habits:

• Always start codex in the repo root or use --cd.
• Use /status when you are unsure which session/config is active.
• Use /permissions when you temporarily want tighter or broader access.
• Use /review before accepting larger changes.
• Use codex exec for repeatable script tasks, but keep permissions narrow.

12. MCP, plugins, and external tools

MCP connects Codex to external tools and data. Plugins are installable bundles that can combine skills, apps, and MCP servers.

Need	Recommendation
Use GitHub, Linear, Slack, Drive, Figma, or internal tools	MCP or plugin
A repeatable workflow without an external tool	Skill
A team should install the same tool workflow	Plugin
Only repo-internal rules	AGENTS.md

MCP configuration belongs in ~/.codex/config.toml or, for trusted repos, in .codex/config.toml. If app, CLI, and IDE load the same config, they see the same MCP servers.

13. Security checklist

Before production use:

• Secure your ChatGPT account with MFA, especially when using Codex Cloud.
• Never commit auth.json, API keys, tokens, or .env.
• Keep the default around workspace-write and on-request until you know a repo well.
• Use Full Access only for clear tasks in trusted repos.
• Grant network access deliberately, not broadly.
• Inspect repos from unknown sources in read-only mode first.
• Use AGENTS.md for project rules, not only memory or ad-hoc prompts.
• Document test, build, and review commands in the repo.
• For WSL: keep the repo under /home/..., not /mnt/c/....

14. Setup check for your scenario

Run these checks in WSL:

pwd
echo $WSL_DISTRO_NAME
which codex
codex --version
echo "${CODEX_HOME:-$HOME/.codex}"
find ~/.agents/skills -maxdepth 3 -name SKILL.md 2>/dev/null
test -f ~/.codex/AGENTS.md && sed -n '1,80p' ~/.codex/AGENTS.md
test -f ~/.codex/config.toml && sed -n '1,120p' ~/.codex/config.toml
git rev-parse --show-toplevel

In VS Code:

• Status bar shows WSL: ....
• Codex Extension is active in the WSL window.
• Integrated Terminal finds codex.
• Auto Context can be controlled with /auto-context.
• /goal appears or features.goals = true is set.

In the Windows app:

• Agent Environment is set to WSL.
• App was restarted after the change.
• Project was opened from \\wsl$ or a WSL project path.
• Skills/plugins are installed or live in the repo.
• /status, /mcp, /review work in the thread.

15. Short answers to common questions

Does personalization from the Codex app also apply to the WSL CLI?

Only if both load the same config/instruction files. With Windows app plus WSL CLI, that is usually not true without CODEX_HOME sync. Put important personal rules in WSL under ~/.codex/AGENTS.md or deliberately share CODEX_HOME.

Which Markdown files do I need?

Minimum: repo-local AGENTS.md. Optional: global ~/.codex/AGENTS.md. For skills: SKILL.md in .agents/skills/<name>/ or $HOME/.agents/skills/<name>/.

Is .codex/config.toml the same as AGENTS.md?

No. AGENTS.md is working guidance. config.toml is technical configuration: model, sandbox, approval, MCP, feature flags, hooks.

Why does the app not see my CLI skills?

Because app and CLI most likely see different home directories and skill paths. Use repo-local .agents/skills, restart, or deliberately share the relevant paths.

Does the Agent/Chat switch in the web docs mean the ChatGPT and Codex windows?

No. It means the mode inside the Codex IDE Extension: Chat for questions/planning, Agent for actual repo actions.

Should I use app, IDE, and CLI in parallel?

Yes, but with clear roles: app for parallel threads, worktrees, review, and larger workflows; VS Code for editor-local context; CLI for fast repo work, exec, resume, and debugging.

Official sources

• Codex Quickstart
• Codex App Features
• Codex Windows and WSL
• Codex CLI
• Codex IDE Extension
• Codex Config Basics
• Custom Instructions with AGENTS.md
• Codex Skills
• Codex MCP
• Codex Plugins
• VS Code WSL Tutorial