Worktree
How to do feature work in this repo with git worktrees via `pnpm worktree`.
Install
npx skills add kortix-ai/suna --skill worktree -g -a claude-code -y- Repository
- kortix-ai/suna20.3k
- Category
- Testing
- Updated
- 3d ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
How to do feature work in this repo with git worktrees via `pnpm worktree`. Each worktree gets its own branch, its own block of app ports, its own node_modules, and by default shares the primary checkout's standard local Supabase DB for fast setup; pass `--db` for its own database (a copy of the primary inside the same Postgres) when the work needs migrations or destructive data changes. Load WHENEVER starting a feature, bugfix, refactor, experiment, or any change you'll want to run/test in isolation; whenever the user mentions worktrees, isolated/parallel dev instances, running multiple branches at once, or 'spin up a worktree'; and whenever you need the exact non-interactive `pnpm worktree` commands and flags. Enforces: one canonical branch per objective, one worktree per branch, join the existing worktree instead of creating another.
Worktrees (pnpm worktree)
Multi-instance dev environments for this monorepo. One command from a clean
checkout provisions a collision-free app stack on its own branch: unique ports
for web/api/gateway, its own node_modules + pnpm store, and a tunnel for cloud
sandbox callbacks. By default the worktree uses the primary checkout's standard
local Supabase DB (kortix-local on 54321/54322) so setup is fast and auth/data
state is shared. Pass --db when the work needs its own schema or data
(migrations, destructive data changes): it copies the primary into its own
database kortix_wt_<n> in the same Postgres (~5 s, no extra containers).
Pass --full-supabase only when the work needs its own auth or storage
config: that runs a whole Supabase project (8 containers, ~0.75 GB RAM). The CLI lives
at scripts/worktree/cli.ts, run via the root package.json script
pnpm worktree.
THE RULE, one canonical branch, one worktree
A worktree maps 1:1 to a canonical branch, the branch for whatever is being worked on. Work in a worktree, but do not create one by reflex.
First, look for the worktree that already exists. Run pnpm worktree list.
If the work continues, extends, fixes, or cleans up something already in flight,
it belongs in that worktree, on that branch. Join it. Spinning a second worktree
for the same objective is the mistake this rule exists to prevent.
Never switch a worktree you did not create to another branch. Another
session may be working in it. The pre-commit hook refuses a commit whose branch
is neither the worktree's own (.kortix-worktree.json) nor <branch>/…
(scripts/check-worktree-branch.sh; deliberate override:
KORTIX_WORKTREE_ANY_BRANCH=1). A throwaway probe branch gets a private
git worktree add <scratchpad>/<name> instead.
