Review and Merge Workflow

What cmux does and does not do here

cmux has no merge command, no commit, and no push. It is a terminal, so git and gh do the git work exactly as they always did. What cmux adds is review surface: a diff viewer you can open from a script, and per-workspace git and PR metadata in the sidebar so you can see the state of ten branches at once.

Opening a diff

cmux diff renders a unified diff or a patch in a browser split.

cmux diff --unstaged
cmux diff --staged
cmux diff --branch
cmux diff --last-turn
git diff | cmux diff
cmux diff changes.patch
cmux diff -                       # read a patch from stdin

With no patch file and no source flag it reads piped stdin. The four named sources are also spellable as --source <name>.

--last-turn is the one that only exists because of agents: it diffs against the baseline captured at the start of the current turn, so you see exactly what this round of work touched. Scope it to one session with --session <id>.

Diff viewer options

cmux diff --branch --base upstream/main --repo ../other-checkout
cmux diff --branch --layout split --font-size 13 --focus true
cmux diff --unstaged --title "review: auth refactor" --no-focus

The default --no-focus behavior matters for automation. An agent that opens a diff after finishing should leave your focus where it was and let the notification pull you over.

Sidebar review signals

With sidebar.showPullRequests on, each workspace row carries the git branch, the linked PR number and status, the working directory, listening ports, and the latest notification line. That is the whole point of vertical tabs: ten rows, ten branches, one glance.

Turn watchGitStatus off if you are working in a very large repository and would rather not have the watcher running.

A review loop that works

One workspace per branch, one agent per workspace, and the sidebar as the queue.

# one workspace per branch, agent started with the workspace
cmux new-workspace --name "fix-auth" --cwd ~/code/api \
  --command "git switch -c fix-auth && claude"

# the agent finishes, notifies, and leaves a diff open
cmux notify --title "fix-auth ready" --body "12 files changed"
cmux diff --last-turn --no-focus

Then ⌘⇧U jumps to the latest unread, you read the diff split, and you do the git part by hand in the same workspace.

git add -p
git commit -m "fix token refresh race"
git push -u origin fix-auth
gh pr create --fill
gh pr checks
gh pr merge --squash

Keeping runs isolated

cmux gives no sandbox, so isolation is your job and git worktrees are the usual answer. One worktree per branch means one workspace per worktree, and no two agents fighting over the same index.

git worktree add ../api-fix-auth -b fix-auth
cmux ../api-fix-auth
cmux new-workspace --cwd ../api-fix-auth --command "claude" --name fix-auth

cmux diff --repo ../api-fix-auth --branch reviews a worktree from anywhere, and cmux workspace status set review pins the row into the review lane so you can tell what is waiting on you versus what is still running.