Clone Worktree Port Bump

[Created by Codex: 019bbb3c-b337-72a1-8563-a7d159806dbc]

Overview

Create an isolated working copy of a project under ~/temp, then avoid port collisions by bumping all dev port values in the clone’s .env by a deterministic offset.

After cloning, treat the clone as the only writable workspace: never modify the original project unless the user explicitly asks.

Triggers

• •“work on a clone”
• •“clone this project to ~/temp”
• •“don’t touch the original repo”
• •“bump ports in the clone”
• •“another agent is working there; avoid collisions”

Workflow (do in order)

1) Choose clone suffix

• •Define base_name as the project folder name (e.g. agent-box-v1).
• •Set dest_root=~/temp.
• •Find the smallest N >= 1 such that dest_root/base_name-cloneN does not exist.

CRITICAL - Iterative check required: Do NOT assume that if cloneN exists, then clone1 through clone(N-1) also exist. Clones may be deleted out of order. You MUST check iteratively starting from N=1:

# Correct approach - check each number starting from 1
for N in 1 2 3 4 5 ...; do
  if [ ! -d ~/temp/base_name-clone$N ]; then
    # Use this N
    break
  fi
done

This ensures clone numbers (and their associated port ranges) are reused when clones are deleted, rather than ever-increasing.

2) Copy project into clone path (no original edits)

• •Copy the project directory to ~/temp/base_name-cloneN/.
• •Exclude node_modules/ and build outputs (e.g. dist/) if present.
• •Do not modify the original directory during/after the copy.

3) Bump ports in the clone

• •Compute offset = 100 * N.
• •Edit only ~/temp/base_name-cloneN/.env:
  • •For every *_PORT=<number> line, change <number> → <number + offset>.
  • •Keep variable names unchanged; change only values.
• •If the repo does not have .env, create it in the clone and define the port variables required by the project before proceeding.

4) Install dependencies in the clone (recommended default)

• •Expect installs to be required because clones often exclude node_modules/.
• •Run dependency installs inside the clone before running dev commands:
  • •Node projects: run npm install (or npm ci if package-lock.json exists and is in sync).
  • •If the project is a monorepo, run installs per app/service as needed (e.g., npm -C apps/foo install).
  • •Python services: install required env (only if the project documents it); otherwise do not guess.

5) Switch working directory and enforce isolation

• •Treat ~/temp/base_name-cloneN as the only writable workspace from this point on.
• •If a task would require editing the original repo, stop and ask the user for explicit permission.
• •When presenting commands for the user, always cd ~/temp/base_name-cloneN first.

6) Sanity checks (recommended)

• •Verify no accidental edits in the original repo:
  • •If the repo is git-managed: git -C <original> status --porcelain should be empty if it was clean before.
• •Verify .env values in clone reflect the expected offset.