From 80f4f3ee93d83771229d1410eece6de7d330bdc7 Mon Sep 17 00:00:00 2001
From: Pedram Amini <pedram.amini@gmail.com>
Date: Sun, 14 Dec 2025 17:56:23 -0600
Subject: [PATCH] ## CHANGES
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added git worktree support for parallel Auto Run operations 🌳
- Enable background processing while continuing interactive work freely 🚀
- No more read-only mode when using worktree feature 🔓
- Visual git branch icon indicates active worktree operation 🌿
- Auto-create pull requests when batch processing completes ✨
- Worktree path computed from base directory plus branch name 📁
- Yellow border and input locks only without worktree enabled 🟡
- Continue editing main repo while Auto Run processes tasks 💪
- Improved documentation explaining worktree setup and benefits 📚
- Enhanced UI indicators for parallel operation status tracking 🎯
---
 CLAUDE.md                                      |  2 ++
 README.md                                      | 18 +++++++++++++-----
 .../components/AutoRunnerHelpModal.tsx         | 13 ++++++++++---
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 61148507..4958c1b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -223,6 +223,8 @@ window.maestro.autorun.readDocument(folderPath, filename);
 window.maestro.autorun.saveDocument(folderPath, filename, content);
 ```
 
+**Worktree Support:** Auto Run can operate in a git worktree, allowing users to continue interactive editing in the main repo while Auto Run processes tasks in the background. When `batchRunState.worktreeActive` is true, read-only mode is disabled and a git branch icon appears in the UI. See `useBatchProcessor.ts` for worktree setup logic.
+
 ## Code Conventions
 
 ### TypeScript
diff --git a/README.md b/README.md
index af6e0f73..e4f05d7b 100644
--- a/README.md
+++ b/README.md
@@ -398,14 +398,22 @@ Save your batch configurations for reuse:
 
 ### Git Worktree Support
 
-For parallel work without file conflicts:
+Git worktrees allow Auto Run to operate in an isolated directory while you continue working interactively in the main repository—no read-only restrictions, no waiting.
 
+**Setup:**
 1. Enable **Worktree** in the Batch Runner Modal
-2. Specify a worktree path and branch name
-3. Auto Run operates in the isolated worktree
-4. Optionally create a PR when the batch completes
+2. Select a **Worktree Directory** (base folder for all worktrees)
+3. Enter a **Branch Name** (becomes the worktree subdirectory)
+4. The computed path shows where the worktree will be created
+5. Optionally enable **Create PR on completion** to auto-open a pull request
 
-Without a worktree, Auto Run queues with other write operations to prevent conflicts.
+**Benefits:**
+- **Continue working** in the main repo while Auto Run processes tasks in the background
+- **No read-only mode** — the yellow border and input lock only appear when running without a worktree
+- **Visual indicator** — a git branch icon appears in the AUTO badge, right panel, and status pill when using a worktree
+- **Automatic PR creation** — when enabled, opens a PR from the worktree branch to your target branch
+
+**Without a worktree:** Auto Run queues with other write operations to prevent conflicts, and the editor enters read-only mode until completion.
 
 ### Progress Tracking
 
diff --git a/src/renderer/components/AutoRunnerHelpModal.tsx b/src/renderer/components/AutoRunnerHelpModal.tsx
index 675179c6..79b05a9b 100644
--- a/src/renderer/components/AutoRunnerHelpModal.tsx
+++ b/src/renderer/components/AutoRunnerHelpModal.tsx
@@ -440,13 +440,20 @@ export function AutoRunnerHelpModal({ theme, onClose }: AutoRunnerHelpModalProps
             >
               <p>
                 For Git repositories, enable <strong style={{ color: theme.colors.textMain }}>Git Worktree</strong> to
-                run Auto Run in an isolated working directory. This allows you to continue working
-                in the main project while Auto Run operates independently—no read-only restrictions.
+                run Auto Run in an isolated working directory. This allows you to{' '}
+                <strong style={{ color: theme.colors.textMain }}>continue making changes interactively</strong>{' '}
+                in the main repository while Auto Run processes tasks in the background—no read-only restrictions,
+                no yellow border, no waiting.
               </p>
               <p>
-                Specify a worktree path and branch name. Optionally enable <strong style={{ color: theme.colors.textMain }}>"Create PR on completion"</strong> to
+                Select a worktree directory and branch name. The worktree will be created as a subdirectory
+                using the branch name. Optionally enable <strong style={{ color: theme.colors.textMain }}>"Create PR on completion"</strong> to
                 automatically open a pull request when all tasks finish.
               </p>
+              <p>
+                When running in a worktree, a <GitBranch className="w-3 h-3 inline mx-1" style={{ color: theme.colors.accent }} />
+                icon appears in the AUTO badge, right panel, and status pill to indicate parallel operation.
+              </p>
             </div>
           </section>