CLI: add --worktree and --tmux flags for one-command isolated sessions #12862
Description
What feature would you like to see?
Add first-class CLI flags to start Codex in an isolated git worktree and optionally attach it to tmux in one command, similar to workflows many users already script manually.
Proposed flags
codex --worktree [name]codex --tmux(requires--worktree)
Proposed behavior
--worktree [name]- Creates or reuses a worktree for the session.
- If
nameis omitted, generate one automatically. - Uses a predictable default location (for example,
.codex/worktrees/<name>) with a config override for root path. - Creates/checks out a branch for the worktree if needed.
--tmux- Requires
--worktree. - Starts/attaches a tmux session bound to that worktree and launches Codex there.
- Requires
- All non-custom arguments are forwarded unchanged to Codex.
Example UX
codex --worktreecodex --worktree fix-logincodex --tmux --worktree fix-logincodex --tmux --worktree fix-login "investigate failing CI"
Why this is useful
This removes repetitive shell glue and makes isolated, parallel task execution a first-class CLI workflow. Right now users commonly combine git worktree + tmux manually or via custom wrappers.
Related issues
- Use git worktrees to achieve parallel agents #8570 (Use git worktrees to achieve parallel agents)
- Background Terminal Sessions #3968 (Background Terminal Sessions)
- Add interactive session-management for Codex CLI: #6500 (Interactive session management)
This request is specifically about CLI flag parity for one-command startup in a new/existing worktree with optional tmux attachment.
Additional information
Happy to help test edge cases (existing branch, detached HEAD repos, repos with non-main default branches, tmux unavailable, etc.).