What probably matters to youSection of the release
What
--worktree starts Claude Code in a separate git worktree, which is a second working copy of your repository in its own folder. --tmux opens that session inside tmux, a terminal multiplexer. Claude Code has a shortcut (a fast path) for this combination, and it changed in several ways:
The shortcut now loads settings early and checks managed policy, meaning the rules an administrator sets. If policy refuses the launch, Claude Code exits with an error. Before, this shortcut only enabled config loading, and the other shortcuts already did this check.
tmux is now started with an explicit, cleaned-up set of environment variables (extendEnv: !1) instead of every variable inherited from your shell.
Claude Code stops looking for --worktree and --tmux when it reaches --. Flags that take a value are skipped with their value, so a value such as -- --worktree is no longer misread.
The arguments forwarded into the new tmux session are now built by a helper instead of an inline filter that copied everything except --tmux and --worktree.
Path arguments are rewritten to absolute (full) paths when they are forwarded. This covers --settings, --mcp-config, --agents, --add-dir, --plugin-dir, --system-prompt-file, --append-subagent-system-prompt-file and --debug-file. Inline JSON and paths starting with ~ are left as they are.
--setting-sources and --managed-settings are now recognised explicitly.
Why
The session inside tmux runs in the worktree folder, not the folder you launched from. A relative path such as --settings ./my.json would otherwise point at the wrong place, and absolute paths keep it pointing at the file you meant. The policy check means administrators' managed policy applies to this way of launching too.
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Confirmed sinceAnthropic's documentation has since written up --tmux, on Claude Code changelog.- Fixed plugin `WorktreeCreate` and `WorktreeRemove` hooks not running when Claude Code starts with `--worktree` (not yet with `--tmux`)changelogsee the edit
Added sinceA small documentation edit on Week 19 · May 4–8, 2026 touched a line naming --worktree after this was published.<div>New <code>worktree.baseRef</code> setting (<code>fresh</code> | <code>head</code>) controls whether `--worktree`, the <code>EnterWorktree</code> tool, and agent-isolation worktrees branch from the remote default branch or local <code>…whats-new/2026-w19see the edit
Confirmed sinceAnthropic's documentation has since written up --worktree, on Hooks reference.* **No WorktreeRemove hook**: when you exit a `--worktree` session and choose removal, Claude Code falls back to `git worktree remove --force` on the path your WorktreeCreate hook returned, so a worktree git recognizes is removed. A worktr…hookssee the edit
How sure we are
Two sources agreeTwo things we can check say the same as this entry.
Anthropic's documentation agreesAnthropic's documentation has since written up --worktree, on Hooks reference.
Anthropic's release notes agreeFixed --setting-sources (and SDK settingSources) not being forwarded to spawned sessions: teammates, /bg, claude agents sessions and…
