Worktree scripts

Use worktree scripts when a new worktree needs more than git worktree add before it is useful.

A good script setup makes parallel work boring: create the worktree, prepare the files, start the right service, and clean up when the branch is done.

What scripts can do

Coldtea supports three script slots:

Setup — runs after a new worktree is created.
Run — starts the app or dev server for the active worktree.
Teardown — runs before a worktree is deleted or retired.

Scripts run in visible terminal panes. If setup or teardown fails, treat that failure like any other terminal command failure and inspect it before continuing.

Config files

Coldtea reads worktree script config from the project root:

.coldtea/config.json for shared team-safe scripts.
.coldtea/config.local.json for local machine-specific overrides.

The shared config can be committed. The local config should stay on your machine.

A simple shared config looks like this:

{
  "setup": ["npm install"],
  "run": ["npm run dev"],
  "teardown": ["npm run clean"]
}

Each field is optional. Omit a field when there is no useful command for it.

Local overrides

Use .coldtea/config.local.json for private or machine-specific behavior.

An array replaces the shared script for that key:

{
  "run": ["npm run dev -- --port 3010"]
}

A wrapper can run local commands before or after the shared script:

{
  "setup": {
    "before": ["cp ../coldtea/.env.local .env.local"],
    "after": ["npm run db:prepare"]
  }
}

Put secrets, personal paths, and local port choices in local config, not shared config.

Available variables

Coldtea provides these variables inside worktree commands:

COLDTEA_ROOT_PATH
COLDTEA_WORKTREE_PATH
COLDTEA_WORKTREE_NAME
COLDTEA_BASE_BRANCH
COLDTEA_BRANCH_NAME
COLDTEA_WORKTREE_ACCENT_TONE

Use them instead of hardcoding paths when a command needs to know which worktree it is running in.

What to decide before committing

Before committing .coldtea/config.json, decide:

Which untracked files need to be copied.
Which generated files can be recreated.
Whether services are shared or per-worktree.
How ports are assigned.
How local databases and caches are handled.
Which cleanup commands are safe for everyone.

Avoid destructive cleanup outside the worktree path. A teardown script should not surprise another developer's machine.

Keep scripts boring

Prefer commands that can be rerun safely. A script that works only on one laptop belongs in local config. A script that deletes broad paths belongs nowhere until the team has reviewed it.

Next: worktrees or run parallel agents.