Skip to content

feat(tui): codex-managed worktree workflow#21435

Draft
fcoury-oai wants to merge 3 commits intomainfrom
fcoury/worktrees
Draft

feat(tui): codex-managed worktree workflow#21435
fcoury-oai wants to merge 3 commits intomainfrom
fcoury/worktrees

Conversation

@fcoury-oai
Copy link
Copy Markdown
Contributor

Why

Codex users already work across multiple local Git worktrees, and the App can create managed worktrees under $CODEX_HOME/worktrees. The CLI/TUI did not have an equivalent first-class workflow: users had to create raw Git worktrees themselves, session lists could not distinguish App-managed workspaces from ordinary checkouts, and cleanup/removal lacked Codex ownership checks.

This PR adds a CLI/TUI-managed worktree flow that follows the Worktrunk-style sibling directory convention while still discovering App-created $CODEX_HOME/worktrees entries. That gives CLI users a predictable workspace location, lets the TUI label worktree sessions, and keeps removal constrained to Codex-owned worktrees.

What Changed

  • Added a new codex-worktree crate for Git worktree lifecycle behavior:
    • create/reuse sibling worktrees from --worktree <BRANCH>;
    • preserve relative cwd when starting from a repo subdirectory;
    • write/read Codex metadata in the Git metadata directory;
    • detect dirty state and support fail, ignore, copy-tracked, and copy-all policies;
    • list App, CLI-managed, and raw Git worktrees with source/location metadata;
    • refuse unsafe removal of non-Codex-managed worktrees.
  • Added shared CLI flags:
    • --worktree <BRANCH>
    • --worktree-base <REF>
    • --worktree-dirty <fail|ignore|copy-tracked|copy-all>
  • Added codex worktree list, path, remove, and prune subcommands.
  • Bound managed worktrees to thread ids after TUI/exec start, resume, and fork responses.
  • Added TUI worktree labels for startup context and resume/fork picker rows.
  • Kept App compatibility by discovering existing App worktrees under $CODEX_HOME/worktrees.

How to Test

  1. From a Git checkout, run:

    cargo run --bin codex -- --worktree fcoury/worktree-smoke --worktree-dirty ignore
  2. Confirm the session starts in a sibling worktree path like:

    ../codex.fcoury-worktree-smoke
    
  3. Run:

    cargo run --bin codex -- worktree list

    Confirm the output is column-aligned and includes SOURCE values such as cli, app, and git.

  4. Try removing a raw Git worktree shown as SOURCE git:

    cargo run --bin codex -- worktree remove <raw-git-branch>

    Confirm Codex refuses with refusing to remove a worktree not managed by Codex.

Targeted tests run:

  • cargo test -p codex-worktree
  • cargo test -p codex-cli
  • cargo test -p codex-tui
  • cargo insta pending-snapshots
  • just argument-comment-lint

Documentation

This adds user-facing CLI flags and codex worktree subcommands. The Codex CLI documentation on developers.openai.com should be updated before this ships broadly.

@fcoury-oai fcoury-oai changed the title Add Codex-managed worktree workflow feat(tui): Codex-managed worktree workflow May 6, 2026
@fcoury-oai fcoury-oai changed the title feat(tui): Codex-managed worktree workflow feat(tui): codex-managed worktree workflow May 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant