| name | bridge-worktree |
| description | Use when starting a feature, experiment or risky refactor in this repo — anything bigger than a one-file fix. Also when the user says "worktree", "new branch", "work on this in parallel", or when a change adds a table, a column or any new persisted data. Covers where the worktree goes, what is missing inside it, and keeping new data off the live bridge DB. |
| user-invocable | true |
Feature work happens in a worktree
master is the checkout the live bridge runs from. Work there and a half-built
feature is one mystical restart away from being the thing the user is talking
to. One-file fix or doc tweak: master is fine. Anything else: worktree.
Create it where the dashboard can see it
git worktree add -b feat/x ~/projects/.worktrees/mystical-assistant/feat-x
Inside BASE_PATH is the load-bearing part — _abs_within() drops any tree
outside ~/projects, so a worktree in /tmp is invisible to every surface and no
session can start in it. Git resolves branch→tree, so a hand-made git worktree add elsewhere under ~/projects still attaches; .worktrees/<repo>/<branch>
(slashes to dashes, _worktree_path() in bridge/dashboard/server.py) is the
convention that keeps it out of the project browser.
What isn't in there
git worktree add checks out tracked files only, so everything git-ignored is
missing:
.env — cp ~/projects/mystical-assistant/.env <wt>/.env. Without it
bin/mystical dies on any command except build/doctor.node_modules — only if you must build web in the worktree:
cd <wt>/bridge/dashboard/web && npm ci. Usually you don't; build from master
at ship time instead.
New data goes in a scratch DB
config.BRIDGE_DB defaults to ~/.bridge_state/bridge.db — the live bridge's
sessions, turns and events. A worktree that migrates it or writes new-shape rows
damages the thing the user is working in right now.
- Tests need nothing.
tests/conftest.py already pins BRIDGE_DB to a temp
file before config is imported.
- Any manual script or REPL:
BRIDGE_DB=/tmp/wt-x.db python3 …. In the
environment, before the process starts — bridge/config.py freezes the value
at import, so setting it afterwards does nothing.
- Schema changes stay in
bridge/store.py: a line in _SCHEMA plus an
idempotent ALTER TABLE in init(), like every column already there. Additive
only — master's code keeps reading that DB.
Two traps
mystical on PATH is the main checkout. It's a symlink to
mystical-assistant/bin/mystical, and that script resolves REPO from its own
location. mystical restart inside a worktree restarts the live bridge running
master's code. Say <wt>/bin/mystical when you mean the worktree.- Worktree code is never live. It can't be, until it's merged and the bridge
restarts — see bridge-ship. Don't restart anything to "test" it.
Fold back
git -C ~/projects/mystical-assistant merge feat/x
git worktree remove ~/projects/.worktrees/mystical-assistant/feat-x
Then bridge-ship. Abandoned worktrees aren't free: each one is a dirty tree
NEXT UP keeps suggesting and a row in the WORKTREES tab, and each can hold one of
the 8 dev-server slots (devserver.MAX_SERVERS).
