Skip to content
Skills Library
Programming · Learning & explanation

worktree-guide

/worktree-guide

Interactive guide for parallel development with Ghostty, git worktrees, and Lazygit. Use when setting up multi-task workflows or learning the worktree system.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Interactive guide for parallel development with Ghostty, git worktrees, and Lazygit. Use when setting up multi-task workflows or learning the worktree system.

Original author description

Interactive guide for parallel development with Ghostty, git worktrees, and Lazygit. Use when setting up multi-task workflows or learning the worktree system.

How it works

  1. Preflight
  2. Phase 1: Welcome & Context Detection
  3. Phase 2: Ghostty Essentials
  4. Phase 3: Lazygit Essentials
  5. Phase 4: Complete Workflow (Guided)
  6. Phase 5: Troubleshooting
  7. Phase 6: Quick Reference Card
  8. Guardrails
Original SKILL.md headings · 405 lines, 1,569 words
SKILL.md preview
---
name: worktree-guide
description: Interactive guide for parallel development with Ghostty, git worktrees, and Lazygit. Use when setting up multi-task workflows or learning the worktree system.
license: MIT
metadata:
  author: claude-code-templates
  version: "1.0"
---

Guide the user through parallel development workflows using Ghostty terminal panels, git worktrees, and Lazygit. This is both a teaching experience and a practical reference.

---

## Preflight

Before starting, detect the user's environment:

```bash
git rev-parse --is-inside-work-tree 2>&1 && echo "GIT_OK" || echo "NOT_GIT"
```

**If not a git repo:**
> This isn't a git repository. Navigate to a git project first, then come back to `/worktree-guide`.

Check if we're in a worktree or main repo:
```bash
git worktree list
pwd
```

Note the context for later guidance.

---

## Phase 1: Welcome & Context Detection

Display based on environment:

**If in main repo:**
```
## Worktree Parallel Development Guide

Welcome! I'll guide you through setting up and using parallel worktrees for multi-task development.

┌─────────────────────────────────────────────────────────────┐
│  Ghostty Terminal                                           │
│  ┌──────────────────────┬──────────────────────┐           │
│  │                      │                      │           │
│  │   Claude (Task 1)    │   Claude (Task 2)    │           │
│  │   claude/login-page   │   claude/fix-auth-bug │           │
│  │                      │                      │           │
│  ├──────────────────────┴──────────────────────┤           │
│  │              Lazygit (monitoring)           │           │
│  └─────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

**Your workflow:**
1. Create worktrees → `/worktree-init`
2. Open Ghostty panels → `Cmd+D` / `Cmd+Shift+D`
3. Run Claude in each panel → `cd <worktree> && claude`
4. Deliver when done → `/worktree-deliver`
5. Clean up → `/worktree-cleanup`

What would you like to do?
```

Use AskUserQuestion:
- "Learn the full workflow" — Start from Phase 2
- "Just show keybindings" — Jump to Quick Reference
- "Create worktrees now" — Suggest `/worktree-init`
- "Something else" — Ask what they need

**If already in a worktree:**
```
## Worktree Status

You're already inside a worktree! Let me check your status.
```

Then run the equivalent of `/worktree-check` and provide contextual guidance.

---

## Phase 2: Ghostty Essentials

**EXPLAIN:**
```
## Ghostty Panel Management

Ghostty's panel system is perfect for parallel development. Here are the essential keybindings:
```

**SHOW:**
```
┌─────────────────────────────────────────────────────────────┐
│                    GHOSTTY KEYBINDINGS                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  SPLITTING                                                  │
│  ─────────                                                  │
│  Cmd+D           Split panel to the right                   │
│  Cmd+Shift+D     Split panel below                          │
│                                                             │
│  NAVIGATION                                                 │
│  ─────────                                                  │
│  Cmd+Alt+←/→/↑/↓ Move focus between panels                  │
│  Cmd+[/]         Cycle through panels                       │
│                                                             │
│  SIZING                                                     │
│  ─────────                                                  │
│  Cmd+Shift+E     Equalize all panel sizes                   │
│  Cmd+Shift+F     Toggle zoom (fullscreen current panel)     │
│                                                             │
│  CLOSING                                                    │
│  ─────────                                                  │
│  Cmd+W           Close current panel                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

**Pro tip:** Use Cmd+Shift+F to zoom into a panel when you need focus, then press it again to return to the multi-panel view.
```

**PAUSE** - "Ready to learn about Lazygit? (Or skip to workflow)"

---

## Phase 3: Lazygit Essentials

**EXPLAIN:**
```
## Lazygit for Monitoring Worktrees

Lazygit gives you a visual overview of all your worktrees and their changes. Run it from your main repo to monitor everything.
```

**SHOW:**
```
┌─────────────────────────────────────────────────────────────┐
│                    LAZYGIT KEYBINDINGS                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  WORKTREES (navigate to Worktrees panel)                    │
│  ─────────                                                  │
│  w              Switch to worktree panel (or create new)    │
│  Enter          Switch to selected worktree                 │
│  n              Create new worktree                         │
│  d              Delete worktree (with confirmation)         │
│                                                             │
│  FILES & STAGING                                            │
│  ─────────                                                  │
│  Space          Stage/unstage file                          │
│  a              Stage all files                             │
│  Enter          View file diff (with Delta highlighting)    │
│                                                             │
│  COMMITS                                                    │
│  ─────────                                                  │
│  c              Commit staged changes                       │
│  C              Commit with editor                          │
│  A              Amend last commit                           │
│                                                             │
│  SYNC                                                       │
│  ─────────                                                  │
│  P              Push                                        │
│  p              Pull                                        │
│  f              Fetch                                       │
│                                                             │
│  GENERAL                                                    │
│  ─────────                                                  │
│  ?              Help (context-sensitive)                    │
│  q              Quit / go back                              │
│  Tab            Switch panels                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

**Monitoring workflow:**
1. Open lazygit in the main repo (or a dedicated Ghostty panel)
2. Press `w` to see all worktrees
3. Use Enter to dive into any worktree's changes
4. Press `q` to go back to the worktree list
```

**PAUSE** - "Ready for the full workflow walkthrough?"

---

## Phase 4: Complete Workflow (Guided)

**EXPLAIN:**
```
## Full Parallel Development Workflow

Let me walk you through the complete cycle. We'll go step by step.
```

### Step 4.1: Create Worktrees

**EXPLAIN:**
```
### Step 1: Create Worktrees

First, define the tasks you want to work on in parallel. The `/worktree-init` command creates a worktree for each task.
```

**DO:** Show example command:
```
Example usage:

/worktree-init add user authentication | fix login bug | improve dashboard performance

This creates:
├── ../worktrees/<repo>/claude-add-user-authentication/
├── ../worktrees/<repo>/claude-fix-login-bug/
└── ../worktrees/<repo>/claude-improve-dashboard-performance/
```

### Step 4.2: Open Ghostty Panels

**EXPLAIN:**
```
### Step 2: Open Ghostty Panels

Now split your terminal into panels—one for each task, plus optionally one for Lazygit monitoring.
```

**DO:**
```
1. Press Cmd+D to split right (first worktree)
2. Press Cmd+D again (second worktree)
3. Optionally press Cmd+Shift+D on any panel for Lazygit below

Resulting layout:
┌──────────┬──────────┬──────────┐
│ Task 1   │ Task 2   │ Task 3   │
│ claude   │ claude   │ claude   │
├──────────┴──────────┴──────────┤
│           lazygit              │
└────────────────────────────────┘
```

### Step 4.3: Work in Each Panel

**EXPLAIN:**
```
### Step 3: Work Independently

In each panel:
1. cd to the worktree path (from the commands output)
2. Run `claude` to start a Claude session
3. Use `/worktree-check` anytime to verify which task you're working on
4. Work normally—Claude doesn't know about other panels
```

### Step 4.4: Deliver Completed Work

**EXPLAIN:**
```
### Step 4: Deliver When Done

When you finish a task in any panel, use `/worktree-deliver` to:
1. Review your changes
2. Create a commit
3. Push to remote
4. Create a pull request
```

### Step 4.5: Clean Up

**EXPLAIN:**
```
### Step 5: Clean Up After Merging

After your PRs are merged on GitHub:
1. Go back to the main repo (not a worktree)
2. Run `/worktree-cleanup --all`
3. It removes merged worktrees and branches
```

---

## Phase 5: Troubleshooting

**SHOW:**
```
## Troubleshooting

### "I'm not sure which worktree I'm in"

Run `/worktree-check` — it shows your branch, task, and status.

Alternatively:
$ git branch --show-current    # Shows claude/<name>
$ pwd                          # Shows the worktree path

---

### "I have uncommitted changes and want to switch tasks"

**Option 1:** Commit work-in-progress
$ git add . && git commit -m "wip: progress on feature"

**Option 2:** Stash changes (temporary)
$ git stash push -m "wip: parking changes"

Then in the other panel, continue working. Come back later with:
$ git stash pop

---

### "I accidentally started working in the wrong worktree"

1. Stash your changes: `git stash push -m "work done in wrong place"`
2. Navigate to the correct worktree
3. Apply the stash: `git stash pop`

---

### "My worktree has merge conflicts"

1. Run `git fetch origin` to get latest
2. Run `git rebase origin/main` (or merge if you prefer)
3. Resolve conflicts in your editor
4. `git add .` then `git rebase --continue`

---

### "I want to abandon a worktree"

From the main repo:
$ git worktree remove ../worktrees/repo/claude-<name> --force
$ git branch -D claude/<name>

Note: Force is needed if there are uncommitted changes.

---

### "/worktree-deliver failed on push"

Usually means the remote branch doesn't exist yet or there's a conflict.

Try:
$ git push -u origin HEAD

If there's a conflict with remote, pull first:
$ git pull --rebase origin claude/<name>

---

### "The worktree path doesn't exist anymore"

The worktree was probably deleted manually. Clean up the git state:
$ git worktree prune
```

---

## Phase 6: Quick Reference Card

**SHOW:**
```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         WORKTREE QUICK REFERENCE                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  COMMANDS                                                                   │
│  ─────────                                                                  │
│  /worktree-init <task1> | <task2>    Create worktrees for parallel tasks    │
│  /worktree-check                     Show current worktree status & task    │
│  /worktree-deliver                   Commit, push, and create PR            │
│  /worktree-cleanup --all             Remove merged worktrees and branches   │
│  /worktree-cleanup --dry-run         Preview what would be cleaned up       │
│                                                                             │
│  GHOSTTY                                                                    │
│  ─────────                                                                  │
│  Cmd+D              Split right     │  Cmd+Shift+E    Equalize panels      │
│  Cmd+Shift+D        Split down      │  Cmd+Shift+F    Zoom toggle          │
│  Cmd+Alt+Arrows     Navigate        │  Cmd+W          Close panel          │
│                                                                             │
│  LAZYGIT                                                                    │
│  ─────────                                                                  │
│  w                  Worktrees panel │  Space          Stage/unstage        │
│  Enter              View diff       │  c              Commit               │
│  P                  Push            │  ?              Help                 │
│                                                                             │
│  GIT (manual)                                                               │
│  ─────────                                                                  │
│  git worktree list                   List all worktrees                     │
│  git worktree add -b claude/name path Create worktree manually               │
│  git worktree remove path            Remove a worktree                      │
│  git worktree prune                  Clean up stale worktree refs           │
│                                                                             │
│  WORKFLOW                                                                   │
│  ─────────                                                                  │
│  1. /worktree-init tasks...          Create worktrees                       │
│  2. Cmd+D (split panels)             Open Ghostty panels                    │
│  3. cd <path> && claude              Start Claude in each                   │
│  4. /worktree-deliver                PR when done                           │
│  5. /worktree-cleanup                Clean up after merge                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Guardrails

- **Never execute destructive commands** without confirmation (worktree remove, branch delete)
- **Always verify location** before suggesting worktree operations
- **If user seems lost**, offer `/worktree-check` first
- **Never force-delete** branches that aren't merged
- **Don't assume tools are installed** — check for lazygit availability if suggesting it
- **Respect user's pace** — don't rush through sections if they want to practice
- **Keep the reference card available** — offer to show it whenever relevant

Versions

The database has no other skills named worktree-guide.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version f3f34785d6fe (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100git-worktrees
    Git worktree management for parallel agent team development. Triggers: 'create worktree', 'worktree setup', or during /delegate dispatch. Do NOT use for branch creation without delegation context.
  • 100git-worktree-manager
    Run parallel feature work safely with Git worktrees. Standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app. Optimized for multi-agent workflows where each agent or terminal session owns one worktree.…
  • 95git-worktree
    This skill should be used when managing Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface.
  • 100worktree
    Manages git worktrees with git-wt, including PR checkouts. Use when the user asks to create, switch, or delete a worktree, or check out a PR.
  • 100lazygit
    Expert Lazygit terminal UI assistance covering git staging, interactive rebasing, branch management, cherry-picking, and diff inspection. Use when managing Git repositories with keyboard speed.
  • 100git-worktree-finish
    Use when the user asks to finish, land, or merge back a feature worktree created with /git-worktree.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.