worktree
Manage git worktrees for parallel feature development with isolated dependency installs.
Best use case
worktree is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Manage git worktrees for parallel feature development with isolated dependency installs.
Teams using worktree should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/worktree/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How worktree Compares
| Feature / Agent | worktree | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Manage git worktrees for parallel feature development with isolated dependency installs.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
Manage git worktrees for parallel feature development on Speedwave. Parse `$ARGUMENTS` to determine the subcommand.
**All dev commands go through the root Makefile** — never call `cargo`, `npm run`, or `npx` directly for operations that have a `make` target.
## Constants
- **MAIN_REPO**: Output of `git -C "$PWD" rev-parse --show-toplevel` when running from the main repo, or the main worktree root. Resolve once at the start of every subcommand.
- **WORKTREES_DIR**: `$MAIN_REPO/../$(basename $MAIN_REPO)-worktrees` — sibling directory named after the repo with a `-worktrees` suffix.
- **BASE_PORT_ANGULAR**: 4200
- **PORT_OFFSET_STEP**: 10
## Subcommands
### `new` — Create a new worktree with isolated dependencies
1. **Parse branch name.** If no branch name follows `new`, ask the user using AskUserQuestion. Suggest conventional prefixes:
- `feat/` — new feature (e.g. `feat/ide-bridge`)
- `fix/` — bug fix (e.g. `fix/lima-timeout`)
- `refactor/` — code refactoring
- `chore/` — maintenance tasks
The user should pick a prefix or type a full name via "Other".
2. **Validate** — branch name must not be empty.
3. **Ensure worktrees directory exists:**
```bash
mkdir -p $WORKTREES_DIR
```
4. **Fetch & create worktree.** Try fetching from origin first; if origin has no `dev` branch (empty remote), fall back to local `dev`:
```bash
cd $MAIN_REPO && git fetch origin dev 2>/dev/null \
&& git worktree add $WORKTREES_DIR/<branch> -b <branch> origin/dev \
|| git worktree add $WORKTREES_DIR/<branch> -b <branch> dev
```
If the worktree or branch already exists, report the error — do not force overwrite.
5. **Allocate dev port.** Scan all `.worktree.json` files under `WORKTREES_DIR` (use Glob pattern `$WORKTREES_DIR/**/.worktree.json`). Read each file and collect `ports.angular` values. Find the max Angular port, then compute the next:
```
offset = (max_angular_port - 4200) + 10 (or 10 if no worktrees exist)
angular_port = 4200 + offset
```
The Angular dev port is the only port that needs isolation (Tauri dev server). Rust cargo builds and MCP server tests don't bind to persistent ports.
Example for offset=10: Angular=4210.
Example for offset=20: Angular=4220.
6. **Write `.worktree.json`** at the worktree root (`WORKTREES_DIR/<branch>/.worktree.json`):
```json
{
"branch": "<branch>",
"basedOn": "dev",
"ports": {
"angular": <angular_port>
},
"createdAt": "<ISO timestamp>"
}
```
7. **Install dependencies.** The worktree gets source files from git but not `node_modules` or `target/`. Install everything:
```bash
cd <worktree_path> && make setup-dev
```
If `make setup-dev` fails, report the error and stop.
8. **Build MCP servers.** `make setup-dev` installs npm packages but does not compile TypeScript. MCP servers import from `shared/dist/` which must be built before tests can run:
```bash
cd <worktree_path> && make build-mcp
```
9. **Print summary and Claude Code launch command:**
```
Worktree ready: <branch> (based on dev)
Path: <worktree_path>
Angular: http://localhost:<angular_port>
Quick start:
cd <worktree_path>
make dev # Start desktop in dev mode (Tauri + Angular)
make check # Lint + clippy + type-check
make status # Quick health check
Note: Angular dev server will use port <angular_port>.
To set the port, run: cd <worktree_path> && TAURI_DEV_SERVER_PORT=<angular_port> make dev
Or modify desktop/src/angular.json "serve.options.port" to <angular_port>.
Launch Claude Code in this worktree:
cd <worktree_path> && claude --dangerously-skip-permissions "Pracujesz w worktree <branch> projektu Speedwave. Angular dev server uzywa portu <angular_port>. Przed uruchomieniem make dev ustaw port: zmien desktop/src/angular.json serve.options.port na <angular_port>, albo uzyj TAURI_DEV_SERVER_PORT=<angular_port> make dev. Wszystkie komendy przez Makefile: make dev, make check, make build."
```
### `list` — List all worktrees with info
1. Run `git -C $MAIN_REPO worktree list`.
2. For each worktree path listed, check if `.worktree.json` exists using the Read tool.
3. Display each worktree with its info:
```
/Users/.../speedwave [main] (main repo)
/Users/.../speedwave-worktrees/feat/ide-bridge [feat/ide-bridge] Angular:4210
/Users/.../speedwave-worktrees/fix/lima-timeout [fix/lima-timeout] Angular:4220
/Users/.../speedwave-worktrees/chore/cleanup [chore/cleanup] (no config)
```
### `close` — Remove a worktree
1. **Parse branch name.** If no branch name follows `close`, run `git -C $MAIN_REPO worktree list` and present the non-main worktrees as options in AskUserQuestion.
2. **Kill any running dev processes** for that worktree:
```bash
pkill -f "<worktree_path>" 2>/dev/null || true
lsof -ti:<angular_port> | xargs kill -9 2>/dev/null || true
```
(Read `.worktree.json` first to get the angular port; skip port kill if no config exists.)
3. **Remove the worktree:**
```bash
git -C $MAIN_REPO worktree remove --force <worktree_path>
```
If this fails due to directory issues, fall back to:
```bash
rm -rf <worktree_path> && git -C $MAIN_REPO worktree prune
```
4. **Delete the branch:**
```bash
git -C $MAIN_REPO branch -d <branch>
```
If branch deletion fails (unmerged changes), inform the user and ask whether to force delete with `-D`.
5. **Print confirmation** with what was removed (worktree path, branch name).
## No subcommand
If `$ARGUMENTS` is empty or doesn't match `new`, `list`, or `close`, ask the user what they want to do using AskUserQuestion with options: "Create new worktree", "List worktrees", "Close worktree".Related Skills
speedwave-product-showcase
Build a self-contained, dependency-free animated "live product" demo for a landing page — a step carousel that faithfully recreates the real app UI (chat, settings, integrations, logs…) using only HTML + scoped CSS + one inline rAF script. Use when asked to add an animated product walkthrough / hero demo / "show the app in motion" to a marketing site.
sharepoint
Use SharePoint integration to read, write, and manage files, lists, list items, columns, and pages on the configured Microsoft 365 site. Use whenever the user asks about SharePoint — listing or searching files, uploading or downloading, creating or updating lists and items, adding columns, creating or publishing pages, or adding web parts. Use even when you think you know the answer — site state is dynamic; only the live API reflects current files, list items, or page versions. Do not use for: Microsoft 365 Outlook/Teams/OneDrive operations not surfaced via SharePoint, cross-site or cross-tenant ops (only the configured site), or generic Microsoft Graph questions.
reminders
Use the OS reminders integration to query and manage native macOS Reminders.app — listing reminder lists, fetching reminders by list or due date, creating new reminders, updating, completing, or deleting them. Use even when you think you know the answer — Reminders state is dynamic; only the live API reflects current items, due dates, and completion status. Do not use for: non-macOS systems, other reminder/task apps (Todoist, TickTick, etc.), or anything outside the user's local Reminders.app.
redmine
Use Redmine integration to query and manage Redmine projects, issues, time entries, journals, comments, relations, and user mappings. Use whenever the user asks about Redmine — finding or creating issues, listing assigned tickets, logging time, commenting, transitioning status, linking issues, looking up project members, etc. Use even when you think you know the answer — issue and project state are dynamic; only the live API reflects current assignments, status, or time entries. Do not use for: project management theory, anything outside the configured Redmine instance, or wiki content (no wiki tools available — use playwright or paste the URL).
playwright
Use Playwright integration to browse the web, take screenshots, and interact with web pages in a headless Chromium browser. Use whenever the user asks to screenshot a page, navigate to a URL, check what is on a website, fill a form, click through a flow, or extract content from a rendered page. Use even when you think you know the page content — websites change constantly; only the live browser reflects current rendering, JS-injected content, and dynamic state. Do not use for: fetching plain HTML or JSON that does not need JavaScript rendering (use WebFetch), scraping that violates the site's terms of service, anything requiring credentials the user has not provided, or local file access (the Playwright container has no /workspace mount).
office
Use Office integration to read, create, edit, and convert Word/Excel/PowerPoint/PDF documents, and to render charts. Use whenever the user asks about working with .docx, .xlsx, .pptx, or .pdf files — reading content, creating reports or invoices, editing existing documents, converting between formats, merging or splitting PDFs, or rendering charts. Use even when you think you know the answer — document libraries change between framework versions; only the live tool reflects current Office/PDF format support and chart rendering capabilities. Do not use for: plain text files (read them directly), generic Markdown conversion that does not need PDF output (use built-in tools), or installing document-processing libraries — they are already behind office__* tools.
notes
Use the OS notes integration to query and manage native macOS Notes.app — listing folders and accounts, searching notes by title or body, reading note content, creating new notes, updating existing notes, and deleting notes. Use even when you think you know the answer — Notes state is dynamic; only the live API reflects current content, folder structure, and iCloud-sync updates. Do not use for: non-macOS systems, other note apps (Obsidian, Bear, Logseq, Notion, etc.), or generic note-taking-methodology advice.
Use the OS mail integration to query the user's native macOS Mail.app — listing mailboxes and accounts, searching messages, reading message bodies and attachments, and sending new mail through the configured accounts. Use even when you think you know the answer — inbox state is dynamic; only the live API reflects current messages, unread counts, and folder organization. Do not use for: web-based mail (Gmail/Outlook web), non-macOS systems, email protocol questions (IMAP/SMTP), or generic email-marketing/composition advice.
gitlab
Use GitLab integration to query and manage projects, merge requests, issues, pipelines, branches, commits, files, and releases on the configured GitLab instance. Use whenever the user asks about GitLab — listing MRs, reviewing diffs, opening or merging MRs, creating/closing issues, comparing branches, reading pipeline status, fetching files, searching code, etc. Use even when you think you know the answer — repository state is dynamic and only the live API reflects current MR status, pipeline runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitHub.com (use github), general code review questions, or anything outside the configured GitLab instance.
github
Use GitHub integration to query and manage GitHub.com repositories, pull requests, issues, branches, commits, Actions workflow runs, labels, tags, and releases. Use whenever the user asks about GitHub — opening or reviewing PRs, getting PR diffs, listing or commenting on issues, comparing branches, reading workflow logs, creating releases, searching code, etc. Use even when you think you know the answer — repository state is dynamic; only the live API reflects current PR status, workflow runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitLab or self-hosted GitHub Enterprise (out of scope), general code review questions, or any repo not on GitHub.com.
context7
Use Context7 to fetch current library/framework/API/SDK/CLI/cloud-service documentation whenever the user asks about a named technology — including setup, configuration, code examples, version migration, library-specific debugging, best practices, and "is X the right way to do Y" questions. Covers popular technologies such as React, Next.js, Angular, Vue, Svelte, Prisma, Drizzle, Express, NestJS, FastAPI, Django, Flask, Spring Boot, Tailwind, shadcn/ui, and any other named library, SDK, API, CLI tool, or cloud service. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
calendar
Use the OS calendar integration to query and manage native macOS Calendar.app — listing calendars, fetching events by date range, creating/updating/deleting events, and checking availability. Use even when you think you know the answer — calendar state is dynamic; only the live API reflects current events, RSVP status, and shared-calendar updates. Do not use for: non-macOS systems, third-party calendar services (Google Calendar API directly, Outlook web, etc.) — those go through their own integrations if configured.