Codex worktrees: run several Codex agents in parallel

To run Codex in a worktree in the Codex app, pick Worktree under the composer, choose the branch to start from and send your prompt. Codex makes a git worktree under $CODEX_HOME/worktrees and works there, so your own checkout stays as it was. In the Codex CLI, codex --worktree starts a session in a managed worktree, on by default from version 0.156.0.

Each worktree is a separate checkout, so you can start several Codex chats on one repository and none of them edits the files another is working on. Everything below comes from OpenAI's worktrees page, its CLI reference and the Codex release notes on GitHub, all read on 24 October 2026.

Worktrees in the Codex app#

OpenAI now documents the Codex app as Codex inside the ChatGPT desktop app. The worktree steps are short:

1. Open a new chat in a project that is a git repository. Worktrees don't work outside one, because they are git worktrees under the hood.
2. Under the composer, select Worktree.
3. Below the composer, choose the branch the worktree should start from.
4. Optionally pick a local environment, whose setup script runs in the new worktree (installing dependencies, for example).
5. Send the prompt. Codex creates the worktree and starts working in it.

Start a second chat the same way and you have two Codex agents working in parallel, each in its own folder.

Three details are easy to miss. First, the worktree is in detached HEAD: it isn't checked out as a branch, which OpenAI says "lets Codex create several worktrees without polluting your branches". When you want to keep the work, press Create branch here in the chat header. Second, a worktree only holds tracked files. Codex copies gitignored files into it only when they match a .worktreeinclude file, so list your .env there (don't list tracked files). It also copies an ignored AGENTS.override.md by itself. Third, git lets one branch be checked out in only one place: a branch checked out in a worktree can't be checked out in your local checkout at the same time.

The worktrees go in $CODEX_HOME/worktrees (~/.codex/worktrees unless you've set CODEX_HOME). To put them somewhere else, change Worktree root in Settings › Worktrees.

Handoff: moving a chat between Local and a worktree#

OpenAI calls your own checkout Local (the foreground) and a worktree the background. Hand off, in the chat header, moves a chat between the two. Codex does the git work needed to carry the changes across safely.

That gives you two ways to check what a worktree chat did. You can stay in the worktree and test there, which works best when a local environment's setup script has installed your dependencies in it. Or you hand the chat off to Local and review the changes in your usual editor, with your usual dev server. Hand it back and it returns to the same worktree, because each chat keeps its worktree over time.

Cleanup: the newest 15, with snapshots#

By default the app keeps your 15 most recent Codex-managed worktrees. You can change the number, or turn automatic deletion off, in settings.

A worktree is deleted when you archive its chat, or when Codex needs room to stay under the limit. It is never deleted while a pinned chat uses it, while its chat is still running, or when it is a permanent worktree. Before deleting one, Codex saves a snapshot of the work on it, and when you open a chat whose worktree is gone, it offers to restore it.

For a long-lived setup, create a permanent worktree from the three-dot menu on a project in the sidebar. Permanent worktrees are never deleted automatically, and several chats can start from the same one.

Codex CLI worktrees: --worktree and /worktree#

The CLI got its own worktree support in Codex CLI 0.154.0, released on 9 September 2026, as an experiment: "create isolated checkouts for new or forked sessions using --worktree or /worktree, then browse and resume them". Version 0.156.0 turned it on by default, and 0.164.0, released on 23 October 2026, retired the worktree feature flag. Check your version with codex --version.

codex --worktree                               # new interactive session in a managed worktree
codex fork <SESSION_ID> --worktree             # fork a saved session into one
codex exec --worktree "add tests for the parser"   # non-interactive run in one

Inside a session in a local git repository, /worktree creates a managed worktree and starts the chat there. It also reopens worktrees Codex already made, with the chats that own them. It isn't available while a task is running.

The reference sets a few limits. --worktree needs local execution. codex fork --worktree needs an explicit session ID, so --last and the picker don't work with it. codex exec --worktree can't be combined with resume, review, --ephemeral or --ignore-user-config. And the reference doesn't say where the CLI puts these worktrees.

To see your chats in one place, codex agents (or /agents) opens the command center: the chats on a shared local or remote Codex server, with their status. Since 0.156.0 you can start worktree sessions from there too.

The manual way: git worktree add and one codex per folder#

On an older CLI, or if you want the folders and branches named your way, plain git does the job, and it works for any agent:

git worktree add ../myapp-api -b codex/api
git worktree add ../myapp-login -b codex/login

codex --cd ../myapp-api        # terminal 1
codex --cd ../myapp-login      # terminal 2

git worktree list

--cd (or -C) sets the folder Codex works in, so you don't have to cd first. Each new folder is a fresh checkout: install dependencies in it and copy your .env over, because neither is tracked. If two worktrees start the same dev server, give each its own port.

A session started in a worktree belongs to that folder, so codex resume --last run from inside it brings that chat back. The other options, including --all for sessions from other folders, are in resuming a Codex CLI session.

Subagents are not worktrees#

Codex also runs several agents inside one session: subagents. You ask for them in a prompt ("Spawn one subagent for security risks, one for test gaps…"), and /subagents in the CLI switches between their threads. OpenAI's subagents page says current releases have them on by default (agents.enabled), and agents.max_concurrent_threads_per_session caps how many run at once.

They solve a different problem. Subagents inherit the session's sandbox, and the page doesn't say they get a checkout of their own. OpenAI suggests starting with read-heavy work (exploring, tests, triage, summaries) and warns that "agents editing code at once can create conflicts". When two tasks both change code, separate chats in separate worktrees keep their edits apart until you merge.

Merging the work back#

In the app, a worktree chat ends one of two ways. Press Create branch here, then commit, push and open a pull request. Or hand the chat off to Local and commit from your own checkout.

By hand, from your main checkout:

git merge codex/api                    # or open a pull request from the branch
git worktree remove ../myapp-api
git branch -d codex/api

A worktree in detached HEAD, as Codex app worktrees start, needs a branch first: run git switch -c <name> inside it. Merge one branch at a time and rebase the next on top, so a conflict shows up in one place. Two agents that changed the same lines will still conflict, worktrees or not.

Parallel chats and your Codex limits#

Running chats in parallel doesn't give you more usage. OpenAI's pricing page says "Local messages and cloud chats share your plan's usage allowance", so every Codex chat on one ChatGPT account draws from the same allowance, whatever checkout it runs in. The subagents page adds that subagent workflows "consume more tokens than comparable single-agent runs". What each plan allows, and when it resets, is in our dated page on Codex usage limits.

How Shuriken does it#

Shuriken runs Codex chats the way it runs Claude Code chats. On the New chat screen, pick Own branch under Works in and the chat gets its own branch in its own git worktree. Project folder is the default, and the pick applies to that one chat only. Shuriken sets no cap on how many run at once: your machine and your plans do. Pick Codex for one chat and Claude Code for the next, and both work the same repository side by side (Claude Code and Codex in one project shows how we split work between them).

A new own branch runs the worktree.setup commands from your shuriken.json. With none written, it installs from your lockfile (npm ci, pnpm install --frozen-lockfile and the like), so the first build doesn't fail on missing dependencies.

Finish in the chat header brings the work home. It waits for the turn to end, commits what's left, rebases onto your default branch, runs the checks you list in shuriken.json and squash-merges, then archives the chat and removes its worktree and branch. With a GitHub remote it can open a pull request with auto-merge instead. If a rebase conflicts or a check fails, the chat's own agent gets the job of fixing it, up to three times. Finishes in one repository run one at a time, so the second chat merges on top of the first. The parallel agents page has the rest, and Shuriken vs the Codex app compares the two side by side.

Parallel chats reach a limit sooner. Shuriken answers that with hot swapping: it moves your chats to another of your accounts or sources when one nears its limit. Once a ChatGPT account reaches your switch point (99% by default), its Codex chats move to another of your ChatGPT accounts when their current turn ends. Add only accounts you own and are entitled to use; providers' terms may not allow sharing a subscription sign-in. The same worktree method for Claude Code, with its own flag, is in how to run Claude Code agents in parallel. To have the worktrees made, merged and cleaned up for every agent you use, download Shuriken.