Codex CLI 0.154 managed worktrees: isolate parallel sessions without losing branch or permission evidence
Quick answer
Codex CLI 0.154.0 adds experimental managed-worktree support for starting, forking, and resuming sessions. The official release notes expose --worktree and /worktree; a clean 0.154.0 package check also shows the flag on the main, fork, and resume command surfaces.
Treat this as checkout isolation, not a security boundary. Before moving real work, verify the executable, capture the repository's starting state, test tracked, untracked, and ignored-file behavior in a disposable repository, and re-check sandbox and approval settings after every fork or resume.
Who this is for
This checklist is for developers running parallel Codex sessions against one Git repository and teams deciding when a task should use the current checkout versus an isolated worktree.
If your main risk is nested-agent cost accounting rather than checkout isolation, use the Codex subagent token-budget checklist. For approval automation, use the Approve for me safety checklist.
What changed—and what remains unproven
| Boundary | What is confirmed | Rollout rule |
|---|---|---|
| Codex CLI 0.154.0 | New and forked sessions can use --worktree or /worktree; saved sessions can be browsed and resumed in a worktree |
Pin and print the actual binary version before each canary |
| OpenAI desktop worktree docs | Managed worktrees are separate Git checkouts; desktop sessions start detached, can use Handoff, and may copy selected ignored files through .worktreeinclude
|
Use this as desktop guidance, not proof of identical CLI behavior |
| Git branch ownership | One branch cannot be checked out in two worktrees simultaneously | Record each worktree path, HEAD, and branch before integrating changes |
| Permissions | A worktree changes the checkout location, not the sandbox or approval policy | Revalidate denied actions; never infer narrower authority from a new directory |
| Cleanup | Desktop-managed worktrees have snapshot and recovery behavior | Do not assume the same CLI cleanup contract until your canary proves it |
The local default executable checked for this article was still 0.145.0 and did not expose --worktree; a clean @openai/codex@0.154.0 invocation did. That is exactly why “the package was upgraded” is weaker evidence than “this process printed 0.154.0 and this help surface contains the flag.”
A safe rollout workflow
1. Prove the executable
Run these checks from the shell that will launch the session:
command -v codex
codex --version
codex --help | grep -A2 -- --worktree
codex fork --help | grep -A2 -- --worktree
codex resume --help | grep -A2 -- --worktree
Stop if the path or version differs from the artifact you intended to test. Shell aliases, old global installs, and long-running terminals can otherwise turn a feature test into a test of the wrong binary.
2. Capture a starting-state manifest
Before launching a managed worktree, store this small record outside the task's output directory:
repo:
base_ref:
head_sha:
branch:
dirty_tracked:
untracked:
ignored_runtime_inputs:
sandbox:
approval_policy:
session_id:
Do not put secret values in the manifest. Record only the presence and intended provider of ignored runtime inputs.
3. Use a disposable fixture first
Create a small Git repository with four canaries: a committed file, a modified tracked file, an untracked file, and an ignored non-secret fixture. Launch a new 0.154 session with --worktree, then ask it to report which canaries exist without changing them.
This distinguishes facts the release announced from behavior your environment actually delivered. In particular, OpenAI's desktop documentation says .worktreeinclude copies selected ignored files into local app-managed worktrees, but that page explicitly does not describe command-line-created Git worktrees. Test the CLI behavior instead of copying a production secret just to see whether it appears.
4. Test start, fork, and resume separately
Use one reversible task per surface:
| Surface | Canary | Required evidence |
|---|---|---|
| New session | Edit one committed fixture | Worktree path, starting HEAD, final diff |
| Fork | Create a second, different edit | New session identity and no cross-write into the first checkout |
| Resume | Reopen the saved task in a worktree | Correct conversation, repository, HEAD, and permission settings |
In-session /worktree
|
Follow the displayed transition | New checkout identity plus preserved task context |
A resumed transcript is not sufficient evidence. The conversation can be correct while the checkout, branch, or permissions are wrong.
5. Reconcile Git ownership
Inside every checkout, capture:
git status --short --branch
git rev-parse --show-toplevel
git rev-parse HEAD
git worktree list --porcelain
Expect a branch conflict if another worktree already owns the branch you want. Do not “fix” that by deleting a worktree whose session still has uncommitted changes. Integrate through an explicit commit, branch, or patch review that preserves author, base SHA, and final diff evidence.
6. Re-test authority, not just files
Run a harmless allowed write and a deliberately denied action. Confirm the same sandbox roots, network boundary, and approval behavior expected by policy. Repeat after fork and resume.
The 0.154 release also contains permission-preservation fixes for remote resume and fork, but that does not make a worktree a permission control. Treat checkout isolation and execution authority as two independent gates.
7. Close with recoverable evidence
Before archiving or removing anything, preserve the session identifier, worktree path, HEAD SHA, git status, complete diff, and integration result. If cleanup behavior is undocumented for the CLI path you used, keep the canary small and recoverable rather than inferring the desktop app's retention rules.
Decision tree
Does the active binary print Codex CLI 0.154.0 or newer?
no -> stop; fix the executable path
yes -> is the task safe for a disposable canary?
no -> keep the existing workflow
yes -> capture the starting-state manifest
launch with --worktree
checkout, branch, and permissions all match?
no -> preserve evidence and stop promotion
yes -> test fork and resume independently
every diff attributable and recoverable?
no -> keep the feature experimental
yes -> expand one low-risk task class at a time
Common mistakes
- Calling the feature stable when the official release labels it experimental.
- Assuming desktop detached-HEAD,
.worktreeinclude, Handoff, or cleanup details are identical in the CLI. - Treating a separate checkout as a sandbox or permission reduction.
- Testing only committed files and discovering missing ignored runtime inputs during real work.
- Resuming the right conversation in the wrong repository or branch.
- Removing a worktree before capturing the diff and session identity.
- Letting two parallel sessions edit the same responsibility without an integration owner.
Building something? Turn your product page into a show people want to watch with PromoFast—hosted, embeddable, and ready to export.
FAQ
Is --worktree available in every Codex CLI install?
No. It arrived in 0.154.0. Verify the executable and help output used by the actual process instead of relying on a package-manager record.
Does a managed worktree copy .env files?
Do not assume it. The OpenAI desktop app documents .worktreeinclude for selected ignored files, while the CLI release notes do not establish the same copying contract. Use a non-secret ignored fixture to test your path.
Can two worktrees use the same branch?
Git prevents the same branch from being checked out in more than one worktree. Keep branch ownership explicit and integrate changes deliberately.
Does a worktree make a session safer?
It reduces checkout collisions. It does not automatically narrow filesystem, command, network, or approval authority; those controls require separate verification.
Sources
- Codex changelog — Codex CLI 0.154.0
- OpenAI Codex worktrees documentation
- Codex CLI 0.154.0 GitHub release
Originally published on IndieSeek.
Top comments (0)