diff --git a/.vscode/settings.json b/.vscode/settings.json
index 73f0e040..fb7e59f9 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -4,6 +4,6 @@
     "git.worktreeIncludeFiles": [
         "api/.env",
         "api/.env.test",
-        "ui/.env.local"
+        "ui/.env"
     ]
 }
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index 9bcd39ce..c3ac3547 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -18,6 +18,18 @@
                 "runOn": "folderOpen"
             },
             "problemMatcher": []
+        },
+        {
+            // Manual, one-time per worktree (heavy: submodule + venv + deps).
+            // Run via: Tasks: Run Task -> "Setup worktree environment".
+            "label": "Setup worktree environment",
+            "type": "shell",
+            "command": "${workspaceFolder}/scripts/setup-worktree.sh",
+            "presentation": {
+                "reveal": "always",
+                "panel": "dedicated"
+            },
+            "problemMatcher": []
         }
     ]
 }
diff --git a/scripts/setup-worktree.sh b/scripts/setup-worktree.sh
new file mode 100755
index 00000000..99a710d9
--- /dev/null
+++ b/scripts/setup-worktree.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# One-time environment setup for a fresh git worktree.
+#
+# A new worktree is just a source checkout — it has no venv, the pipecat
+# submodule isn't checked out, and ui/node_modules may be missing. This wires
+# up an ISOLATED environment so the worktree can run independently (its own
+# editable pipecat install points at THIS worktree's pipecat, so pipecat edits
+# here take effect).
+#
+# Heavy (minutes) — deliberately NOT a folderOpen task. Run it once per worktree:
+#   ./scripts/setup-worktree.sh        (or VS Code: Run Task -> "Setup worktree environment")
+#
+# Fast on repeat: uv hardlinks wheels from its global cache, npm uses its cache.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+PYVER="${PYVER:-3.13}"
+
+# Mirror all output to a gitignored, worktree-local log so you can follow
+# progress any time this runs (manual, VS Code task, or background):
+#   tail -f logs/setup-worktree.log
+# (/logs/ is already in .gitignore, and each worktree has its own logs/.)
+LOG="$ROOT/logs/setup-worktree.log"
+mkdir -p "$ROOT/logs"
+exec > >(tee "$LOG") 2>&1
+echo "=== setup-worktree $(date '+%Y-%m-%d %H:%M:%S')  [$(basename "$ROOT")] ==="
+
+echo "==> [1/4] pipecat submodule (init/update for this worktree)..."
+git submodule update --init --recursive
+
+echo "==> [2/4] isolated venv (python $PYVER)..."
+if [ -x venv/bin/python ]; then
+  echo "    venv already exists — reusing."
+else
+  uv venv venv --python "$PYVER"
+fi
+# Activate so setup_requirements.sh / uv install into THIS worktree's venv.
+set +u  # activate scripts can reference unset vars
+# shellcheck disable=SC1091
+source venv/bin/activate
+set -u
+
+echo "==> [3/4] Python deps (--dev; submodule already inited)..."
+./scripts/setup_requirements.sh --dev
+
+echo "==> [4/4] UI node_modules..."
+( cd ui && npm install )
+
+echo "✅ Worktree env ready: $(basename "$ROOT")  ($(python -V 2>&1))"
diff --git a/scripts/worktree-assign-port.sh b/scripts/worktree-assign-port.sh
index 8daf4eae..71b4b5e7 100755
--- a/scripts/worktree-assign-port.sh
+++ b/scripts/worktree-assign-port.sh
@@ -7,7 +7,7 @@
 #   - The MAIN worktree is left untouched (backend stays on uvicorn's default 8000).
 #   - Each linked worktree gets the next free backend port: 8001, 8002, ...
 #   - api/.env       : UVICORN_PORT          -> the assigned backend port
-#   - ui/.env.local  : BACKEND_URL           -> http://localhost:<port>
+#   - ui/.env  : BACKEND_URL           -> http://localhost:<port>
 #                      NEXT_PUBLIC_BACKEND_URL -> http://localhost:<port>
 #
 # CORS is intentionally NOT touched: local dev runs DEPLOYMENT_MODE="oss", where
@@ -22,7 +22,7 @@ MAIN="$(git worktree list --porcelain | sed -n '1s/^worktree //p')"
 [ "$ROOT" = "$MAIN" ] && { echo "[worktree] main worktree -> backend 8000 (untouched)"; exit 0; }
 
 AENV="$ROOT/api/.env"
-UENV="$ROOT/ui/.env.local"
+UENV="$ROOT/ui/.env"
 [ -f "$AENV" ] || { echo "[worktree] no api/.env yet; skipping"; exit 0; }
 
 # Echo the UVICORN_PORT value from an env file (empty if unset/missing).
diff --git a/ui/.gitignore b/ui/.gitignore
index 219f1c84..a194b9d5 100644
--- a/ui/.gitignore
+++ b/ui/.gitignore
@@ -40,4 +40,4 @@ next-env.d.ts
 # Sentry Config File
 .env.sentry-build-plugin
 
-.env.local
\ No newline at end of file
+.env