Codex desktop app: parallel threads, worktrees and review

The Codex desktop app is the graphical client for the Codex agent on macOS and Windows: one window that runs several threads per project, each in your checkout, a Git worktree or a cloud environment. It shares ~/.codex/ with the CLI and IDE extension. Parallel threads pay off only when each one ends in gates you can check.

You have three tasks on one feature: an interface change, the tests for it and the docs. In the terminal you would run them one after another, or juggle three shells and hope they do not edit the same files. In the app you can start all three before lunch, but you come back to three diffs, three summaries that all say “done”, and no quick way to tell which one is true. This page is for the developer who uses the app every day, and for the tech lead who wants the team’s app threads to meet the same bar as terminal work.

What a verified parallel-thread setup in the Codex app gives you

A decision table for running each thread locally, in a worktree or in the cloud.
A three-thread pattern for one feature, with copy-paste prompts that end in evidence rather than a summary.
A verification routine that checks each thread with your own gates and codex review before you read any code.
The Git steps that bring worktree work back to a branch without the “already checked out” error.
A permission posture for app threads and automations, and fixes for the ways the app goes wrong.

Where does the desktop app fit next to the CLI and the IDE extension?

All three clients drive the same agent and read the same Codex home directory (~/.codex/, or CODEX_HOME), so sign-in, config.toml, MCP servers and skills carry over. Install and version details live in Install Codex.

Client	Reach for it when	How you get there
Desktop app (macOS, Windows)	You run several threads at once, review diffs visually, check UI work in a browser or schedule recurring jobs	`codex app` launches it, or opens the installer if it is missing
CLI / TUI	You want scripts, `codex exec`, precise flags, or you are on Linux	`codex`; see CLI and slash command tips
IDE extension	You are editing and want Codex beside the file	The Codex panel in VS Code or Cursor

Two bridges connect them. In the TUI, /app continues the current session in the desktop app, and /ide pulls the current selection and open files from your editor. codex agents browses the agent sessions on the shared local app-server daemon.

The app now ships as the Codex mode of the ChatGPT desktop app, beside Chat and Work. Neowin (secondary source) dates that change to 2026-07-09. OpenAI’s README still calls it the Codex App, and on macOS codex app opens either ChatGPT.app or Codex.app. Linux has no build: the Linux CLI has no app subcommand (checked on codex-cli 0.157.1).

Several capabilities the app exposes are listed as stable and on in the feature registry of codex-cli 0.157.1: in_app_browser, computer_use, in_app_dictation and in_app_local_automation. codex features list prints the registry on your machine.

Choose where each thread runs: local, worktree or cloud

Every new thread starts in one of three places. The choice decides what the thread can touch and what you have to do afterwards to keep its work.

Run the thread	Use it for	What it costs you
Local, in your checkout	Questions about the code, small edits to files you are already changing, work that must see your uncommitted changes	Two local threads that edit the same files collide, and the changes land in your working tree unreviewed
Worktree, in its own Git worktree	Features, experiments you may discard, anything you run in parallel	You bring the work home through Git, and each worktree needs its own dependency install
Cloud, in a configured environment	Long or heavy tasks, tasks that need a clean machine, best-of-N attempts on a risky fix	It needs a cloud environment and cannot reach local-only services

OpenAI’s worktree documentation puts the purpose in one line: “Worktrees let Codex run multiple independent chats in the same project without interfering with each other” (learn.chatgpt.com, read 2026-08-28). The rule that follows: at most one local thread per project writes files; everything else that writes goes to a worktree or the cloud. Worktree mechanics on every surface, including cleanup, are in Isolated Codex tasks with Git worktrees.

Start a worktree thread from a clean base. A worktree checks out the base branch as committed, so uncommitted edits in your checkout are not in it. Commit or stash first when the thread needs them.

Run one feature as three parallel threads

The pattern that works best in the app splits one feature into implementation, tests and docs. The implementation and the tests each get a worktree on the same base branch; the docs get a local thread because they do not conflict with code.

Write the acceptance criteria once. Put three to five checkable statements in a file the threads can read, for example specs/user-id.md. Each thread’s prompt points at the file instead of restating it, so the three threads cannot drift apart.
Start the implementation thread in a worktree. Paste the first prompt below.
Start the test thread in a second worktree on the same base branch. It writes tests against the criteria, not against the implementation it cannot see yet. Tests written this way fail for the right reason until the implementation lands.
Start the docs thread locally. It edits only docs/, so it cannot collide with the worktrees.
Keep working while they run. Check the threads when they finish or ask for approval. When a thread heads the wrong way, send a correction in the same thread rather than starting over, because the thread keeps its context.
Verify, then merge. Run the routine in the next section on each worktree, bring both branches home, and run the full suite once on the combined result.

Implement the change described in specs/user-id.md: UserService accepts a generic ID type
instead of a numeric id. Update every direct consumer in packages/core. Do not touch tests
or docs; other threads own them.

Work in small steps. After each step run `pnpm typecheck` and fix what it reports.
When you finish, run `pnpm typecheck && pnpm lint && pnpm test --filter core` and reply with:
1. Each acceptance criterion from specs/user-id.md and the file:line that satisfies it.
2. The exact commands you ran and their final exit codes.
3. Anything you could not do, and why.
Do not say "done" if any command failed.

Write tests for the behaviour in specs/user-id.md. Follow the patterns in
tests/integration/ and reuse the fixtures in tests/fixtures/. Write one test per acceptance
criterion and name each test after the criterion it proves.

The implementation is being written in another branch, so these tests are expected to fail
now. Run them and show me that each one fails with an assertion about the missing behaviour,
not with an import error, a typo or a timeout. Do not change any file under src/.

The test thread’s instruction to fail for the right reason is what makes its output worth anything: a test that already passes before the implementation exists proves nothing. When you combine the branches, the same tests must turn green.

How do you verify a thread’s work without reading every line?

A thread’s summary is a claim. Evidence decides whether you keep the work, and you read only the lines the evidence cannot cover. Run this routine in each worktree before you bring it home:

Run your own gates in the thread’s directory. Use the same commands CI runs. The agent reporting that tests passed is not the same as your terminal showing it.

# in a terminal, inside the thread's worktree (git worktree list prints its path)
pnpm typecheck && pnpm lint && pnpm test
git status --short          # anything unexpected, such as a changed lockfile?

Run a separate review pass. codex review --uncommitted reviews staged, unstaged and untracked changes with instructions to find defects, not to defend the code. Use codex review --base main once the work is committed on a branch. Triage and prompts for this pass are in Review Codex’s changes before you commit.
Map the criteria to evidence. Each acceptance criterion needs a test that fails without the change. Criteria with no test are the lines you read yourself.
Review the diff in the app, not the summary. Review the thread’s diff in the app. Keep what the evidence covers, revert what it does not, and reply in the thread with what to change.

Before I merge this thread, prove it. Run `pnpm typecheck && pnpm lint && pnpm test` and paste
the last 20 lines of output. Then list every file you changed with one line on why. For each
acceptance criterion in specs/user-id.md, name the test that fails without your change, then
temporarily revert that change, run the test to show it fails, and restore it.
Flag any change you made outside packages/core.

Who signs off: the developer who started the thread owns the merge; the gates and the review pass are the evidence they sign off on. For a tech lead, the rule to write into AGENTS.md is that no app thread merges on its summary alone. The evidence bundle guide shows how to attach that proof to the pull request.

Bring worktree work home through Git

Git allows a branch to be checked out in only one worktree at a time. If a worktree thread created codex/user-id and you run git switch codex/user-id in your main checkout, Git refuses with an “already checked out” error, because the worktree still holds that branch. You have two ways home:

Keep it on its branch. Commit in the worktree, push the branch and open a pull request; the terminal version is below. Choose this when you can verify everything inside the worktree.
Bring it into your checkout. Merge or cherry-pick the worktree’s commits into a branch in your main checkout. Choose this when you can run only one copy of the app locally, for example because it binds a fixed port.

# in the worktree: name the branch, commit and push
git switch -c codex/user-id        # skip if the thread already created a branch
git add -A && git commit -m "Accept a generic ID type in UserService"
git push -u origin codex/user-id

# or, from your main checkout: take the commits without checking out the branch
git merge --no-ff codex/user-id

Once its work is merged, archive the thread and remove its worktree (git worktree remove <path>); a worktree left on disk keeps its own copy of the files plus every dependency and build artefact the thread installed.

Check UI work with screenshots, the browser and voice

The app earns its place over the terminal on visual work. Attach a screenshot of the broken layout to the prompt and describe what should change; in the CLI, codex -i screenshot.png "..." does the same. The in-app browser lets the thread load your local dev server and check its own change, which turns “it should look right” into something the thread can observe.

The attached screenshot shows the checkout page at 375px wide: the "Pay now" button
overlaps the order summary. Find the cause in src/components/checkout/. Fix it without
changing the desktop layout. Then start the dev server with `pnpm dev`, open
http://localhost:3000/checkout in the in-app browser at 375px and 1280px, and describe what
you see at each width. Add a Playwright test in tests/e2e/checkout.spec.ts that fails on
the overlap and passes after your fix.

Dictation is on in the app (in_app_dictation in 0.157.1) and suits long descriptions of visual problems. It handles code names poorly, so edit identifiers in the transcript before you send it. The TUI has its own /voice command; cross-tool voice setups are in voice input for coding agents.

Use skills and automations from the app

Skills load from the shared Codex home ($CODEX_HOME/skills, ~/.codex/skills by default), so the app sees the same personal skills as the CLI. To call one explicitly, name it with a $ prefix in the prompt, for example $skill-creator, one of the sample skills bundled with Codex. Keep team skills in the repository so a change to a skill goes through code review. Finding and vetting skills is covered in installing and managing skills, and plugin marketplaces (codex plugin marketplace add) in plugin marketplaces and registries.

Automations run a saved prompt on a schedule, in your checkout or a dedicated worktree, and report back in the app. They run only while the app is open and the machine is awake. Test the prompt by hand first, give it the narrowest permissions that work, and make it report rather than change code until you trust it. The full setup, including thread automations and a CI fallback for jobs that must run when your laptop is off, is in Codex automations.

Read-only task. Do not edit files, commit or push.
Run `pnpm test` and `pnpm lint` on the default branch. For each failure, report:
the test or rule name, the file:line, the most likely cause in one sentence, and whether the
failure also occurred in yesterday's report in this thread. If everything passes, reply with
exactly "No failures." and nothing else.

Set the permission posture for app threads

The app reads the same config.toml as the CLI, so set its posture there. OpenAI’s preferred mechanism is permission profiles (beta, Codex CLI 0.138.0 and later): built-ins :read-only, :workspace and :danger-full-access, plus named profiles you define. A custom profile can extend :read-only or :workspace only; codex-cli 0.157.1 rejects any other built-in parent.

# Top-level keys must come before any [table], or TOML assigns them to that table.
default_permissions = "review"

[permissions.review]
description = "Review and triage: read the repo, write nothing"
extends = ":read-only"

Switch posture for one TUI session with /permissions, or for one run with -c default_permissions=":workspace". Do not combine a profile with the legacy --sandbox flag: OpenAI says the two systems “do not compose”. Keep :danger-full-access for disposable, network-restricted sandboxes, never for an automation on your laptop. The cross-tool model is in permissions and sandboxes, and every config.toml key in Codex configuration.

When the Codex desktop app breaks

Two local threads overwrote each other. Both edited the same file in your checkout. Recovery: git diff to see the combined state, git restore -p to drop the hunks you do not want, then rerun one of the tasks in a worktree. Prevention: one writing local thread per project.

A worktree thread is missing your latest changes. They were uncommitted when the thread started, and a worktree sees only committed history. Recovery: commit or stash, then start a new thread from the updated base; do not ask the old thread to “pull in” your edits.

git switch fails with “already checked out”. The worktree still holds the branch. Recovery: work on the branch inside the worktree, or merge it from your checkout with git merge --no-ff codex/BRANCH as shown above.

The thread says tests pass, but they fail for you. It ran a subset, used a different command, or ran before its last edit. Recovery: paste your failing output into the thread and ask it to rerun the exact CI command and show the exit code. Put that command in AGENTS.md so every thread uses it.

A long thread starts ignoring the spec. Earlier turns, corrections and tool output crowd out the instructions you gave first. Recovery: start a new thread that points at the spec file and at the current diff, instead of repeating corrections in the old one.

The app does not see your MCP servers, skills or settings. It reads a different Codex home from the CLI, usually because CODEX_HOME is set in your shell profile but not for the app. Recovery: set CODEX_HOME the same way for every client, or leave it unset everywhere so all of them use ~/.codex/. codex doctor shows what the CLI reads.

An automation never ran or reported nothing. The app was closed or the machine slept. Recovery: move jobs that must run overnight to a CI schedule, as described in Codex automations.

The disk fills up. Old worktrees keep dependencies and build output. Recovery: run git worktree list to find the worktrees whose work is merged, delete each one with git worktree remove <path> (this is what frees the disk), then run git worktree prune to clear entries whose directories were removed by hand.

Where to go next with the Codex desktop app

Codex multi-agent workflows: split a larger feature into lanes and gate each lane before merging.
Codex cloud environments: set up the environment that cloud threads and best-of-N attempts run in.
Review Codex’s changes before you commit: the review loop this page’s verification routine builds on.
Codex automations: recurring jobs with tested prompts and tight sandboxes.