# Worktree

How to do feature work in this repo with git worktrees via `pnpm worktree`.

- Repository: https://github.com/kortix-ai/suna (20345 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kortix-ai/suna --skill worktree -g -a claude-code -y`
Codex: `npx skills add kortix-ai/suna --skill worktree -g -a codex -y`
Cursor: `npx skills add kortix-ai/suna --skill worktree -g -a cursor -y`
Gemini CLI: `npx skills add kortix-ai/suna --skill worktree -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

The rest: https://github.com/kortix-ai/suna/blob/HEAD/.agents/skills/worktree/SKILL.md