Skip to content
Skills Library
Programming · Tool integration

git-worktree-runner

/git-worktree-runner

Manages git worktrees using git-worktree-runner (gtr). Use when the user needs to create, list, remove, or navigate worktrees with `git gtr` commands, open editors or AI tools in worktrees, manage parallel development branches, or check out GitHub PRs (including from forks) into worktrees.

Repository
rulesync ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Manages git worktrees using git-worktree-runner (gtr). Use when the user needs to create, list, remove, or navigate worktrees with `git gtr` commands, open editors or AI tools in worktrees, manage parallel development branches, or check out GitHub PRs (including from forks) into worktrees.

Original author description

Manages git worktrees using git-worktree-runner (gtr). Use when the user needs to create, list, remove, or navigate worktrees with `git gtr` commands, open editors or AI tools in worktrees, manage parallel development branches, or check out GitHub PRs (including from forks) into worktrees.

How it works

  1. Quick Start
  2. Commands
  3. Configuration
  4. Example: Parallel AI Development
  5. Example: PR Review in Isolated Worktree
  6. Example: Hotfix While Working on Feature
  7. Example: Checkout a Fork PR into Worktree
Original SKILL.md headings · 215 lines, 738 words
SKILL.md preview
---
name: git-worktree-runner
description: >-
  Manages git worktrees using git-worktree-runner (gtr). Use when the user needs
  to create, list, remove, or navigate worktrees with `git gtr` commands, open
  editors or AI tools in worktrees, manage parallel development branches, or
  check out GitHub PRs (including from forks) into worktrees.
targets:
  - "*"
allowed-tools: "Bash(git-worktree-runner:*)"
---

# Git Worktree Runner (gtr)

git-worktree-runner (gtr) is a CLI tool that wraps `git worktree` with quality-of-life features for modern development workflows including editor and AI tool integration.

## Quick Start

```bash
# Create a new worktree
git gtr new feature-branch

# Create from a remote branch
git gtr new my-branch --from origin/feature-branch

# Open editor in the worktree
git gtr editor feature-branch

# Start AI tool (claude, codex, etc.) in the worktree
git gtr ai feature-branch

# Remove a worktree
git gtr rm feature-branch
```

## Commands

### Creating Worktrees

```bash
# Create a new worktree with a new branch
git gtr new feature-name

# Create from a specific ref (remote branch, tag, commit)
git gtr new my-branch --from origin/main
git gtr new hotfix --from v1.2.3

# Create and immediately open in editor
git gtr new feature -e

# Create and immediately start AI tool
git gtr new feature -a

# Create with both editor and AI tool
git gtr new feature -e -a
```

### Opening Editor / AI Tool

```bash
# Open the configured editor for a worktree
git gtr editor feature-branch

# Start configured AI tool in a worktree
git gtr ai feature-branch
```

### Running Commands

```bash
# Run an arbitrary command in a worktree
git gtr run feature-branch npm test
git gtr run feature-branch pnpm build
```

### Navigation

```bash
# Navigate to a worktree directory
cd "$(git gtr go feature-branch)"
```

### Listing and Managing

```bash
# List all worktrees
git gtr list

# Remove a worktree
git gtr rm feature-branch

# Rename a worktree
git gtr mv old-name new-name
```

## Configuration

```bash
# Set default editor (cursor, vscode, zed, etc.)
git gtr config set gtr.editor.default cursor

# Set default AI tool (claude, codex, opencode, aider, etc.)
git gtr config set gtr.ai.default claude

# Configure files to copy into new worktrees
git gtr config add gtr.copy.include "**/.env"
git gtr config add gtr.copy.include "**/.env.local"
git gtr config add gtr.copy.include "**/.env.example"

# View current configuration
git gtr config list
```

## Example: Parallel AI Development

```bash
# Create isolated worktrees for parallel AI agents
git gtr new feature-auth --from origin/main
git gtr new feature-api --from origin/main
git gtr new bugfix-login --from origin/main

# Start AI tools in each worktree
git gtr ai feature-auth
git gtr ai feature-api
git gtr ai bugfix-login

# Check status of all worktrees
git gtr list

# Clean up when done
git gtr rm feature-auth
git gtr rm feature-api
git gtr rm bugfix-login
```

## Example: PR Review in Isolated Worktree

```bash
# Create a worktree from PR branch
git gtr new review-pr-123 --from origin/pr-branch

# Open in editor to review
git gtr editor review-pr-123

# Run tests in isolation
git gtr run review-pr-123 pnpm test

# Clean up after review
git gtr rm review-pr-123
```

## Example: Hotfix While Working on Feature

```bash
# Current work is on feature-branch, need to do a hotfix
git gtr new hotfix-critical --from origin/main

# Open editor for the hotfix
git gtr new hotfix-critical -e

# After hotfix is done, remove the worktree
git gtr rm hotfix-critical
# Back to feature-branch work without context switching
```

## Example: Checkout a Fork PR into Worktree

For PRs from forked repositories, the branch is not on `origin`. Use GitHub's `refs/pull/<number>/head` ref to fetch it.

### Procedure

Given a PR number or URL:

1. **Get PR metadata**

   ```bash
   gh pr view <PR_NUMBER> --json headRefName,isCrossRepository
   ```

2. **Check for existing worktree** with the same branch name

   ```bash
   git worktree list
   ```

   If it exists, remove it first: `git gtr rm <branch>`

3. **Fetch the PR ref** into a local branch (use `--force` to handle diverged history from force-pushes)

   ```bash
   git fetch origin pull/<PR_NUMBER>/head:<BRANCH_NAME> --force
   ```

4. **Create the worktree** with `--track local` since it's a local-only branch

   ```bash
   git gtr new <BRANCH_NAME> --track local
   ```

5. **Verify**
   ```bash
   git gtr list
   ```

### Full example (PR #1223 from a fork)

```bash
gh pr view 1223 --json headRefName,isCrossRepository
git fetch origin pull/1223/head:fix/comprehensive-file-formats-docs --force
git gtr new fix/comprehensive-file-formats-docs --track local
git gtr list
```

### Shortening long branch names

```bash
git fetch origin pull/1223/head:pr-1223 --force
git gtr new pr-1223 --track local
```

### Common errors

- **"refusing to fetch into branch checked out at..."**: A worktree with that branch exists. `git gtr rm <branch>` first.
- **"non-fast-forward" rejected**: Local branch diverged. Add `--force` to the fetch.
- **Both errors**: Remove the worktree first, then fetch with `--force`.

Versions

The database has no other skills named git-worktree-runner.

Database snapshot: 13.11.2026 · package version 57712d950145 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100gtr
    This skill should be used when the user invokes /gtr:* commands to manage git worktrees using git-worktree-runner (gtr). Enables parallel branch development through worktree creation, editor/AI integration, and lifecycle management.
  • 100worktree
    Manages git worktrees with git-wt, including PR checkouts. Use when the user asks to create, switch, or delete a worktree, or check out a PR.
  • 100wt
    This skill should be used when the user asks about 'wt', 'worktree', 'worktrees', 'wt create', 'wt checkout', 'wt list', 'wt remove', 'wt pr', 'wt mr', or mentions managing git worktrees with wt. Also use when the user asks how wt works, how to use wt commands, or how to…
  • 100git-worktrees
    Git worktree management for parallel agent team development. Triggers: 'create worktree', 'worktree setup', or during /delegate dispatch. Do NOT use for branch creation without delegation context.
  • 100git-worktree
    Manage Git worktrees for isolated parallel development. Use when creating, switching, or cleaning up worktrees for parallel bead work.
  • 100git-wt
    Manages worktree lifecycle operations through git-wt without replacing an existing linked worktree. Use when creating, switching, listing, renaming, or deleting worktrees.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.