How to Use Codex: Setup, VS Code, CLI, Desktop, and Cloud

Here is the short version. Codex is one agent you reach from several surfaces: the Codex CLI, the Codex IDE extension, the ChatGPT desktop app, ChatGPT web, Codex cloud, and Remote. They share one ChatGPT login, one session history, and one configuration layer. Learn it once in the terminal or in your editor and the rest is mostly a change of window. The name now covers that whole family rather than a single tool, which is why older tutorials feel out of date.

This guide walks the shared setup first, then gives a complete step-by-step path for Codex in VS Code, then covers only what changes on each other surface, then walks one real task end to end across three of them, then the config layer that follows you everywhere.

Which Codex surface should you use

Codex setup: the part every surface shares

Every surface below assumes the same three things are done. The agent is installed somewhere, you are signed in, and it is pointed at a repo.

Step 1: Install the Codex CLI

Even if you plan to work mainly in an editor, installing the CLI first is worth it. It gives you a fast way to confirm sign-in works before you go hunting for an icon in a sidebar.

On macOS and Linux:

On Windows:

The install script pulls binaries from releases.openai.com/codex and falls back to GitHub Releases if a metadata or asset download is unavailable. If you are behind a proxy that blocks one of those, the other usually gets you through. The CLI itself runs locally on your machine.

Step 2: Sign in with your ChatGPT account

On first run, Codex asks you to sign in with a ChatGPT account or with an API key. Use the ChatGPT account unless you have a specific reason not to. Usage is included in your subscription, and some features may be unavailable when you authenticate with an API key instead, per the quickstart.

That single sign-in is what makes the rest of this guide work. The same account carries your session history and configuration between the CLI, the IDE extension, the desktop app, and the cloud.

Step 3: Point Codex at a repo

Codex works against a folder. Open the repository you want to work in, launch Codex there, and let it read the tree before you ask for anything.

Two habits pay off immediately. Ask it to explain the codebase first; the docs suggest this as a first chat for a reason. You get a fast read on whether the agent actually understands the structure, and it costs you one prompt. Then create a Git checkpoint before you start a task, and another after. Commit or stash whatever is dirty, because reviewing an agent's work is far easier when the diff contains only the agent's work.

How to use Codex in VS Code

This is the surface most developers should start with, because you can see what changed next to the code it changed.

1. Install the extension. Open the Extensions view in VS Code and search for the extension published by OpenAI with the identifier openai.chatgpt. The same extension serves VS Code, VS Code Insiders, Cursor, and Windsurf. Xcode and JetBrains use separate integrations, covered further down. The extension updates automatically, so you do not need to track releases yourself.

2. Open the Codex sidebar. There are two ways in: click the Codex icon, or open the Command Palette and run Codex: Open Codex Sidebar. By default the panel appears in the right sidebar. If you would rather have it on the left, drag the Codex icon over to the left activity bar. If it does not appear at all after install, restart the editor before you start debugging anything else. That fixes it in most cases.

3. Sign in. The extension prompts you to sign in with a ChatGPT account or an API key. If you already signed in to the CLI, use the same ChatGPT account so your history and configuration line up.

4. Give it context from what you already have open. This is the reason to use the IDE surface at all. Instead of pasting code into a chat box, you add an open file, a selection, or a recent chat to the composer. Highlighting the exact function you care about and adding that selection is usually more effective than describing where the code lives.

5. Ask for a focused change. Start narrow. The docs recommend asking Codex to explain the codebase, make a focused change, or help debug an issue as a first task. The useful one for getting a feel for the tool is a focused change: rename a concept consistently, add a field and thread it through, tighten one validation path. Write the request the way you would write a ticket. Say what should be true when it is done and which files are in scope.

6. Review the changes beside your code. When Codex finishes, the extension shows a concise summary plus the changed lines, and you keep the edits you want and follow up in the same view. You do not have to accept a task wholesale. If something is close but wrong, follow up in the same chat rather than starting a new one. The context of what it just did is still there.

7. Delegate the bigger jobs. For tasks that will take a while, you can keep the work local for fast iteration or connect Codex web to delegate a longer task, and the chat stays available when you return to review the result. A delegated task does not cost you your place.

8. Set your keyboard shortcuts. Open the settings icon inside the Codex chat, then select Keyboard shortcuts. Binding open-sidebar and add-selection is the difference between using Codex constantly and forgetting it is installed.

Codex in Cursor: what changes

Same extension, same sign-in, same sidebar behavior. The difference is the activity bar. In Cursor it displays horizontally by default, and collapsed items can hide Codex, which is why people report it "not installing" when it installed fine. Pin the Codex icon and reorder the activity bar so it stays visible.

Codex in Windsurf: what changes

Install openai.chatgpt from the marketplace as you would in VS Code, open it with the Codex icon or the Codex: Open Codex Sidebar command, and sign in with the same ChatGPT account. Everything in the VS Code section above applies unchanged.

Codex in Xcode and JetBrains: what changes

These do not use the openai.chatgpt extension. They have their own integrations. In Xcode, open the coding assistant, start a new chat, and choose Codex as the agent. In JetBrains IDEs, open AI Chat and select Codex. After that, the working pattern is the same: give it context, ask for a focused change, review the diff, keep what you want.

How to use Codex in the desktop app

The desktop app arrived for macOS on February 2, 2026, and Windows support followed on March 4, 2026. It is the surface to reach for when one agent at a time is the bottleneck.

Quickstart, per the docs:

1. Sign in with a ChatGPT account or an API key. Some features may be unavailable with an API key.
2. Choose where it works. Start a chat, create a project, or open a folder that Codex can read and modify.
3. Pick Codex from the ChatGPT dropdown to get software development with codebase context.

What is different here:

• Agents run in separate threads, organized by projects, so you are not queueing work behind a single conversation.
• Built-in worktree support means multiple agents can work on the same repo without conflicts, each on an isolated copy, and you can check out changes locally or let an agent keep going without touching your local git state. That is the feature that makes parallel agents practical rather than chaotic.
• Review happens in the thread. You read the agent's changes, comment on the diff, and open it in your editor when you want the real thing in front of you.
• Your setup follows you. The app picks up your session history and configuration from the CLI and IDE extension, so an app you installed today already knows the setup you did last week.
• Skills bundle instructions, resources, and scripts. The app has a dedicated interface to create and manage them, a skill created there works in the app, CLI, and IDE extension, and skills can be checked into a repository for the whole team.
• Automations combine instructions with optional skills and run on a schedule you define, with results landing in a review queue rather than being applied silently.
• The /personality command switches between the two available personalities, and works in the app, CLI, and IDE extension.

How to use Codex cloud tasks

Go to chatgpt.com/codex. This is where you send work that should not hold your machine, and where a task delegated from the IDE ends up. Because the account is shared, a task you start in the browser is visible from the app and the extension, and the reverse.

Use it when the job is long, when you want to keep working in your editor meanwhile, or when you are on a machine with nothing installed. ChatGPT web and Remote give you the same reach from a browser.

One task, walked across three surfaces

Take a concrete job: a failing integration test after a schema change, plus the migration and docs update that go with it.

In VS Code. Open the failing test file. Add it and the model file to the composer as context. Commit or stash first so the working tree is clean. Ask Codex to diagnose why the test fails and fix the model, and tell it not to touch the migration yet. It works locally, then shows a summary and the changed lines. You read the diff, keep the model change, drop an unrelated formatting edit it threw in, and follow up in the same chat to ask why it renamed one field. Commit.

In the desktop app. The migration and the docs are independent, so run them in parallel. Open the project, start one thread for the migration and another for the docs. Worktrees keep them on isolated copies of the repo, so neither agent is fighting the other or your local git state. Review each thread's diff, comment on the migration where the rollback path is wrong, and open the docs change in your editor to check the code sample renders.

In Codex cloud. The last piece is a slow one: sweeping the rest of the repository for other call sites that assumed the old schema. Delegate it from the IDE to Codex web, or start it at chatgpt.com/codex, and go back to your editor. The chat stays available when you return, and the result is waiting under the same account.

Nothing about the request changes between those three. The agent, the login, and the config are the same. What changes is whether the work blocks you.

The shared config layer

This is the payoff for treating Codex as one product with several front doors. Configuration follows the account and the repo, not the surface.

Repository level

• AGENTS.md is where you put standing instructions for a codebase: conventions, what to avoid, how to run tests. Check it in and every surface reads it for everyone on the team.
• Skills and plugins bundle instructions, resources, and scripts, and can be checked into the repo the same way.
• Rules and subagents let you scope behavior more finely than a single instructions file.

Machine and account level

• config.toml holds your persistent settings.
• MCP connects Codex to external tools and data.
• Hooks let you run your own logic around agent actions.
• Permission modes and sandboxing control what the agent may do without asking.

Workflow level

• Auto-review and code review put a check on generated changes.
• Git worktrees keep parallel agents isolated.
• Scheduled tasks run work on a cadence, with results queued for review.
• Non-interactive mode, the Codex SDK, and the GitHub Action are how Codex runs in CI and in your own scripts.
• Integrations exist for GitHub, GitLab (beta), Slack, and Linear.

The practical order: write an AGENTS.md for your main repo on day one, set permission rules for the commands you approve constantly, and leave the rest until you hit a reason to need it.

How to publish your own expertise as a tool Codex can call

MCP appears in that config list as a way to connect Codex to external tools. It is worth pausing on, because it is the one item that runs in both directions. You can consume tools through it, and you can publish one.

Codex is very good at writing code and very bad at knowing which of the six reasonable architectures your specific business should pick, whether a contract clause is standard for your market, or how to price the thing it just built. It answers those from general training. An MCP connector lets it consult a specific person instead. If you are the person people already ask, that consultation is something you can charge for.

That is what Callstand does. You publish an expert connector and get a handle at callstand.com/p/yourhandle. It exposes three verbs: a plan before work starts, a finished deliverable written in your style, and a review of work before it ships. You price each verb yourself, and buyers hold prepaid credits with per-call spending caps, so there is no invoicing and no scheduling on either side.

Because it runs as an MCP server, Codex, Claude and the rest can call it directly. An agent doing a long refactor can have your judgment checked into the result before anything is merged, at 2am, without you being involved.

What building one actually involves

No prompts to write, no model to train, no code, and no infrastructure. A guided setup captures how you think about the work by having you react to examples rather than write rules, which is the part most experts find easy. Most people finish in an afternoon. You then choose who can call your connector, approve callers individually if you want to, and your material stays private, since callers receive answers rather than access to whatever shaped them.

There is no audience size requirement. The bar is having judgment other people would rather borrow than reconstruct.

Frequently asked questions

Changelog: published August 2026; reviewed September 2026. Covers Codex surfaces, install paths, and permission defaults current as of September 2026, including the macOS desktop app (February 2, 2026) and Windows desktop support (March 4, 2026). Check learn.chatgpt.com for changes after this date.