Worktree Scripts

scripts/setup-worktree.sh and scripts/remove-worktree.sh create and tear down a parallel git worktree so you can run a second branch side-by-side — each app on an auto-detected free port, with gitignored config copied and patched. They run standalone from the CLI; the Worktree Skill (/worktree) is a Claude Code wrapper around them.

scripts/setup-worktree.sh <branch> [base-ref] [--db shared|empty|copy]
scripts/remove-worktree.sh <name> [--force] [--keep-branch]

Database isolation

setup-worktree.sh takes --db <mode> (default shared):

Mode	Behaviour
shared	Default. No MONGODB_URI override — the worktree uses main's running Mongo (same data).
empty	Brings up an isolated, empty Mongo on its own free port; sets the worktree's MONGODB_URI.
copy	Like empty, then seeds it from the shared DB (mongodump → mongorestore).

scripts/setup-worktree.sh <branch> --db copy

Isolated modes bring up only a Mongo container (own free port + .env.compose); Redis and assets stay shared. Use copy for destructive/migration work against realistic data without touching main's DB. Caveat: Atlas $search indexes are not carried by mongodump, so search-backed flows on a copy DB are empty until rebuilt.

What it sets up

• Git worktree at ../tell-ia-<feature>, on the resolved/created branch.

• Auto-detected free ports, each probed upward from its base:

  Service	Base
  Backend API	3888
  Frontend Vite	5173
  Admin Vite	5174
  MCP server	3889

• Copied + patched gitignored config: the four .env files and frpc.toml are copied from the main repo, then ports/URLs are rewritten — frontend/admin/mcp point at the worktree's backend, and the backend CORS_ORIGINS / SOCKET_CORS_ORIGIN are widened to the new frontend/admin ports so chat/WebSocket keeps working.

• Database (per --db, default shared): shared leaves the backend .env Mongo pointer at main's containers; empty/copy bring up an isolated Mongo on its own free port, write a .env.compose, and point the worktree's MONGODB_URI at it (copy seeds it from the shared DB). Redis + assets stay shared in every mode.

• VS Code workspace: the folder is added to ../tell-ia.code-workspace (created if missing). An open VS Code window on that workspace picks the folder up automatically.

NOTE

vite.config.ts and package.json are tracked and already read VITE_DEV_PORT, so the worktree gets them from git unchanged — they are not copied.

Prerequisite: shared DB must be running

A shared-DB worktree reuses main's database, and --db copy reads it as the seed source, so start the main repo's DB first either way:

cd apps/agri-backend && docker compose up -d

The setup script warns (and, for --db copy, leaves the DB empty) if nothing is on 27017.

Run the apps

From the worktree directory (each in its own terminal):

pnpm --filter agri-backend dev
pnpm --filter agri-frontend dev
pnpm --filter agri-admin dev
pnpm --filter @tellia-solutions/mcp dev
frpc -c frpc.toml            # optional tunnel

The dev tunnel frpc.toml is regenerated with the worktree's ports and unique subdomains. See Dev Tunnels for frpc install and FRP_TOKEN.

Remove a worktree

From the main repo:

bash scripts/remove-worktree.sh <name> [--force] [--keep-branch]

It removes the worktree directory (including its copied .env files), drops the folder from tell-ia.code-workspace, and deletes the branch. For a --db empty|copy worktree it first tears down the isolated Mongo container + volumes (via the worktree's .env.compose).

TIP

Use --keep-branch when the branch backs an open PR — it removes only the worktree and leaves the branch (local + remote) intact. --force is required if the worktree has uncommitted changes.

A shared-DB worktree has no Docker teardown (the DB was never per-worktree); a --db empty|copy worktree's isolated Mongo container + volumes are torn down automatically (above).

How it differs from Multi-Instance

Multi-Instance (create-instance.sh) is the heavier sibling — a full isolated stack per instance. The worktree scripts are lighter and share by default.

	Multi-Instance (create-instance.sh)	Worktree (setup-worktree.sh)
Database	Full isolation — own Mongo + Redis containers	Shared by default; Mongo-only isolation via --db empty|copy
Docker	New compose stack per instance	None by default; one Mongo container with --db
Ports	Fixed offset (N × 100)	Auto-detected next free port per app
Branch	New instance-N branch	Any branch (or an ENG/PR id via the skill)
Editor	VS Code colour per instance	Adds the folder to a shared .code-workspace
Data	Empty until seeded	Same as main (shared); or empty/seeded copy via --db

Pick multi-instance for a full isolated stack (Mongo + Redis + Firebase) on the instance-N workflow. Pick the worktree scripts for quick parallel work — shared DB by default, or Mongo-only isolation via --db copy (seeded from main) / --db empty.