Refresh editor and AI adapter guidance (#193)

* Refresh editor and AI adapter guidance

* Address PR review: mark legacy adapter rows

Author: helizaga

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com), and this
 
 ## [Unreleased]
 
+### Added
+
+- Antigravity's terminal agent is available as the `antigravity` AI adapter, while other safe agent commands continue to work through the generic `PATH` fallback.
+
+### Changed
+
+- Antigravity editor launches now use the current `agy-ide` command, and the Cursor AI adapter prefers the current `agent` command while retaining legacy fallbacks.
+- Editor and AI documentation now uses current installation commands and labels retired or unmaintained integrations as legacy compatibility.
+- The README now leads with PR review and coding-agent workflows, surfaces agent automation earlier, and documents the complete configuration precedence.
+
 ## [2.10.0] - 2026-08-12
 
 ### Added

README.md

@@ -5,19 +5,19 @@
 [![Git](https://img.shields.io/badge/Git-2.17%2B-orange.svg)](https://git-scm.com/)
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#platform-support)
 
-> A portable, cross-platform CLI for managing git worktrees with ease
+> A portable Git worktree CLI for PR reviews, coding agents, and repeatable per-branch setup
 
 ![4 AI agents working in parallel across different worktrees](docs/assets/demo-parallel.png)
 
 ## Table of Contents
 
 - [What are git worktrees?](#what-are-git-worktrees)
 - [Quick Start](#quick-start)
+- [AI Agent Usage](#ai-agent-usage)
 - [Why gtr?](#why-gtr)
 - [Features](#features)
 - [Requirements](#requirements)
 - [Commands](#commands)
-- [AI Agent Usage](#ai-agent-usage)
 - [Configuration](#configuration)
 - [Shell Completions](#shell-completions-optional)
 - [Platform Support](#platform-support)
@@ -50,7 +50,7 @@ brew tap coderabbitai/tap
 brew install git-gtr
 ```
 
-**Script installer (macOS / Linux):**
+**Install from source (macOS / Linux):**
 
 ```bash
 git clone https://github.com/coderabbitai/git-worktree-runner.git
@@ -118,6 +118,17 @@ git gtr rm my-feature
 git gtr clean --merged --closed
 ```
 
+## AI Agent Usage
+
+Shell-capable coding agents can use `git gtr` directly; a separate MCP server is
+not required. Use `git gtr new <branch> --porcelain` to create a worktree and
+reliably capture its path, then run the agent inside that directory. Built-in
+adapters cover popular tools, while the safe `PATH` fallback works with other
+agent CLIs without requiring a dedicated adapter.
+
+See [docs/agent-usage.md](docs/agent-usage.md) for a copy-paste `AGENTS.md`
+policy, output contract, and safe lifecycle examples.
+
 ## Why gtr?
 
 While `git worktree` is powerful, it's verbose and manual. `git gtr` adds quality-of-life features for modern development:
@@ -142,7 +153,7 @@ While `git worktree` is powerful, it's verbose and manual. `git gtr` adds qualit
 - **Repository-scoped** - Each repo has independent worktrees
 - **Configuration over flags** - Set defaults once, use simple commands
 - **Editor integration** - Open worktrees in Antigravity, Cursor, VS Code, Zed, and more
-- **AI tool support** - Launch Aider, Claude Code, or other AI coding tools
+- **AI tool support** - Launch Claude Code, Codex, Gemini CLI, or any safe command in `PATH`
 - **Smart file copying** - Selectively copy configs/env files to new worktrees
 - **Hooks system** - Run custom commands after create/remove
 - **Cross-platform** - Works on macOS, Linux, and Windows (Git Bash)
@@ -240,7 +251,7 @@ Start AI coding tool (uses `gtr.ai.default` or `--ai` flag).
 ```bash
 git gtr ai my-feature                      # Uses configured AI tool
 git gtr ai my-feature --ai codex          # Override with different tool
-git gtr ai my-feature -- --model gpt-4    # Pass arguments to tool
+git gtr ai my-feature -- --verbose        # Pass arguments to tool
 git gtr ai 1                              # Use AI in main repo
 ```
 
@@ -414,16 +425,16 @@ All configuration is stored via `git config`. For team settings, create a `.gtrc
 # Set your editor (antigravity, cursor, vscode, zed)
 git gtr config set gtr.editor.default cursor
 
-# Set your AI tool (aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode)
+# Set your AI tool (antigravity, aider, auggie, claude, codex, copilot, cursor, gemini, opencode)
 git gtr config set gtr.ai.default claude
 
 # Override-backed adapters may include flags
 git gtr config set gtr.editor.default "nano -w"
 git gtr config set gtr.ai.default "claude --continue"
 
-# Generic fallbacks may use other safe PATH commands
+# Generic fallbacks support other safe PATH commands without dedicated adapters
 git gtr config set gtr.editor.default "code --wait"
-git gtr config set gtr.ai.default "bunx @github/copilot@latest"
+git gtr config set gtr.ai.default goose
 
 # Copy env files to new worktrees
 git gtr config add gtr.copy.include "**/.env.example"
@@ -470,6 +481,9 @@ git gtr config set gtr.ui.color never
 1. `git config --local` (`.git/config`) - personal overrides
 2. `.gtrconfig` (repo root) - team defaults (hooks and editor/AI defaults require `git gtr trust`)
 3. `git config --global` (`~/.gitconfig`) - user defaults
+4. `git config --system` (`/etc/gitconfig`) - system defaults
+5. Environment variables
+6. Built-in defaults
 
 > For complete configuration reference including all settings, hooks, file copying patterns, and environment variables, see [docs/configuration.md](docs/configuration.md)
 
@@ -505,15 +519,6 @@ Requires Git 2.17+ and Bash 3.2+.
 
 > For troubleshooting, platform-specific notes, and architecture details, see [docs/troubleshooting.md](docs/troubleshooting.md)
 
-## AI Agent Usage
-
-Shell-capable coding agents can use `git gtr` directly; a separate MCP server is
-not required. Use `git gtr new <branch> --porcelain` to create a worktree and
-reliably capture its path, then run the agent inside that directory.
-
-See [docs/agent-usage.md](docs/agent-usage.md) for a copy-paste `AGENTS.md`
-policy, output contract, and safe lifecycle examples.
-
 ## Advanced Usage
 
 For advanced workflows including:
@@ -530,8 +535,8 @@ See [docs/advanced-usage.md](docs/advanced-usage.md)
 
 Contributions welcome! Areas where help is appreciated:
 
-- **New editor adapters** - JetBrains IDEs, Neovim, etc.
-- **New AI tool adapters** - Codeium, etc.
+- **New editor adapters** - Editors that need behavior beyond the safe `PATH` fallback
+- **New AI tool adapters** - Agent CLIs that need custom launch or discovery logic
 - **Bug reports** - Platform-specific issues
 - **Documentation** - Tutorials, examples, use cases
 

adapters/ai/cursor.sh

@@ -3,7 +3,9 @@
 
 # Check if Cursor agent/CLI is available
 ai_can_start() {
-  command -v cursor-agent >/dev/null 2>&1 || command -v cursor >/dev/null 2>&1
+  command -v agent >/dev/null 2>&1 \
+    || command -v cursor-agent >/dev/null 2>&1 \
+    || command -v cursor >/dev/null 2>&1
 }
 
 # Start Cursor agent in a directory
@@ -14,8 +16,8 @@ ai_start() {
   local configured_args=("${GTR_AI_CMD_ARGS[@]}")
 
   if ! ai_can_start; then
-    log_error "Cursor not found. Install from https://cursor.com"
-    log_info "Make sure to enable the Cursor CLI/agent from the app"
+    log_error "Cursor agent not found. Install from https://cursor.com/docs/cli/installation"
+    log_info "Current releases use 'agent'; legacy 'cursor-agent' and 'cursor' commands are also supported"
     return 1
   fi
 
@@ -24,8 +26,10 @@ ai_start() {
     return 1
   fi
 
-  # Try cursor-agent first, then fallback to cursor CLI commands
-  if command -v cursor-agent >/dev/null 2>&1; then
+  # Prefer the current standalone CLI, then fall back to legacy commands.
+  if command -v agent >/dev/null 2>&1; then
+    (cd "$path" && agent "${configured_args[@]}" "$@")
+  elif command -v cursor-agent >/dev/null 2>&1; then
     (cd "$path" && cursor-agent "${configured_args[@]}" "$@")
   elif command -v cursor >/dev/null 2>&1; then
     # Try various Cursor CLI patterns (implementation varies by version)

completions/_git-gtr

@@ -160,7 +160,7 @@ _git-gtr() {
         _arguments '--editor[Editor to use]:editor:(antigravity atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed)'
         ;;
       ai)
-        _arguments '--ai[AI tool to use]:tool:(aider auggie claude codex continue copilot cursor gemini none opencode)'
+        _arguments '--ai[AI tool to use]:tool:(aider antigravity auggie claude codex continue copilot cursor gemini none opencode)'
         ;;
       rm)
         _arguments \

completions/git-gtr.fish

@@ -114,7 +114,7 @@ complete -c git -n '__fish_git_gtr_using_command ls' -l porcelain -d 'Machine-re
 complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a 'antigravity atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed'
 
 # AI command options
-complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider auggie claude codex continue copilot cursor gemini none opencode'
+complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider antigravity auggie claude codex continue copilot cursor gemini none opencode'
 
 # Clean command options
 complete -c git -n '__fish_git_gtr_using_command clean' -l merged -d 'Remove worktrees with merged PRs/MRs'

completions/gtr.bash

@@ -67,7 +67,7 @@ _git_gtr() {
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--ai" -- "$cur"))
       elif [ "$prev" = "--ai" ]; then
-        COMPREPLY=($(compgen -W "aider auggie claude codex continue copilot cursor gemini none opencode" -- "$cur"))
+        COMPREPLY=($(compgen -W "aider antigravity auggie claude codex continue copilot cursor gemini none opencode" -- "$cur"))
       else
         local branches all_options
         branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)

docs/configuration.md

@@ -179,7 +179,7 @@ gtr.editor.workspace = project.code-workspace
 
 **Setup editors:**
 
-- **Antigravity**: Install from [antigravity.google](https://antigravity.google), `agy` command available after installation
+- **Antigravity**: Install from [antigravity.google](https://antigravity.google), with the `agy-ide` command available
 - **Cursor**: Install from [cursor.com](https://cursor.com), enable shell command
 - **VS Code**: Install from [code.visualstudio.com](https://code.visualstudio.com), enable `code` command
 - **Zed**: Install from [zed.dev](https://zed.dev), `zed` command available automatically
@@ -198,23 +198,33 @@ VS Code, Cursor, and Antigravity support `.code-workspace` files for multi-root
 ## AI Tool Settings
 
 ```bash
-# Default AI tool: none (or aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode)
+# Default AI tool: none (or antigravity, aider, auggie, claude, codex, copilot, cursor, gemini, opencode)
 gtr.ai.default = none
 ```
 
-**Supported AI Tools:**
-
-| Tool                                                                  | Install                                           | Use Case                                                 | Set as Default                               |
-| --------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------- |
-| **[Aider](https://aider.chat)**                                       | `pip install aider-chat`                          | Pair programming, edit files with AI                     | `git gtr config set gtr.ai.default aider`    |
-| **[Auggie CLI](https://www.augmentcode.com/product/CLI)**             | `npm install -g @augmentcode/auggie`              | Context-aware agentic CLI for automation and development | `git gtr config set gtr.ai.default auggie`   |
-| **[Claude Code](https://claude.com/claude-code)**                     | Install from claude.com                           | Terminal-native coding agent                             | `git gtr config set gtr.ai.default claude`   |
-| **[Codex CLI](https://github.com/openai/codex)**                      | `npm install -g @openai/codex`                    | OpenAI coding assistant                                  | `git gtr config set gtr.ai.default codex`    |
-| **[Continue](https://continue.dev)**                                  | See [docs](https://docs.continue.dev/cli/install) | Open-source coding agent                                 | `git gtr config set gtr.ai.default continue` |
-| **[GitHub Copilot CLI](https://githubnext.com/projects/copilot-cli)** | `npm install -g @githubnext/copilot-cli`          | AI-powered CLI assistant by GitHub                       | `git gtr config set gtr.ai.default copilot`  |
-| **[Cursor](https://cursor.com)**                                      | Install from cursor.com                           | AI-powered editor with CLI agent                         | `git gtr config set gtr.ai.default cursor`   |
-| **[Gemini](https://github.com/google-gemini/gemini-cli)**             | `npm install -g @google/gemini-cli`               | Open-source AI coding assistant powered by Google Gemini | `git gtr config set gtr.ai.default gemini`   |
-| **[OpenCode](https://opencode.ai)**                                   | Install from opencode.ai                          | AI coding assistant                                      | `git gtr config set gtr.ai.default opencode` |
+**Built-in AI Tool Adapters:**
+
+| Tool                                                                                                                        | Install                                                        | Use Case                                                 | Set as Default                                  |
+| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
+| **[Antigravity CLI](https://antigravity.google/docs/cli/getting-started)**                                                   | Install from antigravity.google                                | Terminal agent paired with the Antigravity IDE           | `git gtr config set gtr.ai.default antigravity` |
+| **[Aider](https://aider.chat/docs/install.html)**                                                                            | `python -m pip install aider-install && aider-install`          | Pair programming and file editing                        | `git gtr config set gtr.ai.default aider`       |
+| **[Auggie CLI](https://docs.augmentcode.com/cli/overview)**                                                                  | `npm install -g @augmentcode/auggie`                            | Context-aware agentic CLI for automation and development | `git gtr config set gtr.ai.default auggie`      |
+| **[Claude Code](https://claude.com/claude-code)**                                                                            | Install from claude.com                                        | Terminal-native coding agent                             | `git gtr config set gtr.ai.default claude`      |
+| **[Codex CLI](https://developers.openai.com/codex/cli/reference/)**                                                          | `npm install -g @openai/codex`                                 | OpenAI coding agent                                      | `git gtr config set gtr.ai.default codex`       |
+| **[GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)**       | `npm install -g @github/copilot` or `brew install copilot-cli` | GitHub's terminal coding agent                           | `git gtr config set gtr.ai.default copilot`     |
+| **[Cursor Agent](https://cursor.com/docs/cli/installation)**                                                                 | Install the `agent` CLI from cursor.com                         | Cursor's standalone terminal agent                       | `git gtr config set gtr.ai.default cursor`      |
+| **[Gemini CLI](https://github.com/google-gemini/gemini-cli)**                                                                | `npm install -g @google/gemini-cli`                             | Open-source coding agent powered by Gemini               | `git gtr config set gtr.ai.default gemini`      |
+| **[OpenCode](https://opencode.ai)**                                                                                          | Install from opencode.ai                                       | Open-source terminal coding agent                        | `git gtr config set gtr.ai.default opencode`    |
+| **[Continue (legacy)](https://github.com/continuedev/continue)**                                                              | Existing `cn` installations only                               | Compatibility; the project is no longer maintained      | `git gtr config set gtr.ai.default continue`    |
+
+Any safe executable command in `PATH` also works without a built-in adapter. For
+example, after installing [Goose](https://github.com/aaif-goose/goose) or
+[Qwen Code](https://github.com/QwenLM/qwen-code):
+
+```bash
+git gtr config set gtr.ai.default goose
+git gtr config set gtr.ai.default qwen
+```
 
 **Examples:**
 

docs/troubleshooting.md

@@ -207,14 +207,14 @@ git-worktree-runner/
 
 - Shell completions require bash-completion v2+ for Bash
 - Some AI adapters require recent tool versions (see adapter docs)
-- Windows native (non-WSL) support is experimental
+- Native PowerShell is not supported; use Git Bash or WSL2
 
 ### Testing Approach
 
 - **Automated tests**: BATS test suite (`tests/`) covers core functions
 - **CI**: ShellCheck linting + BATS tests run on all PRs
 - **Manual testing**: End-to-end workflows tested across macOS, Linux, WSL2
-- **Production use**: Battle-tested with Cursor, VS Code, Aider, Claude Code
+- **Adapter coverage**: Built-in and generic `PATH` launch behavior is covered by BATS; product-specific behavior depends on installed tool versions
 - Community testing appreciated - please report issues!
 
 ### Experimental Features