Post-Create Worktree Hooks

Every new git worktree starts bare — no node_modules, no .env, no generated config. A post-create worktree hook lets you define a bash script that runs automatically right after Scape creates a worktree, so a fresh worktree is ready to work in instantly.

Setting up a hook

Open Settings → Developer Tools → Worktrees. You'll find two levels of hooks:

• Global default — a script that runs for every new worktree across all repos.
• Per-repository overrides — a script for a specific repo. When set, the per-repo hook takes precedence over the global default.

The hook is a bash script. Write it exactly as you would in a terminal.

When hooks run

The hook fires after any local Scape worktree creation:

• Cmd+N new session (when it creates a worktree)
• The new-worktree button on session cards
• The create_worktree MCP tool (used by agents like Argus to spawn child sessions)

Remote worktrees created on an SSH host don't run hooks — the script would run on your Mac, not the host.

Execution context

Your script runs with the new worktree as the working directory. Scape also provides these environment variables:

Behavior

Hooks are fire-and-forget — the worktree tab opens immediately and the hook runs in the background. You don't have to wait for it to finish before you start working.

• A configurable timeout prevents runaway scripts.
• If a hook fails, Scape surfaces the error via a macOS notification so you know something went wrong.

Example: Node project setup

This hook installs dependencies and copies the .env file from the main repo:

#!/bin/bash
 
# Install dependencies in the new worktree
if [ -f "pnpm-lock.yaml" ]; then
  pnpm install
elif [ -f "yarn.lock" ]; then
  yarn install
elif [ -f "package-lock.json" ]; then
  npm install
fi
 
# Copy .env from the main repo if it exists
if [ -f "$REPO_PATH/.env" ]; then
  cp "$REPO_PATH/.env" "$WORKTREE_PATH/.env"
  echo "Copied .env from main repo"
fi

Example: Symlink shared directories

For large dependency trees, symlinking node_modules can save time and disk space:

#!/bin/bash
 
# Symlink node_modules from the main repo
if [ -d "$REPO_PATH/node_modules" ] && [ ! -d "node_modules" ]; then
  ln -s "$REPO_PATH/node_modules" node_modules
  echo "Symlinked node_modules"
fi
 
# Copy local config files
for f in .env .env.local; do
  [ -f "$REPO_PATH/$f" ] && cp "$REPO_PATH/$f" "$WORKTREE_PATH/$f"
done

Example: Full-stack project

A more comprehensive hook for a project with a database, code generation, and environment config:

#!/bin/bash
set -e
 
echo "Setting up worktree for branch: $BRANCH"
 
# Dependencies
pnpm install
 
# Copy environment files
cp "$REPO_PATH/.env" .env
cp "$REPO_PATH/.env.local" .env.local 2>/dev/null || true
 
# Run code generation (e.g. Prisma, GraphQL)
pnpm run generate
 
# Warm the build cache
pnpm run build --filter ./packages/shared
 
echo "Worktree ready!"