[BUG] `claude -w` hangs when worktree name contains spaces (invalid git branch name)
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report
- [x] I am using the latest version of Claude Code
What's Wrong?
claude -w '<name with spaces>' hangs indefinitely with no output. The TUI never renders and the process shows no CPU activity.
Root cause: The worktree name is used directly as part of the git branch name (e.g., worktree-<name>). Git branch names cannot contain spaces. When git worktree add -b "worktree-<name with spaces>" fails, Claude Code does not handle the error — it hangs silently instead of reporting the failure.
Reproduction Steps
# Hangs indefinitely (name contains a space before "AI"):
claude -w '团队支持通过 AI 创建和具备评分能力'
# Works perfectly (no space):
claude -w '团队支持通过AI创建和具备评分能力'
# Also hangs (English with spaces):
claude -w 'add user auth feature'
Expected Behavior
Claude Code should sanitize the worktree name before using it as a git branch name — replacing spaces and other invalid characters with hyphens (or similar). For example:
- Input:
团队支持通过 AI 创建和具备评分能力 - Branch:
worktree-团队支持通过-AI-创建和具备评分能力
At minimum, if the name is invalid, Claude Code should display a clear error message instead of hanging.
Environment Info
- Claude Code version: 2.1.72
- Platform: macOS (Darwin 25.2.0, x86_64)
- Shell: zsh
- Node: v22.x
- Git: 2.x
Additional Context
The --worktree flag accepts an optional [name] argument which is commonly a task description (natural language, often with spaces). Since users naturally type names with spaces, this is a very easy trap to fall into.
Relevant git constraint: branch names cannot contain spaces, consecutive dots (..), ASCII control characters, or characters like ~, ^, :, ?, *, [, \. See git-check-ref-format.
Suggested fix: Apply git check-ref-format --normalize or equivalent sanitization to the derived branch name before calling git worktree add.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗