# gtr-workflow

> Git Worktree Runner (gtr) workflow guidance for parallel development with Claude Code. Use when the user asks about git worktrees, parallel AI development, running multiple Claude sessions, managing worktrees with gtr, or setting up isolated development environments for feature work.

- Author: Kazuki Ogawa
- Repository: okazuki58/maclogger
- Version: 20260126122554
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/okazuki58/maclogger
- Web: https://mule.run/skillshub/@@okazuki58/maclogger~gtr-workflow:20260126122554

---

---
name: gtr-workflow
description: Git Worktree Runner (gtr) workflow guidance for parallel development with Claude Code. Use when the user asks about git worktrees, parallel AI development, running multiple Claude sessions, managing worktrees with gtr, or setting up isolated development environments for feature work.
---

# 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

```bash
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

```bash
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)

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

## Parallel Development Workflow

### Single Feature with Claude Code

```bash
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

```bash
# 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:

```bash
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

```bash
# 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:

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

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

[hooks]
postCreate = npm install

[defaults]
editor = cursor
ai = claude
```

### Copy Files to Worktrees

```bash
# 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

```bash
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`

## 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

```bash
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)
```