Git Worktree Runner

What it does

When your agent uses it

• The user needs to create
• Navigate worktrees with git gtr commands
• AI tools in worktrees
• Manage parallel development branches

Example prompts

• “Use the git-worktree-runner skill to manage git worktrees using git-worktree-runner (gtr). An agent skill from dyoshikawa/rulesync”
• “/git-worktree-runner”

Requirements

• Pre-approved tools (allowed-tools): Bash(git-worktree-runner:*)

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1Get PR metadata
2. 2Check for existing worktree with the same branch name
3. 3Fetch the PR ref into a local branch (use --force to handle diverged history from force-pushes)
4. 4Create the worktree with --track local since it's a local-only branch
5. 5Verify

What it can do on your machine

Read from SKILL.md and the folder at commit 85bcaf6. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Bash(git-worktree-runner:*)

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • git
  • gh

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use git and gh, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Git Worktree Runner loads about 1.3k tokens when it runs. Until then it costs about 78 tokens; SKILL.md has 198 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~78

When it runs · the whole SKILL.md, loaded when a task matches

~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:106

  git gtr config add gtr.copy.include "**/.env"

• NoteMentions a .env fileSKILL.md:107

  git gtr config add gtr.copy.include "**/.env.local"

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from dyoshikawa/rulesync at commit 85bcaf6, republished under its MIT licence (© dyoshikawa). 198 words, ~1,292 tokens.

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.

allowed-tools

Bash(git-worktree-runner:*)

targets

*

# 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

# 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

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

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

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

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

# List all worktrees
git gtr list

# Remove a worktree
git gtr rm feature-branch

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

# 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

# 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

# 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

# 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

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

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

© dyoshikawa, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .rulesync/skills/git-worktree-runner of dyoshikawa/rulesync.

Open the folder on GitHubat commit 85bcaf6