CLI: add --worktree and --tmux flags for one-command isolated sessions

I have already implemented the codex --worktree feature in https://github.com/scharalambous3/codex
Curious to hear your thoughts - I'm open to feedback!
I also plan to implement the background terminal session soon, too

What is the progress on this?

I think this is the right umbrella issue for making git worktrees a first-class CLI workflow.

codex --worktree [name] would already remove a lot of shell glue, but I want to add one closely related pain point: moving between existing worktrees still requires leaving the current Codex session, cd-ing manually, and starting/resuming again.

From a user perspective, the ideal direction is:

• startup convenience: codex --worktree [name]
• in-session convenience: switch the active cwd to another existing worktree without restarting the conversation

I am not attached to a specific command shape (/cwd, /worktree switch, etc.). The important part is making worktree-based isolation feel native in the CLI.

Related discussions:

• #12464
• #15935

Is there any progress on this feature as the desktop app has already supported it?

bump

Bumping this - important differentiator for Claude Code right now for power users

Bumping this - important differentiator for Claude Code right now for power users

Exactly! Bump

bump

How many 👍 does this need to enter dev focus?

Also, please don’t forget .worktreeinclude -- otherwise this lands pre-half-baked. 🙂

bump

It can be quite disappointing if OpenAI takes such a common feature so lightly.

bump
lets use those tokens wisely

+1. This is one of the first things I ended up scripting for Codex CLI.

For anyone who wants a shell workaround today, here’s a small zsh helper. I personally alias it as gwt, but the long name makes the intent clearer: create or reuse a git worktree, cd into it, then always launch Codex with the remaining args forwarded unchanged.

codex_worktree() {
  if [[ $# -lt 1 ]]; then
    echo "usage: codex_worktree <name> [codex args...]" >&2
    return 2
  fi

  local name="$1"
  shift

  if ! git check-ref-format --branch "$name" >/dev/null 2>&1; then
    echo "codex_worktree: invalid branch name: $name" >&2
    return 2
  fi

  local repo_root
  repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
    echo "codex_worktree: not inside a git repository" >&2
    return 1
  }

  local worktree_path="$repo_root/.codex/worktrees/$name"
  mkdir -p "${worktree_path:h}"

  if [[ -e "$worktree_path/.git" ]]; then
    cd "$worktree_path" || return
  elif git show-ref --verify --quiet "refs/heads/$name"; then
    git worktree add "$worktree_path" "$name" && cd "$worktree_path" || return
  else
    git worktree add -b "$name" "$worktree_path" HEAD && cd "$worktree_path" || return
  fi

  command codex "$@"
}

Examples:

codex_worktree fix-login
codex_worktree fix-login "investigate failing CI"
codex_worktree fix-login --model gpt-5.5 "investigate failing CI"

This only covers the worktree startup flow, not tmux/session management. Native codex --worktree [name] would still be cleaner, especially if it standardized the worktree location and branch reuse behavior.

bump!

bump

Being an experienced Claude Code TUI user, every time I try to use Codex with work trees the same way it works with claude -w <foo>, I get frustrated, give up, and go back to Claude Code. This is basically the blocker preventing me from giving Codex a spin for any serious coding work. ChatGPT models might be good, but I can't experience any of that because of how frustrating the experience with Codex and work trees is.

And, BTW, if you ever end up implementing this feature, please implement it in a way so that it creates a work tree from the current local branch without copying unstaged/uncommitted changes. Basically, each newly created work tree is supposed to be a clean slate. For some stupid reason, when I tried asking Codex GUI to create a work tree, it copied unstaged/uncommitted changes over to the work tree — that's just so weird.

Bump

Adding a concrete reference: Claude Code documents first-class CLI worktree sessions here: https://code.claude.com/docs/en/worktrees

For Codex CLI, the key UX to match is --worktree/-w: start a session directly in an isolated worktree, allow an explicit name (--worktree <name>), and auto-generate a useful name when omitted. Codex App already supports worktree-backed sessions; the CLI is missing the equivalent one-command entrypoint.

It would also help to make the starting state explicit: create a clean new branch/worktree from a clean base with no staged/unstaged changes copied over, or opt into carrying the current branch context and staged/unstaged changes when desired. Both workflows are valid, and the CLI should make that choice clear.

Let me know when support for work trees lands. Then I might resubscribe to ChatGPT/Codex and give it another chance. For now, I'm stuck with Claude and have unsubscribed from ChatGPT/Codex.

First-class --worktree should probably record ownership, not only create a checkout.

The useful contract is: session id, worktree path, branch name, base ref, parent project, cleanup policy, and whether the worktree is reusable or single-turn. --tmux can then attach to the same owned session instead of becoming a parallel source of truth. That also gives the UI/CLI enough data to show which task owns which branch and avoid two agents mutating the same checkout accidentally.

I maintain Better Agent (https://github.com/ofekron/better-agent), where isolated worktrees and parent-visible task ownership are core to supervising Claude/Codex/Gemini sessions. If useful, a star helps other coding-agent workflow builders find it.