gtr (Git Worktree Runner) Workflow

git gtr is a CLI tool that wraps git worktree with quality-of-life features for parallel AI-assisted development.

Core Commands

git gtr new <branch>           # Create worktree
git gtr editor <branch>        # Open in editor (cursor/vscode/zed)
git gtr ai <branch>            # Start AI tool (claude/aider/codex)
git gtr go <branch>            # Print path (use: cd "$(git gtr go feature)")
git gtr run <branch> <cmd>     # Run command in worktree
git gtr rm <branch>            # Remove worktree
git gtr list                   # List all worktrees
git gtr copy <branch> -- <pattern>  # Copy files to worktree

Special ID 1 references the main repo: git gtr go 1, git gtr ai 1

Installation

git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr

Initial Setup (per repository)

cd ~/your-project
git gtr config set gtr.editor.default cursor
git gtr config set gtr.ai.default claude

ブランチの起点に注意（重要）

git gtr new <branch> はデフォルトで gtr.defaultBranch（通常は develop や main）からブランチを作成する。 featureブランチから派生させたい場合は必ず --from-current または --from を指定すること。

# 現在のブランチから作成（最もよく使う）
git gtr new feature/child-branch --from-current

# 特定のブランチから作成
git gtr new feature/child-branch --from feature/parent-branch

# NG: featureブランチにいてもデフォルトではdevelopから作成されてしまう
git gtr new feature/child-branch  # → developベースになる！

Parallel Development Workflow

Single Feature with Claude Code

git gtr new feature-auth
git gtr ai feature-auth
# Claude Code runs in isolated worktree
# Main repo remains untouched
git gtr rm feature-auth  # Cleanup when done

Multiple Parallel Claude Sessions

# Terminal 1: API work
git gtr new feature-api
git gtr ai feature-api

# Terminal 2: UI work
git gtr new feature-ui
git gtr ai feature-ui

# Terminal 3: Tests
git gtr new feature-tests
git gtr ai feature-tests

Each session has isolated context - no stashing, no branch switching.

Same Branch, Multiple Worktrees

Use --force with --name for parallel work on the same feature:

git gtr new feature-auth
git gtr new feature-auth --force --name backend
git gtr new feature-auth --force --name frontend
# Creates: feature-auth/, feature-auth-backend/, feature-auth-frontend/
# All on same branch - coordinate commits carefully

PR Review While Working

# Working on feature
git gtr new my-feature
git gtr ai my-feature

# Need to review PR - create separate worktree
git gtr new review-pr-123 --from origin/pr-branch
git gtr editor review-pr-123
# Review without interrupting Claude session
git gtr rm review-pr-123

Configuration

Team-Shared Config (.gtrconfig)

Create .gtrconfig in repo root:

[copy]
include = **/.env.example
include = **/CLAUDE.md
exclude = **/.env

[copy]
includeDirs = node_modules
excludeDirs = node_modules/.cache

[hooks]
postCreate = npm install

[defaults]
editor = vscode
ai = claude

Copy Files to Worktrees

# Add patterns to config
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/CLAUDE.md"

# Copy node_modules to avoid npm install
git gtr config add gtr.copy.includeDirs "node_modules"

Post-Create Hooks

git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "cp .env.example .env"

Branch Name Mapping

Slashes and special characters become hyphens:

• feature/user-auth → folder feature-user-auth
• fix/bug#123 → folder fix-bug-123

Worktree作成前の確認

1. .gtrconfig の確認

worktree作成前に、プロジェクトルートに .gtrconfig が存在するか確認する。 なければ以下の内容で作成し、コミットする:

[copy]
include = **/.env*
include = **/CLAUDE.md

[hooks]
postCreate = npm install

これにより、worktree作成時に自動で npm install が実行される。

2. ベースブランチの確認

現在のブランチが develop / main 以外（featureブランチ等）の場合、 worktree作成時に 必ず --from-current を付けること。 付け忘れると develop ベースになり、featureブランチの変更が含まれない。

# featureブランチから派生する場合
git gtr new feature/child --from-current

Best Practices

1. One worktree per task - Keep Claude sessions focused
2. Copy CLAUDE.md - Include project context in each worktree
3. Use hooks - Automate dependency installation
4. Clean up regularly - git gtr rm when PRs merge
5. Use git gtr list - Track active worktrees

Troubleshooting

git gtr doctor          # Health check
git gtr adapter         # List available editors/AI tools
git gtr clean           # Remove stale worktrees
git gtr clean --merged  # Remove worktrees for merged PRs (requires gh CLI)