Skip to content

feat: add worktree isolation utilities for parallel sessions#96

Open
reshashi wants to merge 1 commit intogarrytan:mainfrom
reshashi:feat/worktree-utils
Open

feat: add worktree isolation utilities for parallel sessions#96
reshashi wants to merge 1 commit intogarrytan:mainfrom
reshashi:feat/worktree-utils

Conversation

@reshashi
Copy link

Summary

Adds two utility scripts for managing isolated git worktrees, enabling multiple Claude Code sessions to work on different tasks without file conflicts:

  • scripts/worktree.sh — create/list/remove/clean worktrees with .claude-worktree marker files for branch tracking
  • scripts/branch-guard.sh — prevents accidental commits to the wrong branch by validating the .claude-worktree marker against the current git branch

These complement conductor.json for multi-session orchestration by providing the underlying worktree isolation layer. Conductor is the conductor; these are the tracks.

Usage

# Create isolated worktree for a task
scripts/worktree.sh create myapp auth-flow main

# List active worktrees with branch info
scripts/worktree.sh list myapp

# Remove worktree and delete branch
scripts/worktree.sh remove myapp auth-flow

# Clean all worktrees for a project
scripts/worktree.sh clean myapp

Branch guard (for git hooks)

# In pre-commit hook:
scripts/branch-guard.sh --check-only
# Exit 0 = OK, Exit 1 = wrong branch (blocks commit)

The .claude-worktree marker file (JSON) tracks expected branch, worktree path, session name, and creation timestamp. It is auto-added to .gitignore on creation.

Environment

GSTACK_WORKTREE_BASE overrides the default worktree root (~/.worktrees).

Test plan

  • worktree.sh create creates worktree + branch + .claude-worktree marker
  • worktree.sh list shows branch and creation time from marker
  • worktree.sh remove cleans up worktree, branch, and directory
  • branch-guard.sh returns 0 when on correct branch
  • branch-guard.sh returns 1 when on wrong branch or main/master
  • branch-guard.sh returns 0 when no marker found (not in a worktree)

🤖 Generated with Claude Code

Adds two utility scripts for managing isolated git worktrees, enabling
multiple Claude Code sessions to work on different tasks without file
conflicts.

- worktree.sh: create/list/remove/clean worktrees with .claude-worktree
  marker files for branch tracking
- branch-guard.sh: prevents accidental commits to wrong branch by
  validating .claude-worktree marker against current git branch

These complement conductor.json for multi-session orchestration
by providing the underlying worktree isolation layer.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant