DavidROliverBA/ArchitectKB / .claude/skills/worktree
worktree
VerifiedCreate and manage git worktrees for parallel agent sessions
Worktree Management
Manage git worktrees for parallel Claude Code sessions and subagent dispatch.
Commands
| Command | Usage | Purpose |
|---|---|---|
/worktree create <slug> | Create a new worktree | Isolated workspace for parallel work |
/worktree list | List active worktrees | See what's running |
/worktree merge <slug> | Merge and clean up | Bring work back to main |
/worktree cleanup <slug> | Remove without merging | Abandon a worktree |
Execution
All commands delegate to .claude/scripts/worktree-manager.sh:
.claude/scripts/worktree-manager.sh <command> [slug]
IMPORTANT: The script operates on the vault root. Always run from the vault directory. Use dangerouslyDisableSandbox: true because worktrees are created outside the vault directory (sibling path).
Slug Rules
- Lowercase alphanumeric with hyphens:
meeting-notes-batch,architecture-review - Becomes the branch name:
worktree/<slug> - Becomes the directory name:
../<vault>-worktrees/<slug>/
Dispatching Subagents to Worktrees
After creating a worktree, dispatch subagents with the worktree path as their working directory:
1. Create worktree: /worktree create meeting-notes-batch
2. Note the path from output (e.g. /Users/.../BA-DavidOliver-ObsidianVault-worktrees/meeting-notes-batch)
3. Dispatch subagent with Task tool, including in the prompt:
"Work in /Users/.../BA-DavidOliver-ObsidianVault-worktrees/meeting-notes-batch"
4. When subagent completes: /worktree merge meeting-notes-batch
Multi-Session Usage
For separate Claude Code terminals working in parallel:
- Session A:
/worktree create feature-alpha→ opens terminal in worktree path - Session B:
/worktree create feature-beta→ opens terminal in worktree path - Each session works independently
- When done:
/worktree merge feature-alpha(from the main vault session)
Conventions
- Branch naming:
worktree/<slug>— visually distinct in git log - Merge strategy:
--no-fffor clean merge commits - Config copied:
.claude/and.mcp.jsonare copied to each worktree - Not copied:
.obsidian/— worktrees are agent workspaces, not Obsidian vaults - Location: Sibling directory
../<vault>-worktrees/<slug>/(outside vault, invisible to Obsidian)
Troubleshooting
| Issue | Fix |
|---|---|
| "slug required" | Provide a slug: /worktree create my-task |
| Merge conflicts | Resolve manually in main, then git worktree remove |
| Sandbox blocks worktree creation | Use dangerouslyDisableSandbox: true |
| Worktree already exists | Idempotent — reuses existing worktree |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Unverified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |