Best way to get Claude Code to use `gtr` when creating worktrees?

[echarrod]

Recently it seems Claude Code is creating worktrees a lot more, particularly when dispatching work to sub-agents.

These are created at .claude/worktrees in the repo which:

• (presumably) only observe .worktreeinclude, and not .gtrconfig
• Aren't gitignored by default

Looking for thoughts on the best way we can get Claude Code to use gtr for these, so e.g. we can have postCreate / postCd commands run, and have everything in .gtrconfig

This could be with:

• Adding a line to AGENTS.md
• A hook?
• A skill?

[traycerai]

Plan

Observations

The gtr project already has a rich hooks system (postCreate, postCd, preRemove, postRemove) and a .gtrconfig team-config file. Claude Code creates worktrees at .claude/worktrees via raw git worktree add, bypassing gtr entirely — so hooks never fire, .gtrconfig is ignored, and the directory isn't gitignored. The existing CLAUDE.md guides Claude Code on how to work with the gtr codebase but says nothing about using gtr for worktree creation.

Approach

A two-layer strategy: (1) instruct AI agents directly via CLAUDE.md/AGENTS.md so they call git gtr new instead of git worktree add, and (2) add a post-checkout git hook that git gtr init can install as a safety net — so even if an agent bypasses gtr, the post-create hooks still fire. This covers both the "happy path" (agent follows instructions) and the "escape hatch" (agent doesn't).

sequenceDiagram
    participant CC as Claude Code / Sub-agent
    participant AGENTS as AGENTS.md / CLAUDE.md
    participant GTR as git gtr new
    participant Hook as post-checkout hook
    participant Hooks as gtr hooks (postCreate)

    CC->>AGENTS: reads instructions on startup
    AGENTS-->>CC: "use git gtr new, not git worktree add"
    CC->>GTR: git gtr new <branch>
    GTR->>Hooks: run_hooks_in postCreate
    Note over Hook: Safety net if agent ignores instructions
    CC-->>Hook: git worktree add (bypasses gtr)
    Hook->>Hooks: run_hooks_in postCreate

Loading

---

Implementation Steps

1. Update CLAUDE.md with worktree creation instructions

In file:CLAUDE.md, add a dedicated "Worktree Creation" section (place it near the top, after "Invocation"). It should state:

• Always use git gtr new <branch> to create worktrees — never raw git worktree add
• Use git gtr rm <branch> for removal, not git worktree remove
• When dispatching sub-agents, pass the worktree path obtained from git gtr new (or git gtr go <branch>)
• The reason: gtr runs postCreate hooks, copies config files, and respects .gtrconfig

2. Create AGENTS.md at the repo root

Create a new AGENTS.md file (the generic AI-agent instruction file, analogous to CLAUDE.md but read by a broader set of agents). It should contain:

• The same worktree creation rule: use git gtr new / git gtr rm
• A brief explanation of what gtr does (hooks, file copying, .gtrconfig)
• The gtr.worktrees.dir config key so agents know where worktrees land
• A note to add .claude/worktrees (and any other agent-specific worktree dirs) to .gitignore

3. Add a post-checkout hook installer to git gtr init

This is the safety-net layer. Extend lib/commands/init.sh (the cmd_init function) with a new sub-command or flag, e.g. git gtr init hooks, that installs a post-checkout hook into .git/hooks/post-checkout.

The installed hook script should:

• Check $3 (the branch-flag argument) — exit early if it's 0 (file checkout, not branch switch)
• Detect whether the current working directory is a worktree and not the main repo (compare git rev-parse --git-dir against git rev-parse --git-common-dir)
• If it's a newly-created worktree, call git gtr run-hooks postCreate (see step 4) from the worktree directory
• Set the same env vars that run_hooks_in sets: REPO_ROOT, WORKTREE_PATH, BRANCH

Update lib/commands/help.sh and all three completion files (completions/gtr.bash, completions/_git-gtr, completions/git-gtr.fish) to document the new init hooks sub-command.

4. Add an internal run-hooks sub-command

Add lib/commands/run_hooks.sh with a cmd_run_hooks function that accepts a hook name (postCreate, preRemove, etc.) and runs it via the existing run_hooks_in function from lib/hooks.sh. This gives the post-checkout hook script a stable, public-ish entry point without exposing internal library functions.

Register it in the main() dispatcher in bin/git-gtr under a case like run-hooks|run_hooks.

5. Document .gitignore guidance

In docs/advanced-usage.md, add a section "AI Agent Worktree Integration" covering:

• Add agent-specific worktree directories to .gitignore (e.g. .claude/worktrees/, .github/worktrees/)
• Configure gtr.worktrees.dir to point to the same location Claude Code uses (.claude/worktrees) so git gtr list shows those worktrees and git gtr rm can clean them up
• Example .gtrconfig snippet with worktrees.dir = .claude/worktrees
• The git gtr init hooks command to install the safety-net hook

6. Update README.md

Add a brief "AI Agent Integration" subsection under the existing "Advanced Usage" section pointing to docs/advanced-usage.md for the Claude Code / sub-agent workflow.

---

Summary of files to change

File	Change
file:CLAUDE.md	Add "Worktree Creation" section instructing use of git gtr new
AGENTS.md (new)	Generic AI-agent instructions mirroring the above
file:lib/commands/init.sh	Add hooks sub-command to install post-checkout hook
lib/commands/run_hooks.sh (new)	cmd_run_hooks — internal entry point for hook execution
file:bin/git-gtr	Register run-hooks in main() dispatcher
file:lib/commands/help.sh	Document init hooks
file:completions/gtr.bash	Add init hooks completion
file:completions/_git-gtr	Add init hooks completion
file:completions/git-gtr.fish	Add init hooks completion
file:docs/advanced-usage.md	Add "AI Agent Worktree Integration" section
file:README.md	Add pointer to AI agent integration docs

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `gtr` project already has a rich hooks system (`postCreate`, `postCd`, `preRemove`, `postRemove`) and a `.gtrconfig` team-config file. Claude Code creates worktrees at `.claude/worktrees` via raw `git worktree add`, bypassing `gtr` entirely — so hooks never fire, `.gtrconfig` is ignored, and the directory isn't gitignored. The existing `CLAUDE.md` guides Claude Code on how to work _with_ the `gtr` codebase but says nothing about _using_ `gtr` for worktree creation.

## Approach

A two-layer strategy: (1) instruct AI agents directly via `CLAUDE.md`/`AGENTS.md` so they call `git gtr new` instead of `git worktree add`, and (2) add a `post-checkout` git hook that `git gtr init` can install as a safety net — so even if an agent bypasses `gtr`, the post-create hooks still fire. This covers both the "happy path" (agent follows instructions) and the "escape hatch" (agent doesn't).

```mermaid
sequenceDiagram
    participant CC as Claude Code / Sub-agent
    participant AGENTS as AGENTS.md / CLAUDE.md
    participant GTR as git gtr new
    participant Hook as post-checkout hook
    participant Hooks as gtr hooks (postCreate)

    CC->>AGENTS: reads instructions on startup
    AGENTS-->>CC: "use git gtr new, not git worktree add"
    CC->>GTR: git gtr new <branch>
    GTR->>Hooks: run_hooks_in postCreate
    Note over Hook: Safety net if agent ignores instructions
    CC-->>Hook: git worktree add (bypasses gtr)
    Hook->>Hooks: run_hooks_in postCreate
```

---

## Implementation Steps

### 1. Update `CLAUDE.md` with worktree creation instructions

In `file:CLAUDE.md`, add a dedicated **"Worktree Creation"** section (place it near the top, after "Invocation"). It should state:

- Always use `git gtr new <branch>` to create worktrees — never raw `git worktree add`
- Use `git gtr rm <branch>` for removal, not `git worktree remove`
- When dispatching sub-agents, pass the worktree path obtained from `git gtr new` (or `git gtr go <branch>`)
- The reason: `gtr` runs `postCreate` hooks, copies config files, and respects `.gtrconfig`

### 2. Create `AGENTS.md` at the repo root

Create a new `AGENTS.md` file (the generic AI-agent instruction file, analogous to `CLAUDE.md` but read by a broader set of agents). It should contain:

- The same worktree creation rule: use `git gtr new` / `git gtr rm`
- A brief explanation of what `gtr` does (hooks, file copying, `.gtrconfig`)
- The `gtr.worktrees.dir` config key so agents know where worktrees land
- A note to add `.claude/worktrees` (and any other agent-specific worktree dirs) to `.gitignore`

### 3. Add a `post-checkout` hook installer to `git gtr init`

This is the safety-net layer. Extend `lib/commands/init.sh` (the `cmd_init` function) with a new sub-command or flag, e.g. `git gtr init hooks`, that installs a `post-checkout` hook into `.git/hooks/post-checkout`.

The installed hook script should:
- Check `$3` (the branch-flag argument) — exit early if it's `0` (file checkout, not branch switch)
- Detect whether the current working directory is a worktree and not the main repo (compare `git rev-parse --git-dir` against `git rev-parse --git-common-dir`)
- If it's a newly-created worktree, call `git gtr run-hooks postCreate` (see step 4) from the worktree directory
- Set the same env vars that `run_hooks_in` sets: `REPO_ROOT`, `WORKTREE_PATH`, `BRANCH`

Update `lib/commands/help.sh` and all three completion files (`completions/gtr.bash`, `completions/_git-gtr`, `completions/git-gtr.fish`) to document the new `init hooks` sub-command.

### 4. Add an internal `run-hooks` sub-command

Add `lib/commands/run_hooks.sh` with a `cmd_run_hooks` function that accepts a hook name (`postCreate`, `preRemove`, etc.) and runs it via the existing `run_hooks_in` function from `lib/hooks.sh`. This gives the `post-checkout` hook script a stable, public-ish entry point without exposing internal library functions.

Register it in the `main()` dispatcher in `bin/git-gtr` under a case like `run-hooks|run_hooks`.

### 5. Document `.gitignore` guidance

In `docs/advanced-usage.md`, add a section **"AI Agent Worktree Integration"** covering:

- Add agent-specific worktree directories to `.gitignore` (e.g. `.claude/worktrees/`, `.github/worktrees/`)
- Configure `gtr.worktrees.dir` to point to the same location Claude Code uses (`.claude/worktrees`) so `git gtr list` shows those worktrees and `git gtr rm` can clean them up
- Example `.gtrconfig` snippet with `worktrees.dir = .claude/worktrees`
- The `git gtr init hooks` command to install the safety-net hook

### 6. Update `README.md`

Add a brief **"AI Agent Integration"** subsection under the existing "Advanced Usage" section pointing to `docs/advanced-usage.md` for the Claude Code / sub-agent workflow.

---

### Summary of files to change

| File | Change |
|---|---|
| `file:CLAUDE.md` | Add "Worktree Creation" section instructing use of `git gtr new` |
| `AGENTS.md` _(new)_ | Generic AI-agent instructions mirroring the above |
| `file:lib/commands/init.sh` | Add `hooks` sub-command to install `post-checkout` hook |
| `lib/commands/run_hooks.sh` _(new)_ | `cmd_run_hooks` — internal entry point for hook execution |
| `file:bin/git-gtr` | Register `run-hooks` in `main()` dispatcher |
| `file:lib/commands/help.sh` | Document `init hooks` |
| `file:completions/gtr.bash` | Add `init hooks` completion |
| `file:completions/_git-gtr` | Add `init hooks` completion |
| `file:completions/git-gtr.fish` | Add `init hooks` completion |
| `file:docs/advanced-usage.md` | Add "AI Agent Worktree Integration" section |
| `file:README.md` | Add pointer to AI agent integration docs |

---

Execution Information

Branch: main
Commit: c74f843

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[helizaga]

try adding this to claude.md:

When creating worktrees, always use `git gtr new <branch>` instead of `git worktree add`. Use `git gtr rm <branch>` to remove them.