Skip to content

DR-010: Git Worktree-Based Multi-Workspace Development

Home › Reference › Decision Records › Dr010

Status

  • [x] Accepted
  • [ ] Proposed
  • [ ] Rejected
  • [ ] Deprecated
  • [ ] Superseded

Date: 2024-12-20

Context

Developers use Claude Code for AI-assisted development, often working on multiple features simultaneously. Need isolated environments with shared history.

Problem: How to enable parallel Claude Code sessions without context conflicts?

Decision

Git worktrees for parallel development with dedicated work commands.

Workspace Lifecycle:

  • work create <branch> - Create new worktree
  • work pull - Sync with main via rebase
  • work merge - Squash merge back to main
  • work remove - Delete worktree and branch
  • show workspaces - List active worktrees

Directory Structure:

eac/                  # Main workspace
../eac-feature-x/     # Worktree for feature-x
../eac-feature-y/     # Worktree for feature-y

Claude Code Integration:

  • Plan → Clear → Implement pattern
  • Each workspace = one Claude session
  • Isolated file changes per workspace
  • Agents use workspace-aware operations

Workflow Pattern:

  1. Create workspace for feature
  2. Run Claude Code session in workspace
  3. Implement feature with AI assistance
  4. Merge back to main (squash commits)
  5. Remove workspace when done

Consequences

Positive: Parallel sessions, isolated environments, shared history, fast switching, no stashing, context separation

Negative: Disk space (multiple working trees), user must manage workspaces, worktree commands unfamiliar

Alternatives Considered

  1. Branch Switching: Rejected - slow, requires stashing, context loss, file churn
  2. Git Stash: Rejected - error-prone, conflicts common, lost work risk
  3. Separate Clones: Rejected - no shared git history, duplication, sync issues

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.