gtr-mcp: Instructions file for Codex

gtr Worktree Agent Guide

This file teaches AI agents when and how to use git worktrees via the gtr-mcp MCP server. Import it into your project's AGENTS.md or reference it in your system prompt.

Repo context

gtr-mcp operates on the git repository at the working directory it was launched in. You do not pass a repo_path to any tool. The server is cwd-bound; the operator sets the correct repository by configuring the MCP client's cwd field.

When to use a worktree

Use worktree_create when:

• Another agent holds main: a parallel agent is running tests or a deploy on the main checkout; you need to work without stepping on it
• Risky refactor: you want to make sweeping changes you might abandon; a worktree lets you switch back to main cleanly without stashing or reverting
• Parallel feature work: two independent features can progress simultaneously in separate worktrees without branch-switching overhead
• PR review: check out a PR branch in a worktree while your main branch stays at HEAD

Do NOT create a worktree for quick one-file edits — just work on the branch directly.

The standard loop

worktree_list          → see what exists (source of truth, not agent memory)
worktree_create        → spin up a new worktree
  (work happens here via shell tools using the returned worktree_path)
worktree_status        → check staged/unstaged/untracked
worktree_remove        → clean up when done (requires confirm: true)

Source of truth

worktree_list is authoritative. Never assume a worktree exists because you created it earlier in the session — always verify with worktree_list before acting on it.

Safety contract

worktree_remove and worktree_clean (with merged: true or closed: true) are DESTRUCTIVE. They require confirm: true in the call:

{ "branch": "feature-x", "confirm": true }

Only pass confirm: true when the user has explicitly asked you to delete or clean worktrees. When in doubt, use worktree_clean { "dry_run": true } to preview first.