# coderabbitai/git-worktree-runner architecture

> Architecture diagram of the GitHub repository coderabbitai/git-worktree-runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coderabbitai/git-worktree-runner
- Repository: https://github.com/coderabbitai/git-worktree-runner

## Overview

gtr is a Bash CLI that simplifies Git worktree creation and lifecycle management for parallel development, PR review, editors, and coding agents. A typical workflow invokes `git gtr new` to create a worktree, optionally copies files or runs setup hooks, then opens an editor or AI tool; users can later list, navigate to, and remove worktrees. The README supports these product relationships, but no source excerpts were provided, so internal call ownership and implementation details cannot be verified.

Main entry points: [`bin/git-gtr`](https://github.com/coderabbitai/git-worktree-runner/blob/main/bin/git-gtr) (CLI), [`lib/commands/create.sh`](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/create.sh) (Create worktree), [`lib/commands/clean.sh`](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/clean.sh) (Merged PR cleanup), [`lib/commands/pr.sh`](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/pr.sh) (PR worktrees)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["CLI"]
  node_shell["Shell helper"]
end

subgraph group_lifecycle["Worktree lifecycle"]
  node_worktree[("Git worktrees")]
  node_create["Create worktree<br/>[create.sh]"]
  node_pr["PR worktrees<br/>[pr.sh]"]
  node_list["List worktrees<br/>[list.sh]"]
  node_remove["Remove worktree<br/>[remove.sh]"]
  node_clean["Merged PR cleanup<br/>[clean.sh]"]
end

subgraph group_integrations["Developer integrations"]
  node_filecopy["Config file copy<br/>[copy.sh]"]
  node_hooks["Setup hooks<br/>[hooks.sh]"]
  node_editor["Editor launch<br/>[editor.sh]"]
  node_ai["AI launch<br/>[ai.sh]"]
  node_adapters["Tool adapters<br/>[adapters.sh]"]
end

subgraph group_settings["Configuration and UX"]
  node_config["Configuration<br/>[config.sh]"]
  node_completion["Shell completion"]
end

node_user(("Developer"))
node_prservice["PR CLI"]

node_user -->|"runs commands"| node_cli
node_cli -->|"handles &#96;new&#96;"| node_create
node_cli -->|"handles &#96;pr&#96;"| node_pr
node_cli -->|"handles &#96;list&#96;"| node_list
node_cli -->|"handles &#96;rm&#96;"| node_remove
node_cli -->|"handles &#96;clean&#96;"| node_clean
node_cli -->|"handles &#96;editor&#96;"| node_editor
node_cli -->|"handles &#96;ai&#96;"| node_ai
node_create -->|"creates"| node_worktree
node_pr -->|"creates"| node_worktree
node_list -->|"lists"| node_worktree
node_remove -->|"removes"| node_worktree
node_clean -->|"cleans"| node_worktree
node_create -->|"copies files"| node_filecopy
node_create -->|"runs hooks"| node_hooks
node_editor -.->|"uses adapters"| node_adapters
node_ai -->|"uses adapters"| node_adapters
node_clean -->|"checks PR status"| node_prservice
node_cli -->|"handles config"| node_config
node_user -->|"navigates worktrees"| node_shell
node_cli -->|"offers completions"| node_completion

click node_cli "https://github.com/coderabbitai/git-worktree-runner/blob/main/bin/git-gtr"
click node_shell "https://github.com/coderabbitai/git-worktree-runner/blob/main/bin/gtr"
click node_create "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/create.sh"
click node_pr "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/pr.sh"
click node_list "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/list.sh"
click node_remove "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/remove.sh"
click node_clean "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/clean.sh"
click node_filecopy "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/copy.sh"
click node_hooks "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/hooks.sh"
click node_editor "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/editor.sh"
click node_ai "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/ai.sh"
click node_adapters "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/adapters.sh"
click node_config "https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/config.sh"
click node_completion "https://github.com/coderabbitai/git-worktree-runner/blob/main/completions/_git-gtr"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shell toneBlue
class node_worktree,node_create,node_pr,node_list,node_remove,node_clean toneAmber
class node_filecopy,node_hooks,node_editor,node_ai,node_adapters toneMint
class node_config,node_completion toneRose
class node_user,node_prservice toneIndigo
```

## Components

### CLI entry

- [CLI](https://github.com/coderabbitai/git-worktree-runner/blob/main/bin/git-gtr): `bin/git-gtr`
- [Shell helper](https://github.com/coderabbitai/git-worktree-runner/blob/main/bin/gtr): `bin/gtr`

### Worktree lifecycle

- **Git worktrees**
- [Create worktree](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/create.sh): `lib/commands/create.sh`
- [PR worktrees](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/pr.sh): `lib/commands/pr.sh`
- [List worktrees](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/list.sh): `lib/commands/list.sh`
- [Remove worktree](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/remove.sh): `lib/commands/remove.sh`
- [Merged PR cleanup](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/clean.sh): `lib/commands/clean.sh`

### Developer integrations

- [Config file copy](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/copy.sh): `lib/copy.sh`
- [Setup hooks](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/hooks.sh): `lib/hooks.sh`
- [Editor launch](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/editor.sh): `lib/commands/editor.sh`
- [AI launch](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/ai.sh): `lib/commands/ai.sh`
- [Tool adapters](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/adapters.sh): `lib/adapters.sh`

### Configuration and UX

- [Configuration](https://github.com/coderabbitai/git-worktree-runner/blob/main/lib/commands/config.sh): `lib/commands/config.sh`
- [Shell completion](https://github.com/coderabbitai/git-worktree-runner/blob/main/completions/_git-gtr): `completions/_git-gtr`

### Other components

- **Developer**
- **PR CLI**

## Connections

- Developer → CLI: runs commands (evidence: `README.md`)
- CLI → Create worktree: handles `new` (evidence: `README.md`)
- CLI → PR worktrees: handles `pr` (evidence: `README.md`)
- CLI → List worktrees: handles `list` (evidence: `README.md`)
- CLI → Remove worktree: handles `rm` (evidence: `README.md`)
- CLI → Merged PR cleanup: handles `clean` (evidence: `README.md`)
- CLI → Editor launch: handles `editor` (evidence: `README.md`)
- CLI → AI launch: handles `ai` (evidence: `README.md`)
- Create worktree → Git worktrees: creates (evidence: `README.md`)
- PR worktrees → Git worktrees: creates (evidence: `README.md`)
- List worktrees → Git worktrees: lists (evidence: `README.md`)
- Remove worktree → Git worktrees: removes (evidence: `README.md`)
- Merged PR cleanup → Git worktrees: cleans (evidence: `README.md`)
- Create worktree → Config file copy: copies files (evidence: `README.md`)
- Create worktree → Setup hooks: runs hooks (evidence: `README.md`)
- Editor launch → Tool adapters: uses adapters
- AI launch → Tool adapters: uses adapters (evidence: `README.md`)
- Merged PR cleanup → PR CLI: checks PR status (evidence: `README.md`)
- CLI → Configuration: handles config (evidence: `README.md`)
- Developer → Shell helper: navigates worktrees (evidence: `README.md`)
- CLI → Shell completion: offers completions (evidence: `README.md`)