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 --worktree, on Run parallel sessions with worktrees.* **The worktree has work in it**: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch. To return later, run the `claude --worktree <name> --resume` command that Claude Code prints on exit. Removin…worktreessee the edit
How sure we are
Something disagreesSomething we can check disagrees with this entry, or the writer said they could not settle it.
The writer flagged doubtThe finding does not say which environment variables are kept or dropped when tmux is started.
Anthropic's documentation agreesAnthropic's documentation has since written up --worktree, on Run parallel sessions with worktrees.
Anthropic's release notes agreeFixed --setting-sources (and SDK settingSources) not being forwarded to spawned sessions: teammates, /bg, claude agents sessions and…
