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.
- Author
- dyoshikawa ↗
- Repository
- rulesync ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
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
- Quick Start
- Commands
- Configuration
- Example: Parallel AI Development
- Example: PR Review in Isolated Worktree
- Example: Hotfix While Working on Feature
- Example: Checkout a Fork PR into Worktree
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.