create-worktree · diff
v1.0.0 to v1.0.0
14 added, 1 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: false
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]
+ "${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" <worktree_name> [base_branch] [--no-from-remote] [--skip-fetch]
```
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)
+
+ **Resume-from-remote (default-on, CTL-1640).** When a NEW branch is being created and
+ `origin/<worktree_name>` already exists (e.g. a pushed draft PR's commits, CTL-783), the worktree
+ is seeded from that remote tip instead of being cut fresh off the base branch — so a re-dispatch
+ or a cross-host reclaim rebuilds on the pushed work rather than orphaning it under a fresh branch.
+ This is automatic; the script prints a `🌱 Resuming from origin/<name>` banner when it fires. An
+ existing **local** branch always wins over the remote (no auto-merge); the resume applies only
+ when there is no local branch yet.
+
+ To opt out and force a fresh branch off the base (ignore any matching origin branch), pass
+ **`--no-from-remote`**. To suppress all origin fetches entirely (offline), pass **`--skip-fetch`**
+ (which also disables the resume). Confirm with the user which they want before overriding the
+ default when a matching origin branch may carry stale or already-merged history.
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.
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. 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
(
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
```