Feature request: worktree environment setup hook (deps, env files, port isolation)
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:
- https://nicholasjhenry.medium.com/building-isolated-phoenix-workspaces-for-ai-agents-with-conductor-a438d161f191
- https://www.10play.dev/blog/worktree-10x-development
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:
# ~/.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:
- Wait minutes per session for dep installs, or
- Start agents in broken environments (missing env vars, no deps), or
- 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.
Source: smtg-ai/claude-squad