create-worktree · diff
v1.0.0 to v1.0.0
13 added, 7 removed. Audit B to B.
---
name: create-worktree
description:
"Create a git worktree for parallel work and optionally launch implementation session. **ALWAYS
use when** the user says 'create a worktree', 'work in parallel', 'start a worktree for', or needs
to work on multiple features simultaneously without switching branches."
disable-model-invocation: true
allowed-tools: Bash, Read
version: 1.0.0
---
## Configuration Note
This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
prefix:
- Read from `.catalyst/config.json` if available
- Otherwise use a generic format like `TICKET-XXX`
- Examples: `ENG-123`, `FEAT-456`, `BUG-789`
You are tasked with creating a git worktree for parallel development work.
## Process
When this command is invoked:
1. **Gather required information**:
- Worktree name (e.g., PROJ-123, feature-name)
- Base branch (default: current branch)
- Optional: Path to implementation plan
2. **Confirm with user**: Present the worktree details and get confirmation before creating.
3. **Create the worktree**: Use the create-worktree.sh script:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" <worktree_name> [base_branch]
```
The script automatically:
- Reads `catalyst.worktree.setup` from config for project-specific setup
- Copies `.claude/` and `.catalyst/` directories
- Falls back to auto-detected setup if no config (dependency install + thoughts init)
4. **Project setup** (handled by script based on config):
- If `catalyst.worktree.setup` is defined in config, those commands run in order.
- Otherwise, the script auto-detects: dependency install (`bun/npm`) + thoughts init.
+ If `catalyst.worktree.setup` is defined in config, those commands run in order. Otherwise, the
+ script auto-detects: dependency install (`bun/npm`) + thoughts init.
Example config for full control:
+
```json
{
"catalyst": {
"worktree": {
"setup": [
"humanlayer thoughts init --directory ${DIRECTORY} --profile ${PROFILE}",
"humanlayer thoughts sync",
"bun install",
"~/.claude/scripts/trust-workspace.sh \"$(pwd)\""
]
}
}
}
```
5. **Optional: Launch implementation session**: If a plan file path was provided, ask if the user
- wants to launch Claude in the worktree:
+ wants to launch Claude in the worktree. Note: `claude -w` takes a _name_ and creates a new
+ worktree — so `cd` into the already-created worktree instead, capture stderr to a real file for
+ post-mortem debugging, and use `--dangerously-skip-permissions` since there's no TTY.
```bash
- claude -w <worktree_path> \
- -p "/catalyst-dev:implement-plan <plan_path> and when done: create commit, create PR, update Linear ticket" \
- --output-format stream-json --verbose \
- > "<worktree_path>/worker-stream.jsonl" 2>/dev/null &
+ (
+ cd "<worktree_path>" || exit 1
+ exec nohup claude \
+ --output-format stream-json --verbose \
+ --dangerously-skip-permissions \
+ -p "/catalyst-dev:implement-plan <plan_path> and when done: create commit, create PR, update Linear ticket"
+ ) > "<worktree_path>/worker-stream.jsonl" 2> "<worktree_path>/worker-stderr.log" &
```
## Worktree Location Convention
Worktree base directory is resolved in this order:
1. `catalyst.orchestration.worktreeDir` from config (explicit override)
2. `~/catalyst/wt/<projectKey>/` (default — reads `catalyst.projectKey` from config)
3. `~/catalyst/wt/<repo>/` (fallback if no config)
**Recommended**: Add `~/catalyst` to Claude Code's `additionalDirectories` in
`~/.claude/settings.json` so all worktrees across projects are automatically trusted.
**Example layout** (for project with `projectKey: "acme"`):
```
~/catalyst/wt/acme/
├── ACME-123-feature/
├── ACME-456-bugfix/
└── ENG-789-oauth/
```
**With orchestration** (multiple named orchestrators):
```
~/catalyst/wt/acme/
├── auth-orch/ # orchestrator
├── auth-orch-ACME-101/ # worker
├── auth-orch-ACME-102/ # worker
├── dash-orch/ # another orchestrator
└── dash-orch-ACME-201/ # worker
```
## Example Interaction
```
User: /create-worktree PROJ-123
```