# Clone Worktree Port Bump

> Clone a repo to ~/temp with unique -cloneN, bump all *_PORT values in clone .env by +100*N, then work only in the clone and never touch the original unless explicitly asked.

- Skill: `tankygranny05/clone-worktree-port-bump` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/clone-worktree-port-bump`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/clone-worktree-port-bump/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/clone-worktree-port-bump

---


# 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:

```bash
# 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.