Skip to content

README.md

Latest commit

 

History

History
123 lines (86 loc) · 3.65 KB

README.md

File metadata and controls

123 lines (86 loc) · 3.65 KB

claude-worktrees

Isolated git worktree workspaces for running parallel Claude Code sessions across a monorepo.

The problem

You have a monorepo with multiple sub-projects (e.g. backend/, frontend/, infra/). You want to work on several features at the same time, each in its own Claude Code session. But if two sessions touch the same repo directory, they'll collide — uncommitted changes, conflicting branches, confused context.

How it works

These scripts use git worktrees to create isolated copies of your repos, each on its own branch, inside a named workspace directory. Each workspace gets:

  • A git worktree per repo, checked out to a branch named after the task
  • A symlink to your root CLAUDE.md (so all sessions share the same project guidance)
  • A copy of your .claude/ config (project settings, permissions) — but not plans or memory, which stay per-session
your-monorepo/
├── backend/              ← main working copies
├── frontend/
├── infra/
├── tasks/
│   ├── add-webhooks/     ← workspace: isolated branches
│   │   ├── backend/      ← worktree on branch "add-webhooks"
│   │   ├── infra/        ← worktree on branch "add-webhooks"
│   │   ├── CLAUDE.md     ← symlink to root
│   │   └── .claude/      ← copied config
│   └── redesign-feed/
│       ├── frontend/     ← worktree on branch "redesign-feed"
│       ├── CLAUDE.md
│       └── .claude/
├── task-new.sh
├── task-done.sh
├── repos.conf
└── CLAUDE.md

You can run as many workspaces as you want simultaneously. Each gets its own branches, so there are no conflicts.

Setup

  1. Place task-new.sh and task-done.sh in the root of your monorepo (alongside your repo directories).

  2. Create a repos.conf file listing your repo directory names, one per line:

cp repos.conf.example repos.conf
# repos.conf
backend
frontend
infra
  1. Make the scripts executable (they should already be):
chmod +x task-new.sh task-done.sh

Usage

Create a workspace

# Workspace with specific repos
./task-new.sh add-webhooks backend infra

# Workspace with all repos
./task-new.sh big-refactor

This creates tasks/add-webhooks/ with a worktree per repo, each on a new branch called add-webhooks.

Work in it

Open Claude Code in the workspace directory:

cd tasks/add-webhooks
claude

Claude Code picks up the symlinked CLAUDE.md and copied .claude/ config automatically.

Tear it down

# Remove the workspace, keep the branches (can resume later)
./task-done.sh add-webhooks

# Remove the workspace and delete the branches
./task-done.sh add-webhooks --delete-branches

List active workspaces

./task-done.sh
# prints usage + lists all active workspaces under tasks/

Requirements

  • Bash 4+
  • Git with worktree support (Git 2.5+)

FAQ

Can I use this without Claude Code? Yes. The worktree isolation is useful for any parallel development workflow. The CLAUDE.md symlink and .claude/ copy are no-ops if those files don't exist.

What happens if I forget to tear down a workspace? Nothing bad. The worktrees and branches just stick around. Run task-done.sh whenever you're ready to clean up.

Can two workspaces include the same repo? No — git worktrees require unique branches per repo. If workspace A already has backend on branch task-a, workspace B can't also create a backend worktree on branch task-b from the same source. Each workspace gets its own branch name, so this works naturally as long as task names are unique.

License

MIT