Desktop App Overview
📚 Series Navigation: The previous article 06 · Running Your First Task let you send your first instruction and watch Codex finish the task. This article officially introduces its most promoted entry—the Desktop App, laying out the interface layout, what it can do, key configurations, and shortcuts. The next article 08 · Getting Started with the CLI returns to the terminal to cover the other path.
OpenAI split Codex into four entries, but the download button on the homepage, the entire app folder in the docs, and even the event demos all center on one thing—the Desktop App. Not the CLI, not the Web version, but this standalone window.
This is not an exaggeration. I counted the subpages under the official app directory: features, commands, settings, review, worktrees, automations, browser, computer-use, local-environments, chrome-extension... Over a dozen pages are dedicated to the Desktop App, while CLI documentation has less than half of that volume. Where the official focus lies is clear.
However, the first reaction of many people is: "Desktop App? Isn't that just a simplified version for people who don't know the command line? I'll go straight to the CLI." To be honest, this judgment is wrong for Codex—the Codex Desktop App is not a stripped-down version of the CLI. It packs parallelism, Worktree isolation, visual reviews, built-in browser, and automation all into a single window, making it the feature-richest face of the tool.
This article takes you on a tour of this window: what each area does, how to run parallel tasks without conflicts, how to review edits at a glance, and which shortcuts are most worth remembering.
After reading this article, you will get:
- A layout diagram of the Desktop App: what the left sidebar, middle conversation area, and right panel manage
- A clear explanation of the differences between the three run modes (Local / Worktree / Cloud) and when to use which
- How to use the visual review panel—line-by-line annotations, block-by-block accept/discard, and committing/pushing PRs all inside the window
- Built-in terminal, Actions shortcut buttons, and Automations—the features that the "CLI cannot offer"
- A cheat sheet of the most important shortcuts + slash commands, along with a copy-pasteable startup flow
⚠️ All specific shortcuts, settings, and default behaviors mentioned below are based on the Codex official documentation; shortcuts in the official docs are currently only labeled for macOS, and keymaps on Windows are subject to what is displayed in your local Settings > Keyboard Shortcuts, which we will highlight below.
01 Understand First: The Positioning of the Desktop App
Many people open the Desktop App and get confused by the tabs, buttons, and icons. Don't click blindly; understand its positioning first so you know where each area belongs.
First, the conclusion: the Codex Desktop App is a code workbench "built for parallelism." The official docs call it "a focused desktop experience for working on Codex threads in parallel." Here, a thread (thread) is an independent task; the instruction you sent in Article 06 was a thread.
Analogy: An open office with many desks. (Here, "desks" refer to independent Codex task threads, not your physical seat.) The CLI is like sitting at a single desk working on one task at a time; the Desktop App is like being a team leader with a row of desks in front of you, each with a Codex agent working on a different task—one fixing a bug, one writing tests, one running a long task in the corner—you scan the room, see where everyone is, and step in when they need your decision. "Monitoring a row of tasks and switching to intervene at any time" is the soul of the Desktop App.
It runs the same Codex as the CLI and IDE extensions, sharing the same AGENTS.md (the project onboarding handbook from Article 02), the same MCP configuration, and the same Skills. So it is not "another watered-down tool" but the same Codex inside a wrapper optimized for parallelism and visualization.
Real-world scenarios where you would use the Desktop App:
- Handling three or four unrelated minor requirements that you want to run in parallel without their edits conflicting on the same files.
- Taking over an unfamiliar frontend project and wanting to see page results in a built-in browser as Codex edits them.
- Wanting a daily summary of "what changed in the codebase yesterday" automatically generated every morning.
These three tasks are either impossible in the CLI or require building your own scripts; in the Desktop App, they work out of the box.
💡 Summary in one sentence: The Desktop App is not a simplified version of the CLI; it is the same Codex wrapped in a workbench shell optimized for parallelism and visualization, and it is the main entry officially promoted.
02 Installing It: Two Platforms, plus Bad News for Linux
Let's get the bad news out of the way first: Linux has no Desktop App for now.
This is not a mistake on your part; the official app has not been released yet—the official site has a sign-up form for Linux users, and until then, use the CLI. Below we focus only on macOS and Windows.
The installation itself was covered in Article 03; here we highlight the parts relevant to the Desktop App:
| Platform | How to Get | Traps to Avoid |
|---|---|---|
| macOS (Apple Silicon) | Go to the official download page and get the default build | Downloading the wrong chip version will fail to install |
| macOS (Intel Chip) | Select Intel build on the same page | Avoid downloading the Apple Silicon one |
| Windows | Distributed via Microsoft Store; command line: winget install Codex -s msstore | Check sandbox configurations in Article 03 |
| Linux | None; sign up for updates | Use the CLI for now |
Once installed and opened, there is a hidden requirement for logging in that you must know:
The Desktop App has full functionality when logged in with a ChatGPT account; some features are restricted or unavailable when logged in with an OpenAI API key. The official docs state that "some functionality might not be available." What features are disabled under API keys change rapidly, so check the official billing and feature availability pages—just remember: to unlock everything the Desktop App has to offer, log in with a ChatGPT account. This echoes Article 04: Codex usage is included in your ChatGPT subscription (Plus / Pro / Business / Edu / Enterprise).
When I first installed the Desktop App in March 2026, I pasted an API key to log in out of convenience, only to find a cloud feature grayed out. I assumed it was a version bug and spent ten minutes troubleshooting before realizing it was the login method. Logging out and logging back in with a ChatGPT account lit up the grayed-out areas immediately. I've run into this trap for you.
💡 Summary in one sentence: The Desktop App is macOS and Windows only, with Linux still in line; Mac users must distinguish between Intel and Apple Silicon builds, and log in with a ChatGPT account—API keys will disable some features.
03 Interface Layout: Left Sidebar / Middle Area / Right Panel
When you open the Desktop App, the screen is split into three vertical sections: the left sidebar manages "where to go," the middle area handles "dialogue and tasks," and the right panel manages "reviewing results." Understanding these three will stop you from feeling overwhelmed.
Here is a layout diagram. Even if you cannot see the image, the text below will explain it:
This diagram shows that: you select the project and thread in the left sidebar → chat and send instructions in the middle area → review Codex's output in the right panel. The workflow flows from left to right. Let's break down each area.
Left Sidebar: Your "Navigation Hub"
The left sidebar, from top to bottom, is your entry point for managing everything (names are subject to change in local versions, as the official interface is updated regularly):
- New Thread: Open a brand-new task. This is the button you will use most often.
- Search: Search historical conversations and project records. Acts as a global search in large projects.
- Plugins: Add external capabilities to Codex, like browser access or GitHub integration.
- Automations: Set up Codex to run tasks automatically on a schedule (detailed in Section 05).
- Projects: The list of project folders / codebases you have bound; switch between projects here.
- Chats: Pure chats not bound to a project, suitable for looking up information or doing research.
Here is a crucial distinction for beginners: a Project is not the same as a Chat.
Analogy: A Project is a "formal employee with an ID card," and a Chat is a "visitor asking for directions at the door." A Project is bound to a specific folder on your computer; Codex can enter it to read files, modify code, and run commands—it has an "ID card" and can work in the factory. A Chat is not bound to a project; the official docs state it uses a thread directory managed by Codex itself (default ~/.codex/threads), which is suitable for researching, planning, and adjusting plugins—tasks that do not touch your code repositories—like a visitor at the door chatting without entering the work area.
Real-world scenarios:
- Letting Codex modify the login logic in your local
~/code/my-app→ use a Project. - Asking it "how does ownership work in Rust" purely to check documentation → use a Chat, no project binding needed.
Middle Area: Main Chat and Command Zone
This large main workspace in the middle is the core: the upper portion is the dialogue stream (what Codex read, modified, and ran), and the bottom is the input box. The input box contains several key switches that you should check before sending instructions:
- Mode Selector: Local / Worktree / Cloud, deciding where this thread runs (detailed in Section 04).
- Model Selector: Switch which model is used, which can be changed mid-conversation.
- Permission Selector: The approval policy discussed in Article 02, controlling whether Codex asks before modifying files.
Right Panel: Viewing What Codex Did
The right panel may be collapsed by default; click the panel icon in the top right to expand it. It is the "results display area" containing:
- Diff Review: What files Codex modified and which lines changed (the highlight of Section 03).
- Built-in Terminal: A terminal sharing the same working directory as Codex (detailed in Section 05).
- Preview: Pages, files, images, and Sources; clicking them displays them here.
Putting all three together into a single window looks roughly like this:
This diagram splits the Desktop App window into six areas—top status bar (Project / Mode / Model / Actions), left project and thread list, middle dialogue area, top-right Diff review panel, bottom-right built-in terminal, and bottom status bar (Branch / Token usage / Connection state). The arrows point to the main line: "left selector → middle prompt → right review." This is a conceptual diagram; actual UI layout is subject to official changes—areas and names may vary slightly in your local build.
Let's look at the actual interface to get familiar:
💡 Summary in one sentence: The interface has three columns—left sidebar select, middle area prompt, and right panel review; remember the rule that "Projects edit code, Chats are only for conversations" to save yourself from confusion.
04 Three Run Modes: Choosing Between Local, Worktree, and Cloud
Before sending your first message, you choose a run mode below the input box. This is the most important setting to understand in the Desktop App—choose the wrong one, and you might contaminate your main branch or run the task somewhere you can't reach.
The three modes in the official docs:
| Mode | Where It Runs | Where Edits Are Applied | When to Use |
|---|---|---|---|
| Local | Your machine, current project directory | Directly modifies your working directory | Daily development, wanting to see results immediately |
| Worktree | Your machine, independent Git worktree | In an isolated copy, not touching the main directory | Trying out new ideas, or running parallel tasks without conflicts |
| Cloud | OpenAI cloud sandbox | Cloud sandbox, results returned as PRs or reports | Offloading long tasks to the background without consuming local resources |
The official docs emphasize a key detail: both Local and Worktree run on your own computer, while only Cloud is remote. Don't be intimidated by the name "Worktree"; it still works on your machine, just in an isolated folder copy.
Let's focus on Worktree, as it is the foundation of "parallelism without conflicts" in the Desktop App.
Analogy: Photocopying the same blueprint several times so everyone can edit separately. You and several Codex agents are modifying the same project (the same blueprint). If everyone edits the same original file in Local, edits will overwrite each other. The Worktree method photocopies a complete copy of the blueprint for every task (a Git worktree, using git worktree under the hood) so everyone edits their own copy, never touching anyone else's. Once a copy is ready, you decide whether to merge it back into the original. Before merging, changes in one thread will never contaminate another.
I mentioned a sandbox permission trap in Article 02, and here is a related lesson about Worktree: in April, I opened two parallel threads in Local mode modifying the same repository—one refactoring the data layer and one modifying routing. Both edited the same configuration file, and the second thread overwrite half of the first thread's edits. I stared at git diff for a long time before figuring it out. Since then, whenever I run parallel tasks on the same project, I always use Worktree, and I've never had an overwrite issue since.
A few official facts about Worktree you must know to avoid traps:
- Worktree only works inside Git repositories—it relies on
git worktreeunder the hood. If the project is not a Git repository, the review panel will prompt you to initialize one first. - Worktree only inherits files committed to Git—files in
.gitignore(like.envornode_modules) will not be copied over. This means new worktrees often lack dependencies, which you must resolve using "setup scripts" (detailed in Section 05 under Local Environments). - Where Stored: Codex creates worktrees under
$CODEX_HOME/worktrees(whereCODEX_HOMEdefaults to~/.codex), and they default to a "detached HEAD" state, avoiding branch contamination. - Handoff: If you want to move a thread between Local and Worktree, use the Hand off button at the top of the thread. Codex will handle the Git operations under the hood. For example, after running a task in a worktree in the background, hand it off to Local to inspect it in your familiar IDE.
- Auto Cleanup: By default, the system retains only the 15 most recent worktrees managed by Codex, deleting older ones automatically (creating snapshots before deletion so they can be restored). You can change this limit and auto-cleanup rules in settings.
Note that these numbers and defaults (like "retaining 15 copies") change regularly, so refer to your local settings panel for current values.
💡 Summary in one sentence: Local directly modifies your main directory, Worktree creates isolated copies for tasks (essential for parallel work without conflicts), and Cloud outsources tasks to the cloud. Use Worktree for parallel work, but remember it only copies Git-committed files.
05 Features That the "CLI Cannot Offer"
What truly separates the Desktop App from the CLI are the following graphical features that rely on the UI. Let's break them down.
Visual Review Panel: Review Edits at a Glance
This is the most direct improvement over a plain terminal. In the CLI, Codex prints diffs as green and red text streams; the Desktop App turns this into a Review pane where you can click, write line-by-line annotations, and accept or discard changes block-by-block.
Analogy: Upgrading from "reading a whole email" to "commenting inside a document." In the CLI, reviewing a diff is like reading a plain text email from top to bottom; if you want to give feedback, you have to write a new message describing "change the variable name in line 20." The review panel is like editing in track-changes mode in Word or Google Docs—you click on a specific line and type your comment, which is much more precise.
Key features of the Review panel (all from the official docs):
- Defaults to "uncommitted changes": It reflects the state of your entire Git repository, not just Codex's changes—your own manual edits and other uncommitted edits will display here.
- Switch View Scope: You can switch from "uncommitted changes" to All branch changes (compared to the baseline branch) and Last turn changes (only what Codex changed in the last message cycle). Locally, you can also switch between Unstaged / Staged changes.
- Line-by-line Inline Comments: Hover over a line in the diff, click the + button that appears, and write your feedback. Send a message to the thread (like "edit according to the inline comments, keep changes minimal"), and Codex will follow your comments.
- Granular Staging / Discarding: You can stage, unstage, or revert (discard) changes at three levels: the entire diff, a single file, or a single hunk (block of code). Keep what you want and discard what you don't with a single click.
Commit and Push directly: For Local and Worktree tasks, once you are happy with the diff, you can commit, push, and create a Pull Request directly in the App without switching to the terminal.
Note: The Review panel only works for projects inside Git repositories. If it is not a Git repository, it prompts you to initialize one. To manage GitHub PR comments in the App, you must install and log into the GitHub CLI (gh) on your machine—run gh auth login to authorize it; otherwise, PR context may fail to load.
I've found line-by-line annotations extremely useful. In the CLI, describing where to edit was tedious ("the function handling timeouts, around line 20, that magic number"), and it often modified the wrong place; now I click on the line and write "extract this number to a constant," and it gets it right every time.
Built-in Terminal: Shared Environment with Codex
Every thread contains a built-in terminal (integrated terminal) whose scope is the current project or worktree. Open it by clicking the terminal icon in the top right, or pressing Cmd + J on macOS (Windows keymaps are covered in Section 06).
The best part: this terminal runs in the thread's working directory, sharing the environment with Codex. If you run git status or npm test inside, you are looking at the exact copy of files Codex is editing, avoiding any file mismatches. Furthermore, Codex can read the output of this terminal, so it can inspect your local server logs or build outputs to check why a build failed.
A shortcut trap to avoid (explicitly noted in the docs):
Cmd + Kin the Desktop App opens the command menu, not clearing the terminal. To clear the terminal, useCtrl + L.
Actions: Saving Common Commands as Top Buttons
Running the same sequence of commands repeatedly (npm run dev, running tests, formatting)? The Desktop App lets you save them as Actions (actions), placing them as one-click buttons at the top of the window.
Analogy: Saving a favorite food order as "order again." Searching for the store, selecting items, and checking out every time is tedious; saving it as "order again" lets you do it with one click. Actions are these "order again" buttons for project commands—click them, and they run in the built-in terminal.
Where are Actions configured? Along with Worktree setup scripts, they belong to Local Environments (local environments), with configurations stored in the .codex folder in the project root, which can be committed to Git to be shared by the team. Setup scripts run automatically when a worktree is created (fixing the "missing dependencies in worktrees" issue), and Actions are run manually by clicking. Together, they ensure that worktrees are created with dependencies intact and common commands are available at your fingertips.
Automations: Scheduled Automation
Automations (automations) allow Codex to run tasks on a schedule—daily, weekly, or at specific times.
Analogy: Setting an alarm + task list for Codex. The alarm rings (the scheduled time arrives), and it wakes up to complete the tasks you listed, placing the results in your inbox when done.
Official examples:
- Daily Code Summary: Analyzes recent commits to generate a summary of "what was changed yesterday."
- Telemetry Error Monitoring: Regularly inspects telemetry logs for errors and attempts to fix them automatically.
- Thread Automation: Scheduled wake-ups for specific threads to continue long-running tasks, retaining context—ideal for tasks requiring multi-day runs.
Prerequisite: Automations require that the App is running and the corresponding project folder is accessible on disk.
I set up an Automation in April to summarize yesterday's commits into a daily report for a personal project. It ran for two weeks, and every morning I opened the App to find a fresh report—this experience of "work done without me doing anything" is something the CLI cannot match.
💡 Summary in one sentence: The visual review panel (inline comments + block rollback + PR creation), the shared built-in terminal, one-click Actions, and scheduled Automations—these four features are the core advantages of the Desktop App over the CLI, fully utilizing the graphical interface.
06 Shortcuts and Slash Commands: The Most Important Ones
The Desktop App has many shortcuts, but you don't need to memorize them all. First, a critical prerequisite:
The official shortcut documentation only lists macOS keymaps. The corresponding keys on Windows are subject to what is displayed in your local Settings > Keyboard Shortcuts panel—you can search commands or modify keymaps there, so check that panel instead of copying Mac
Cmdkeymaps.
Here are the highest-return macOS shortcuts I use (all from the official commands docs):
| macOS Shortcut | What It Does | Why It is Worth Memorizing |
|---|---|---|
Cmd + Shift + P or Cmd + K | Open command menu | Run anything from here; remember this if nothing else |
Cmd + N or Cmd + Shift + O | New thread | The starting point for parallel work; used most often |
Cmd + J | Toggle built-in terminal | Run commands to verify changes; high-frequency |
Cmd + B | Toggle left sidebar | Hide it to get a larger conversation area |
Cmd + Option + B | Toggle Diff review panel | Open and close to review edits |
Cmd + G | Search historical threads | Find past tasks |
Cmd + F | Find in current thread | Note: searches only the current thread, not globally |
Cmd + , | Open settings | Adjust themes, Git, and MCP configurations here |
Ctrl + L | Clear terminal | Avoid using Cmd + K (opens the command menu) |
Ctrl + M | Voice input | Hold to speak, converting voice to text |
Note: Searching historical threads (
Cmd + G) and "finding in current thread" (Cmd + F) are different—the former searches across all threads for past conversations, while the latter searches text in your currently active thread. Do not mix them up.
Now about slash commands (slash commands). Typing / in the input box brings up a menu of shortcuts to control Codex. The official list:
| Slash Command | Action |
|---|---|
/status | View current thread ID, context usage, and quota limits |
/review | Start code review mode, reviewing uncommitted changes or comparing branches |
/plan | Toggle plan mode (on/off) for multi-step planning |
/goal | Set a goal for Codex to achieve (use /plan to outline it first) |
/mcp | Check the status of connected MCP servers |
/feedback | Submit feedback (optionally attaching logs) |
Note: Typing
$in the input box allows you to invoke Skills; enabled Skills also appear in the slash command menu. If/goalis missing from your menu, you may need to enable it viafeatures.goals = trueinconfig.tomlor runcodex features enable goals(subject to official guidelines).
My most common command is /status—when running a long task, running it checks how many tokens have been burned and how much quota is left. Since Codex quota is billed by token (Article 04), /status is your fuel gauge.
💡 Summary in one sentence: If you can't remember all shortcuts, memorize
Cmd + K(command menu to run anything) andCmd + N(new thread); in slash commands,/statusfor usage and/reviewfor code reviews are the most valuable; Windows shortcuts must be checked locally.
07 Hands-on: Opening and Running Your First Parallel Task
Reading is not enough. Let's walk through the minimal flow for the Desktop App's unique features—opening two parallel threads, isolating them with Worktree, and reviewing changes via the review panel.
Prerequisite: You have installed the Desktop App as described in Article 03 and logged in with a ChatGPT account. Choose a small project you are familiar with, and make sure it is a Git repository (Worktree and the review panel rely on Git).
Step 1: Add Project, Select Worktree Mode
Click New Thread / Add Project in the left sidebar, and select a Git repository folder. Below the input box, select Worktree mode (not Local).
✅ Check: You should see the mode switch to Worktree, prompting you to choose a starting branch (like main or the current branch). If it says "Git repository required" → the folder you selected has not been initialized with Git; run git init or choose a different repository.
Step 2: Send the First Command
Type a small, specific task in the input box, for example:
Locate a TODO comment and implement itor:
Add a section on "How to run locally" to the READMEPress Enter. Expected behavior: Codex creates a Git worktree copy based on your starting branch and begins working there—your main working directory remains completely untouched.
Step 3: Open a Second Parallel Thread
Without waiting for the first task to finish, click New Thread again in the left sidebar, select Worktree mode, and send a different, unrelated task:
Clean up all console.log debug statements in the project✅ Expected behavior: The left sidebar now lists two threads running in independent worktree copies, completely isolated. This is the core advantage of the App—two tasks modifying the same project without interfering with each other. You can click between them to monitor progress.
Step 4: Review Changes in the Review Panel
Select one of the completed threads and open the Diff review panel on the right (macOS: Cmd + Option + B, Windows: check local settings). You will see which files were modified and which lines changed.
Try these verification actions:
- Hover over a line → click
+: A comment box pops up; write a comment (like "add a comment here"), submit it, and prompt the thread: "edit according to the inline comments." Verify if Codex applies the change. - Stage / Revert by hunk: Stage parts you like, and discard parts you don't.
✅ Expected behavior: Before you click Stage / Commit, Codex's changes remain in the worktree copy—commit/push only when you are satisfied, or roll back block-by-block. This "edit first, review before applying" flow is what makes the Desktop App safe.
Step 5 (Optional): Hand Off the Thread to Local
If you are satisfied with the edits in a worktree and want to bring them into your main directory to continue in your familiar IDE, click Hand off at the top of the thread and select Local. Codex will handle the Git operations under the hood.
✅ Expected behavior: The thread and code move into your Local directory, and you can open them in your IDE. Note: files in .gitignore are not copied over (Handoff uses Git operations).
By this step, you have run through the core pipeline of the Desktop App: parallel threads → Worktree isolation → visual review → handoff. This is an experience the CLI cannot replicate. Watching two Codex agents work in separate copies without conflicts is a great demonstration of a workbench.
💡 Summary in one sentence: Open parallel Worktree threads → wait for completion → use the review panel for line-by-line comments or hunk rollbacks → commit when satisfied. Running this once will lock the App's workflow into your muscle memory.
08 Summary
This article has explored the Desktop App entry of Codex:
- Its Positioning: Not a simplified CLI; the same Codex inside a shell optimized for parallelism and visualization, sharing
AGENTS.md, MCP, and Skills. - Installation: macOS and Windows only (Linux is waiting); log in with a ChatGPT account to avoid grays, as API keys disable some features.
- Three Columns: Left nav selects, middle area prompts, right panel reviews; Projects edit code, Chats are only for conversations.
- Three Modes: Local directly edits the main folder, Worktree creates isolated copies for tasks (essential for parallel work, copies Git files only), and Cloud runs remote tasks.
- App Advantages: Visual reviews (inline comments + block rollback + PR creation), shared built-in terminal, Actions buttons, and Automations.
- Shortcuts / Slash Commands: Memorize
Cmd + K,Cmd + N,/status, and/review; Windows shortcuts must be checked locally.
You should now be able to run the Desktop App on Mac or Windows, understand the columns, run parallel threads isolated with Worktrees, and use the review panel to comment on and accept edits. Mastering parallelism will stop you from feeling overwhelmed when handling multiple tasks.
The next article 08 · Getting Started with the CLI: since the Desktop App is so convenient, is the CLI still worth learning? The answer is: for scripting, server access, and CI pipelines, the Desktop App cannot help; the CLI is the only tool for the job. The next article returns to the terminal to cover the codex command, interactive modes, and automation—mastering both lines is the key to using Codex completely.