Subwave Worktree Dev

What it does

When your agent uses it

• The user wants to test branch changes in a worktree
• Run subwave from a worktree
• Prep/set up a worktree for dev mode
• Asks to copy env files / nodemodules / state into a worktree — phrases like test this worktree in dev mode

Example prompts

• “set up”
• “test this worktree in dev mode”
• “start subwave from the worktree”
• “/subwave-worktree-dev”

Requirements

• Node.js
• A Bash shell
• Docker

Workflow steps

5 steps, taken from the step headings in SKILL.md.

1. 1Identify the worktree
2. 2Stop any running stack
3. 3Prep the worktree
4. 4Start the stack from the worktree
5. 5Verify on-air

What it can do on your machine

Read from SKILL.md and the folder at commit 45ef433. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Shell), which the agent can run.

  Shell commands in SKILL.md call:

  • docker
  • npm
  • git
  • curl
  • bash

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use docker, npm, git and curl, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Subwave Worktree Dev loads about 2.1k tokens when it runs. Until then it costs about 202 tokens; SKILL.md has 875 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~202

When it runs · the whole SKILL.md, loaded when a task matches

~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:6

  gitignored files (controller/.env, web/.env.local, docker/.env, web/node_modules,

• NoteMentions a .env fileSKILL.md:30

  | `.env` | Root `.env` — `ADMIN_USER` / `ADMIN_PASS` / `SITE_URL`. Dev compose references it as `./.env`; compose refuse

• NoteMentions a .env fileSKILL.md:31

  | `controller/.env` | Dev compose declares `env_file: ./controller/.env` — controller container won't start without it.

• NoteMentions a .env fileSKILL.md:32

  | `web/.env.local` | Dev API/stream URL overrides (`NEXT_PUBLIC_API_URL` etc.). Without it the web UI defaults to same-o

• NoteMentions a .env fileSKILL.md:33

  | `docker/.env` | Compose variable substitution (legacy — harmless to copy). |

• NoteMentions a .env fileSKILL.md:163

  hing the **main checkout's** `controller/.env`, `state/`, or config

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from perminder-klair/subwave at commit 45ef433, republished under its MIT licence (© perminder-klair). 875 words, ~2,106 tokens.

name

subwave-worktree-dev

description

Stage a SUB/WAVE git worktree so the dev stack can run from it, then start it. A git worktree only checks out tracked files — the dev stack also needs gitignored files (controller/.env, web/.env.local, docker/.env, web/node_modules, and a state/ directory) that this skill copies or scaffolds from the main working tree. Use this skill whenever the user wants to test branch changes in a worktree, run subwave from a worktree, "prep"/"set up" a worktree for dev mode, or asks to copy env files / node_modules / state into a worktree — phrases like "test this worktree in dev mode", "start subwave from the worktree", "prep the worktree", "run my branch locally", "copy the required files into the worktree". Do NOT use it for the main checkout (that's subwave-control) or for production.

git rev-parse --absolute-git-dir          # a worktree's is <main>/.git/worktrees/<name>
git worktree list                         # shows the main tree + every linked worktree

# Kill the web dev server if it holds :7700 — but only if it is `node`,
# never macOS ControlCenter/AirPlay.
WEB_PID=$(lsof -nP -iTCP:7700 -sTCP:LISTEN -t 2>/dev/null | head -1)
[ -n "$WEB_PID" ] && ps -p "$WEB_PID" -o comm= | grep -qi node && kill "$WEB_PID"

# Bring down whichever dev stack is up. The compose file lives at the
# checkout root (not under docker/); container names are global, so any
# checkout's docker-compose.dev.yml targets the running containers.
docker compose -f <some-checkout>/docker-compose.dev.yml down

bash "<skill base directory>/scripts/prep-worktree.sh" <worktree-path>

cd <worktree-path> && docker compose -f docker-compose.dev.yml up -d --build

cd <worktree-path>/web && npm run dev

sleep 5
curl -sf http://localhost:7701/health                               # expect {"status":"on-air"}
curl -sf -o /dev/null -w '%{http_code}\n' http://localhost:7700      # expect 200

© perminder-klair, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in .claude/skills/subwave-worktree-dev of perminder-klair/subwave.

• SKILL.md
• scripts/prep-worktree.sh

Open the folder on GitHubat commit 45ef433