Claude Code worktrees: isolate tasks, ports and databases

CLAUDE_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-worktrees.XXXXXX")
git init -b main "$CLAUDE_LAB/repo"
cd "$CLAUDE_LAB/repo"
printf '.claude/worktrees/\n' > .gitignore
printf '# Disposable worktree example\n' > README.md
git add .gitignore README.md
git -c user.name='Worktree demo' -c user.email='demo@example.invalid' \
  commit -m 'Initialize disposable Claude worktree example'
pwd

claude --worktree docs-a

cd /paste/the/printed/repository/path
claude -w docs-b

codex -C /absolute/path/to/your/assigned/worktree

LAB_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/agent-worktrees.XXXXXX")
git init -b main "$LAB_ROOT/repo"
cd "$LAB_ROOT/repo"
printf '.local/\n' > .gitignore

cat > app.py <<'PY'
import json
import os
from pathlib import Path
import sqlite3
import subprocess
from http.server import BaseHTTPRequestHandler, HTTPServer

port = int(os.environ["APP_PORT"])
database = Path(os.environ["APP_DATABASE"]).resolve()
database.parent.mkdir(parents=True, exist_ok=True)
with sqlite3.connect(database) as connection:
    connection.execute("CREATE TABLE IF NOT EXISTS notes (body TEXT NOT NULL)")

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/health":
            self.send_error(404)
            return
        with sqlite3.connect(database) as connection:
            notes = [row[0] for row in connection.execute("SELECT body FROM notes")]
        branch = subprocess.check_output(
            ["git", "branch", "--show-current"], text=True
        ).strip()
        body = json.dumps({"branch": branch, "port": port,
                           "database": str(database), "notes": notes}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

HTTPServer(("127.0.0.1", port), Handler).serve_forever()
PY

git add .gitignore app.py
git -c user.name='Worktree demo' -c user.email='demo@example.invalid' \
  commit -m 'Add local worktree demonstration'
git clone --bare . "$LAB_ROOT/origin.git"
git remote add origin "$LAB_ROOT/origin.git"
git fetch origin

git worktree list --porcelain
git worktree add --detach "$LAB_ROOT/agent-a" origin/main
git -C "$LAB_ROOT/agent-a" switch -c demo/agent-a
git worktree add --detach "$LAB_ROOT/agent-b" origin/main
git -C "$LAB_ROOT/agent-b" switch -c demo/agent-b
git worktree list

mkdir -p "$LAB_ROOT/agent-a/.local" "$LAB_ROOT/agent-b/.local"
cat > "$LAB_ROOT/agent-a/.local/runtime.env" <<'ENV'
APP_PORT=8911
APP_DATABASE=.local/dev.sqlite
ENV
cat > "$LAB_ROOT/agent-b/.local/runtime.env" <<'ENV'
APP_PORT=8912
APP_DATABASE=.local/dev.sqlite
ENV
chmod 600 "$LAB_ROOT"/agent-{a,b}/.local/runtime.env
git -C "$LAB_ROOT/agent-a" check-ignore .local/runtime.env
git -C "$LAB_ROOT/agent-b" check-ignore .local/runtime.env
printf 'A: %s\nB: %s\n' "$LAB_ROOT/agent-a" "$LAB_ROOT/agent-b"

cd /paste/the/printed/agent-a/path
set -a
. .local/runtime.env
set +a
python3 app.py

cd /paste/the/printed/agent-b/path
set -a
. .local/runtime.env
set +a
python3 app.py

curl --fail --silent http://127.0.0.1:8911/health
curl --fail --silent http://127.0.0.1:8912/health

python3 - "$LAB_ROOT/agent-a/.local/dev.sqlite" <<'PY'
import sqlite3
import sys
with sqlite3.connect(sys.argv[1]) as connection:
    connection.execute("INSERT INTO notes (body) VALUES (?)", ("agent-a-only",))
PY
curl --fail --silent http://127.0.0.1:8911/health
curl --fail --silent http://127.0.0.1:8912/health
git -C "$LAB_ROOT/agent-a" status --short
git -C "$LAB_ROOT/agent-b" status --short

npm ci

createdb --host=127.0.0.1 --port=5432 agent_a_dev
createdb --host=127.0.0.1 --port=5432 agent_b_dev
psql --host=127.0.0.1 --port=5432 --dbname=agent_a_dev \
  -X -v ON_ERROR_STOP=1 -c 'SELECT current_database(), current_schema();'
psql --host=127.0.0.1 --port=5432 --dbname=agent_b_dev \
  -X -v ON_ERROR_STOP=1 -c 'SELECT current_database(), current_schema();'

npm run stack:assign
npm run stack:up
npm run stack:ps

set -a
. .ams-worktree/stack.env
set +a
curl --fail "$AMS_BASE_URL/health"

npm run runtime:assign
npm run dev:worktree

Work only in the assigned checkout and branch. Read its repository instructions.

Before editing, report the absolute checkout path, branch, assigned listener
ports, and database name without printing credentials. Inspect startup scripts
for shared paths and verify the app and tests target the assigned resources.

Own only the notification sender implementation and its focused tests.
List the exact allowed paths before editing. Hold shared API types,
migrations, manifests and lockfiles for an agreed owner. Stop and ask the
receiver owner before a dependent interface or migration change.

Done means the assigned behavior works, focused tests pass, and a reviewer
can inspect the diff. Report the base/HEAD, changed paths, tests and gaps.
Do not stop another task's process, reuse its database, or change its checkout.
Commit, push, PR, merge and deployment each need their required authorization.

ams workspace current --json

ams workspace use WORKSPACE_ID --worktrees

ams --require-workspace status
ams --require-workspace messages --resume

ams --require-workspace send "I own sender changes on demo/agent-a. Receiver owner: both branches add migration 0042. Please acknowledge who will reconcile the migration order before we combine them; I will hold the dependent migration edit."

git fetch origin
git worktree list --porcelain
git log --oneline origin/main..demo/agent-a
git diff --stat origin/main...demo/agent-a
git log --oneline origin/main..demo/agent-b
git diff --stat origin/main...demo/agent-b

cp -R "$LAB_ROOT/agent-a/.local" "$LAB_ROOT/agent-a-local-backup"
cp -R "$LAB_ROOT/agent-b/.local" "$LAB_ROOT/agent-b-local-backup"

git -C "$LAB_ROOT/repo" worktree remove "$LAB_ROOT/agent-a"
git -C "$LAB_ROOT/repo" worktree remove "$LAB_ROOT/agent-b"