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 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)

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!"