Worktree Provisioning
Every feature runs in its own git worktree under ~/.shep/repos/<repo-hash>/wt/<branch-slug>. By default Shep creates it with git worktree add, which gives you a clean checkout: no node_modules, no untracked .env, no build caches.
That’s fine for most repositories. It isn’t for:
- Monorepos that resolve dependencies from one hoisted
node_modulesat the root. A fresh worktree has none, and installing per feature is slow, or impossible offline. - Projects with native or path-sensitive tooling that only build from a prepared directory.
- Teams with their own worktree tool that already knows how to lay a tree out correctly.
Two optional commands cover these cases. Leave both empty and nothing changes.
The two commands
| Setting | Replaces git worktree add? | Runs in | Typical use |
|---|---|---|---|
| Post-create command | No, runs after it | The new worktree | Link node_modules, copy config, warm caches |
| Custom create command | Yes | The main repository | Hand worktree creation to your own tool |
Both are ordinary shell command lines, run through your platform’s shell (cmd.exe on Windows, the POSIX shell elsewhere), so pipes, &&, quoting and variable expansion work. When both are set, the create command runs first and the post-create command runs after it.
Both are global settings: they apply to every repository you use with Shep.
Configure them
In the web UI, open Settings → Worktree:

From the terminal:
shep settings worktree # show the current config
shep settings worktree --post-create-command '<cmd>' # run <cmd> in each new worktree
shep settings worktree --create-command '<cmd>' # replace git worktree add
shep settings worktree --timeout 900000 # per-command timeout, in ms
shep settings worktree --clear # back to plain git worktree addPassing an empty string (--create-command '') clears just that command.
Environment variables
Both commands get your normal environment plus:
| Variable | Value |
|---|---|
SHEP_REPO_PATH | Absolute path of the main repository |
SHEP_WORKTREE_PATH | Absolute path where the worktree must exist when the command finishes |
SHEP_BRANCH | Branch checked out in the worktree |
SHEP_START_POINT | Start ref for a new branch; empty when the branch already exists |
SHEP_START_POINT tells a create command what to do: create the branch when it’s set, check out the existing branch when it’s empty. It’s empty, for example, when Shep adopts a branch you already have.
Examples
Link a hoisted node_modules (monorepo)
Leave the create command empty and set the post-create command:
shep settings worktree --post-create-command 'ln -s "$SHEP_REPO_PATH/node_modules" node_modules'The post-create command runs inside the new worktree, so the relative node_modules link lands in the right place.
For a pnpm workspace where each package has its own node_modules, link them all:
for dir in packages/*; do
[ -d "$SHEP_REPO_PATH/$dir/node_modules" ] && ln -s "$SHEP_REPO_PATH/$dir/node_modules" "$dir/node_modules"
done
ln -s "$SHEP_REPO_PATH/node_modules" node_modulesPaste multi-line scripts like this into the Post-create command field in Settings, or save them as a script in your repository and call that script.
Copy untracked local config
cp "$SHEP_REPO_PATH/.env.local" . 2>/dev/null || trueUse your own worktree tool
my-monorepo-tool worktree add "$SHEP_WORKTREE_PATH" "$SHEP_BRANCH" ${SHEP_START_POINT:+--from "$SHEP_START_POINT"}A create command must leave a usable checkout at $SHEP_WORKTREE_PATH. Shep checks that the directory exists, then looks it up in git worktree list. If your tool made something git doesn’t list as a worktree of the main repository (a separate clone, for example), Shep inspects the directory directly instead of failing.
Prefer a tool that wraps git worktree add. Shep removes worktrees with git worktree remove, which only works on real worktrees.
Timeouts and failures
The timeout (default 300000 ms, five minutes) applies to each command separately. Raise it if your command runs an install.
A failing command fails feature creation. This is on purpose: a worktree that wasn’t set up properly causes confusing agent failures much later. The error shows the command, its exit message, and the first 2,000 characters of its output.
What’s next
- Parallel features & worktrees — how Shep isolates each feature.
- Dev servers — run a worktree’s dev server once it’s provisioned.
- Configuration — every other setting.