Feature request: worktree environment setup hook (deps, env files, port isolation)

Author: rohansxCreated Mar 5, 2026Updated Aug 14, 2026

Problem

When Claude Squad creates a new worktree session, the worktree is missing everything that isn't tracked by git:

  • node_modules / target/ / .venv — gone, needs full reinstall (minutes + GBs of disk per session)
  • .env, .envrc, .npmrc, secrets — gone, agent fails immediately or uses wrong config
  • Port conflicts — two sessions both try port 3000, one crashes
  • Docker compose collisions — shared project namespace means containers clobber each other

Right now the workaround is manually setting up each session or writing custom bash. This is the same problem Conductor users hit — several have published 50-100 line setup scripts just to get worktrees working:

Proposal

Support a setup hook that runs after worktree creation, so users can automate their environment setup. Something like:

cs new --setup "workz sync --isolated"

Or a config option:

toml
# ~/.config/claude-squad/config.toml
worktree_setup = "[workz](https://github.com/rohansx/workz) sync --isolated"

Existing tool that solves this

I built workz — a Rust CLI specifically for this problem. When run in a worktree, it:

  • Auto-detects project type (Node/Rust/Python/Go/Java)
  • Symlinks heavy dirs (node_modules, target/, .venv, etc.) — saves GBs, no reinstall
  • Copies env files (.env, .envrc, .npmrc, 17 patterns)
  • Auto-installs deps from lockfiles if needed
  • With --isolated: assigns unique ports, namespaces Docker compose, generates per-worktree DB names

It works as a single command (workz sync --isolated) and requires zero configuration for most projects.

Why this matters for Claude Squad specifically

Claude Squad's strength is spinning up many parallel sessions fast. But the environment setup bottleneck means users either:

  1. Wait minutes per session for dep installs, or
  2. Start agents in broken environments (missing env vars, no deps), or
  3. Write custom setup scripts per project

A setup hook would let users plug in workz (or any custom script) and get instant, fully functional worktrees for every session.

Happy to contribute a PR for the hook mechanism if there's interest.