›_ Codex Issues
Codex Issues / #16531

Sync agent-created worktrees with the active Codex thread/UI context

Open 💬 3 comments Opened Apr 2, 2026 by waleed-salama
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

App

What feature would you like to see?

Summary

Please add first-class support for agent-created worktree handoff in the Codex App so the thread and UI stay synced with the actual worktree and branch the agent moved into.

Current behavior

Codex works well when I manually move a thread into a worktree, because the UI understands that the thread is now attached to a different workspace and branch context.

But when the agent itself creates a new git worktree and switches work there, the thread UI can remain attached to the original workspace and branch. That creates a mismatch between where the agent is actually working and what the Codex App thinks the thread is attached to.

What goes wrong

In my workflow, I had the agent:

  1. plan a Linear issue
  2. move it through Ready -> Todo
  3. start implementation
  4. create a dedicated branch and worktree
  5. continue coding in that worktree

The implementation itself worked, but the UX became inconsistent:

  • the thread UI still looked attached to the original workspace/branch
  • the Codex App did not clearly reflect that the agent had moved to a different worktree
  • reviewing diffs and following the implementation became harder than it should be
  • if I used the Codex UI to commit, push, or open a PR without asking the agent, it would operate on the local/original workspace instead of the worktree, so those UI flows became unusable

Why this matters

This weakens one of the main reasons to use worktrees in the app in the first place: isolated execution with good supervision, review, and follow-up Git actions from the UI.

The value proposition is strongest when the Codex App stays synchronized with the agent’s real execution context.

Requested behavior

When the agent creates a worktree and begins working there, the Codex thread/UI should update to reflect that new worktree and branch context.

At minimum, I’d like:

  • the thread to clearly show the active worktree path
  • the thread to clearly show the active branch for that worktree
  • diff review in the UI to follow the worktree the agent is actually using
  • app-level Git actions like commit, push, and PR creation to target the active worktree, not the original workspace

Possible implementation direction

Codex already appears to use structured app directives for git/UI synchronization, for example around branch creation, staging, commits, pushes, and PR creation.

A similar directive for worktree creation/handoff seems like a natural fit, for example:

::git-create-worktree{cwd="/abs/path/to/repo" worktree="/abs/path/to/worktree" branch="branch-name"}

More generally, any equivalent mechanism would be useful as long as it lets the app switch the thread’s active workspace context to the worktree the agent actually created and entered.

Additional information

This request is based on the workflow described here:
https://github.com/openai/codex/discussions/16440

A maintainer asked me on April 2, 2026 to file this as an enhancement request in the issue tracker so it can be prioritized via issue upvotes.

View original on GitHub ↗

3 Comments

github-actions[bot] contributor · 4 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • ##16525
  • # #15854
  • # #16290

Powered by Codex Action

shikyo13 · 4 months ago

Additional Windows Desktop repro, with project details redacted.

Environment:

  • Codex Desktop on Windows x64
  • Installed package observed locally as OpenAI.Codex_26.422.2437.0_x64__...
  • codex.exe file version observed as 0.124.0.0
  • Repository uses Git worktrees under <repo-root>/.worktrees/

What happened:

  1. Root checkout was restored to clean main while feature branches were already checked out in dedicated worktrees:
<repo-root>                       [main]
<repo-root>/.worktrees/<worktree-a> [<feature-branch-a>]
<repo-root>/.worktrees/<worktree-b> [<feature-branch-b>]
  1. A Desktop chat remained attached to the root checkout, even though the work the user wanted to continue lived in an existing worktree.
  1. Using the Desktop branch picker from the root checkout attempted to switch the root checkout onto a branch that Git correctly reports is already checked out by another worktree.

Observed user-facing error, sanitized:

Failed to switch branch: fatal: '<feature-branch>' is already used by worktree at '<repo-root>/.worktrees/<existing-worktree>'

Why this matters:

  • Git is behaving correctly here. The branch cannot be checked out in the root checkout because it is already checked out in its dedicated worktree.
  • The confusing part is Codex Desktop presenting the action as “switch to this branch” when the user actually needs “attach this chat/thread to the existing worktree path.”
  • This creates a high-risk workflow where root main, an existing feature worktree, and the Desktop diff/branch UI can all disagree.
  • The user sees dirty or stale diffs in the Desktop review panel even when git status says the actual root checkout is clean.

Verified local state at the time, sanitized:

$ git status --short --branch
## main...origin/main

$ git worktree list
<repo-root>                       [main]
<repo-root>/.worktrees/<worktree-a> [<feature-branch-a>]
<repo-root>/.worktrees/<worktree-b> [<feature-branch-b>]

Current workaround:

  • Keep <repo-root> on clean main.
  • Do not use the root branch picker for branches already checked out in worktrees.
  • Run commands with explicit cwd pointing at the desired worktree, or start a new chat directly from the worktree folder if the app exposes an open-folder flow.

Requested behavior:

  • If a selected branch is already checked out in a known worktree, Desktop should offer to attach or move the thread to that worktree instead of trying git switch in the current checkout.
  • The thread should clearly display the active filesystem root and branch.
  • The review panel, dirty badge, commit action, push action, and PR action should all target the attached worktree, not the original/root checkout.
  • The branch picker should distinguish “switch this checkout to branch” from “open existing worktree for branch.”
devansh-jain-18 · 2 months ago

Related current pain: #22316 covers the complementary user-facing workflow.

When a worktree already contains the desired filesystem/git/index state, there is no first-class way to start a zero-context/new transcript thread attached to that same existing worktree. Fork keeps old context, while New worktree creates a different checkout.

So in addition to keeping thread/UI context synced when worktrees change, it would help if the app exposed existing worktrees as addressable execution targets, or offered a "New thread here" / "clear context for this worktree" action from a worktree-backed thread.