Claude-code-templates 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.
install
source · Clone the upstream repo
git clone https://github.com/davila7/claude-code-templates
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/davila7/claude-code-templates "$T" && mkdir -p ~/.claude/skills && cp -r "$T/cli-tool/components/skills/development/worktree-guide" ~/.claude/skills/davila7-claude-code-templates-worktree-guide && rm -rf "$T"
manifest:
cli-tool/components/skills/development/worktree-guide/SKILL.mdsource content
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:
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:
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-checkPhase 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
first/worktree-check - 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