[chmouel]

Three changes to how lazyworktree works with Herdr workspaces.

Grouped workspaces

• Worktree workspaces open through herdr worktree open, the same path Herdr's own picker uses, so each one appears nested under its repository in the sidebar.
• Lazyworktree recognises a workspace by its checkout path as well as by its tag. A workspace opened from Herdr's picker is reused, listed in the palette and handled by on_exists: kill, and workspaces are still found after a Herdr restart drops the tags.
• Bare repositories and Herdr refusals fall back to a plain workspace. worktree_group: false on the herdr block turns grouping off.

Closing workspaces on delete

• Deleting a worktree (TUI, merged prune, lazyworktree delete, lazyworktree cleanup) closes its Herdr workspaces in every running Herdr session.
• The workspace hosting lazyworktree stays open, and a failed git worktree remove keeps its workspaces.

Herdr creates the worktree (opt-in)

use_herdr_for_workspace_create: true
herdr_workspace_create_layout: H # optional custom command key

flowchart TD
    A[New worktree requested] --> B{use_herdr_for_workspace_create}
    B -- off --> G[git worktree add]
    B -- on --> C[lazyworktree prepares the branch]
    C --> D[herdr worktree create]
    D -- fails --> G
    D -- ok --> E[Run .wt init commands]
    G --> E
    E -- succeed --> F[Apply layout from herdr_workspace_create_layout]
    E -- fail, worktree removed --> X[Close the new workspace]

Loading

• Applies to the CLI, the TUI and the shell helpers.
• Branch tracking and PR upstreams stay with lazyworktree. Detached commits and tags are checked out with git, then opened in Herdr.
• If Herdr fails, git creates the worktree, and a branch Herdr left behind is deleted only when lazyworktree created it.
• The trust prompt for any new worktree now offers Cancel Setup, which keeps the worktree and skips its commands and layout.
• A TUI started by the shell helpers or with --output-selection never focuses new workspaces, so the helper can still cd once you leave.

Docs, the man page, the help screen and the generated config reference cover the new options.

[qodo-free-for-open-source-projects]

Qodo is busy working

Check back in a few minutes. Qodo's code review agents are on it.

[qodo-code-review]

PR Summary by Qodo

Group Herdr workspaces and optionally create worktrees through Herdr

✨ Enhancement 🐞 Bug fix ⚙️ Configuration changes 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Group Herdr workspaces by repository and reuse them by checkout path, even after tags disappear.
• Close workspaces after successful worktree deletion, while preserving the workspace hosting
 LazyWorktree.
• Optionally create worktrees through Herdr, with Git fallback and layouts applied after
 initialization.

Diagram

graph TD
  C["Creation config"] --> S["Git worktree service"] --> D{"Use Herdr"} -->|enabled| H["Herdr workspace"] --> I["Init and trust"] --> L["Workspace layout"]
  D -->|disabled or failure| G["Git fallback"] --> I
  S -->|successful removal| X["Close Herdr workspaces"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Integrate Herdr separately at each creation call site

• ➕ Avoids interpreting Git argument lists in the service.
• ➖ Duplicates fallback and setup logic across CLI and TUI paths.
• ➖ Makes it easier for a creation path to miss the integration.

Recommendation: Keep the centralized worktree hook: it covers existing creation paths while retaining the original Git command as a fallback. Review the recognized command forms and rollback behavior closely, since both determine whether a workspace is finalized or safely left open.

Files changed (33) +2387 / -313

Enhancement (13) +1017 / -97

app.goInstall the TUI creator hook and route creation setup +10/-2

Install the TUI creator hook and route creation setup

• Attaches the Herdr creator when enabled and sends new-worktree initialization through the setup flow.

internal/app/app.go

app_git.goFinalize TUI workspaces after trusted initialization +131/-38

Finalize TUI workspaces after trusted initialization

• Separates trust decisions from creation setup, then finalizes or forgets the worktree hook before refreshing. The creation trust prompt gains a Cancel Setup path that keeps the worktree without further setup.

internal/app/app_git.go

app_helpers.goAllow helper-launched workspaces to stay in background +10/-0

Allow helper-launched workspaces to stay in background

• Exposes a model method that disables focusing newly created Herdr workspaces while a shell helper awaits TUI exit.

internal/app/app_helpers.go

herdr.goGroup TUI workspaces and list checkout-matched entries +26/-2

Group TUI workspaces and list checkout-matched entries

• Opens eligible workspaces through Herdr's worktree command, includes this repository's untagged grouped workspaces in the palette, and adds a deletion cleanup helper.

internal/app/herdr.go

trust.goMake the trust prompt's cancel label configurable +12/-1

Make the trust prompt's cancel label configurable

• Allows creation flows to display Cancel Setup while preserving Cancel Operation elsewhere.

internal/app/screen/trust.go

worktree_operations.goComplete TUI creation setup and clean up deletions +11/-4

Complete TUI creation setup and clean up deletions

• Routes additional creation paths through the new initialization flow and closes Herdr workspaces only after successful worktree removal.

internal/app/worktree_operations.go

commands.goEnable Herdr creation and grouping in CLI actions +10/-1

Enable Herdr creation and grouping in CLI actions

• Installs the creator hook for CLI creation and opens eligible custom-command workspaces through Herdr's grouped worktree path.

internal/bootstrap/commands.go

operations.goFinalize CLI creation and clean up deleted workspaces +45/-1

Finalize CLI creation and clean up deleted workspaces

• Finalizes the creation hook after successful initialization, forgets setup for a worktree kept after failure, and closes matching Herdr workspaces after deletion.

internal/cli/operations.go

service.goRoute supported worktree commands through a hook +43/-18

Route supported worktree commands through a hook

• Intercepts recognized worktree additions and reports removal outcomes while retaining checked-command error reporting.

internal/git/service.go

worktree_hook.goDefine the worktree lifecycle hook +88/-0

Define the worktree lifecycle hook

• Adds the add, removal, finalization, and forget contract, plus parsers for the worktree command forms issued by LazyWorktree.

internal/git/worktree_hook.go

models.goRepresent intercepted worktree additions +11/-0

Represent intercepted worktree additions

• Adds a worktree-add request carrying path, ref, new branch, tracking choice, and original command directory.

internal/models/models.go

herdr.goSupport grouped workspaces and cross-session cleanup +225/-30

Support grouped workspaces and cross-session cleanup

• Matches Herdr workspaces by persistent checkout path when tags are absent, opens grouped workspaces with plain-workspace fallback, and closes deleted worktree workspaces across running sessions while sparing the caller's workspace.

internal/multiplexer/herdr.go

herdr_create.goCreate and finalize worktrees through Herdr +395/-0

Create and finalize worktrees through Herdr

• Prepares branches with Git, delegates eligible checkout creation to Herdr, and falls back safely when it fails. Tracks fresh workspaces for post-init layout, conditional focus, abandonment, or rollback cleanup.

internal/multiplexer/herdr_create.go

Bug fix (2) +6 / -0

bootstrap.goSuppress workspace focus for selection-output TUIs +3/-0

Suppress workspace focus for selection-output TUIs

• Keeps newly created Herdr workspaces in the background when the TUI must return a path to a shell helper.

internal/bootstrap/bootstrap.go

cleanup.goClose Herdr workspaces after cleanup removal +3/-0

Close Herdr workspaces after cleanup removal

• Closes matching workspaces when cleanup successfully removes a worktree.

internal/cli/cleanup.go

Refactor (1) +2 / -11

base_selection.goMove branch-selection initialization into the update loop +2/-11

Move branch-selection initialization into the update loop

• Returns creation-initialization messages instead of running trust handling inside asynchronous creation commands.

internal/app/base_selection.go

Tests (8) +1051 / -1

app_git_test.goTest TUI initialization and trust outcomes +113/-0

Test TUI initialization and trust outcomes

• Checks finalization ordering, failed and skipped initialization, and all three creation trust choices.

internal/app/app_git_test.go

base_selection_test.goAdapt branch-selection tests to deferred setup +10/-0

Adapt branch-selection tests to deferred setup

• Processes the new initialization message before asserting the resulting worktree refresh.

internal/app/base_selection_test.go

herdr_test.goTest grouped TUI opening and palette discovery +59/-0

Test grouped TUI opening and palette discovery

• Verifies grouped worktree opening and filters checkout-matched palette entries to the current repository.

internal/app/herdr_test.go

operations_test.goTest CLI hook finalization and abandonment +68/-0

Test CLI hook finalization and abandonment

• Checks post-init finalization, environment delivery, nonfatal layout errors, and forgetting incomplete setup.

internal/cli/operations_test.go

config_herdr_test.goTest grouping defaults and layout resolution +94/-0

Test grouping defaults and layout resolution

• Covers 'worktree_group' parsing, layout-key precedence and validation, defaults, and CLI overrides.

internal/config/config_herdr_test.go

worktree_hook_test.goTest command parsing and hook dispatch +112/-0

Test command parsing and hook dispatch

• Checks accepted and rejected worktree command forms and confirms that additions and removal outcomes reach the hook.

internal/git/worktree_hook_test.go

herdr_create_test.goExercise Herdr creation and fallback lifecycle +384/-0

Exercise Herdr creation and fallback lifecycle

• Tests branch and ref handling, Git fallback, ambiguous Herdr failures, existing workspaces, rollback, layout behavior, and focus suppression.

internal/multiplexer/herdr_create_test.go

herdr_test.goTest grouping, path reuse, and session cleanup +211/-1

Test grouping, path reuse, and session cleanup

• Covers grouped opening and fallback, checkout-based reuse, cross-session deletion with host protection, and bare-repository detection.

internal/multiplexer/herdr_test.go

Documentation (6) +61 / -2

configuration.mdDocument Herdr creation settings +2/-0

Document Herdr creation settings

• Introduces the opt-in Herdr creation flag and optional workspace layout key in the configuration guide.

docs/configuration.md

reference.mdAdd generated reference entries for Herdr creation +2/-0

Add generated reference entries for Herdr creation

• Lists the types, defaults, and purposes of both new global settings.

docs/configuration/reference.md

custom-commands.mdDocument per-command worktree grouping +1/-0

Document per-command worktree grouping

• Describes 'worktree_group' on Herdr commands and its default grouped behavior.

docs/custom-commands.md

multiplexer-integration.mdExplain Herdr grouping, creation, and deletion +33/-1

Explain Herdr grouping, creation, and deletion

• Covers checkout-path reuse, grouping fallback, cross-session cleanup, opt-in creation, layout timing, trust choices, and focus behavior.

docs/guides/multiplexer-integration.md

help.goExplain Herdr lifecycle options in help +4/-0

Explain Herdr lifecycle options in help

• Adds help text for grouping, deletion cleanup, opt-in creation, layouts, and Cancel Setup.

internal/app/screen/help.go

lazyworktree.1Document Herdr options and lifecycle in the man page +19/-1

Document Herdr options and lifecycle in the man page

• Adds configuration keys and explains grouped opening, deletion cleanup, opt-in creation, fallback, layout timing, and trust behavior.

lazyworktree.1

Other (3) +250 / -202

main.goTeach the config reference generator new keys +139/-131

Teach the config reference generator new keys

• Adds type, description, default, and ordering metadata for the Herdr creation settings.

hack/docsync/main.go

config.goAdd global Herdr creation configuration +71/-58

Add global Herdr creation configuration

• Parses the opt-in creation flag and layout key, supports CLI overrides, and enables grouping on the default Herdr command.

internal/config/config.go

config_herdr.goConfigure grouping and resolve creation layouts +40/-13

Configure grouping and resolve creation layouts

• Defaults Herdr commands to grouped workspaces and resolves an optional layout key with worktrees-pane precedence and warnings for unusable bindings.

internal/config/config_herdr.go

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Command palette docs miss path-based workspace listing ✗ Dismissed

Description

The PR changes how Herdr workspaces are recognised and listed in the command palette (by checkout
path as well as tag) and adds worktree_group to custom commands, and it updates
docs/custom-commands.md. docs/core/command-palette.md is not touched, so the two docs diverge on
palette behaviour.

Code

docs/custom-commands.md[246]

+| `worktree_group` | bool | `true` | Nest workspaces under their repository in the Herdr sidebar via `herdr worktree open`; `false` creates plain workspaces |

Evidence

The rule requires both docs/core/command-palette.md and docs/custom-commands.md to be updated
when custom commands or palette behaviour change. Only the latter is in the diff.

Rule 349612: Keep command palette and custom commands documentation in sync with code changes
docs/custom-commands.md[243-249]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Custom command docs gained `worktree_group` and palette workspace discovery changed, but `docs/core/command-palette.md` was not updated.

## Fix Focus Areas
- docs/core/command-palette.md
- docs/custom-commands.md[243-249]

## Recommended Fix
Add to the command palette doc that Herdr workspaces are listed and matched by checkout path as well as tag, and mention `worktree_group`, keeping wording consistent with custom-commands.md.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Worktree docs describe the old delete behaviour ✗ Dismissed

Description

The delete paths (deleteWorktreeCmd, deleteWorktreeOnlyCmd, the merged-prune path and CLI
delete/cleanup) now close Herdr workspaces, and creation can go through Herdr. The PR changes
neither docs/core/worktree-operations.md nor docs/worktree-lifecycle.md, so both still describe
worktree creation and removal without these steps.

Code

internal/app/worktree_operations.go[R1056-1060]

+		removed := m.state.services.git.RunCommandChecked(m.ctx, []string{"git", "worktree", "remove", "--force", wt.Path}, "", fmt.Sprintf("Failed to remove worktree %s", wt.Path))
		m.state.services.git.RunCommandChecked(m.ctx, []string{"git", "branch", "-D", wt.Branch}, "", fmt.Sprintf("Failed to delete branch %s", wt.Branch))
+		if removed {
+			m.closeHerdrWorktreeWorkspaces(wt.Path)
+		}

Evidence

Worktree lifecycle behaviour changed (workspace closing on delete, Herdr-created worktrees). Both
required docs exist in the repo, but neither appears in the PR's changed files; only
docs/configuration.md, docs/guides/multiplexer-integration.md and others were edited.

Rule 349607: Update both worktree documentation files when changing worktree operations
internal/app/worktree_operations.go[1053-1061]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Worktree delete and create behaviour changed (Herdr workspaces closed on delete; optional Herdr-driven creation, trust prompt Cancel Setup), but the two required worktree docs were not updated.

## Fix Focus Areas
- docs/core/worktree-operations.md
- docs/worktree-lifecycle.md

## Recommended Fix
Describe in both files that deleting a worktree closes its Herdr workspaces, that `use_herdr_for_workspace_create` changes creation, and the Cancel Setup trust option. Keep both files consistent.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Rollback can leave a Herdr workspace open ✗ Dismissed

Description

WorktreeRemoved removes the fresh-worktree entry before calling CloseWorkspace, and a close
failure only produces a warning. When creation is rolled back after a stash-apply failure, Git has
already removed the worktree and the rollback path makes no separate cross-session close attempt,
leaving the workspace pointed at a deleted checkout.

Code

internal/multiplexer/herdr_create.go[R169-174]

+	entry, ok := c.take(path)
+	if !ok {
+		return
+	}
+	h := &Herdr{Bin: c.Bin, Session: entry.session}
+	if err := h.CloseWorkspace(ctx, entry.created.Workspace.ID); err != nil {

Evidence

The hook consumes its tracked entry before attempting the close, while the stash-apply rollback
performs only Git removal and stash restoration. The normal TUI deletion path has a separate
cross-session close, but this rollback does not.

internal/multiplexer/herdr_create.go[162-176]
internal/git/service.go[347-355]
internal/app/worktree_operations.go[443-454]
internal/app/worktree_operations.go[1055-1060]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A failed Herdr close during worktree-creation rollback leaves a workspace open after its checkout is removed.
## Fix Focus Areas
- internal/multiplexer/herdr_create.go[162-176]
- internal/app/worktree_operations.go[445-455]
## Recommended Fix
Ensure a failed close in the rollback path is retried through path-based workspace cleanup, or otherwise retain enough state for a cleanup attempt after Git removes the worktree.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

4. Orphan cleanup leaves Herdr workspaces open ✗ Dismissed

Description

The new cleanup calls close Herdr workspaces only for registered worktrees removed through `git
worktree remove; orphan candidates still go directly through os.RemoveAll`. If a checkout loses
its Git registration while its directory and Herdr workspace remain, CLI or TUI orphan cleanup
deletes the directory without closing the workspace.

Code

internal/cli/cleanup.go[R382-384]

+			if removed {
+				closeHerdrWorkspaces(ctx, candidate.worktree.Path, silent, stderr)
+			}

Evidence

Herdr workspace cleanup matches the checkout path, but the added cleanup calls cover only registered
worktrees. Both orphan branches remove directories without invoking that path-based cleanup.

internal/cli/cleanup.go[369-384]
internal/cli/cleanup.go[417-434]
internal/app/worktree_operations.go[895-902]
internal/app/worktree_operations.go[929-943]
internal/multiplexer/herdr.go[848-867]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Orphan-directory cleanup can delete a checkout path without closing its Herdr workspace.
## Fix Focus Areas
- internal/cli/cleanup.go[417-434]
- internal/app/worktree_operations.go[929-943]
## Recommended Fix
After successful orphan-directory removal, invoke the same path-based Herdr workspace cleanup used for registered worktree deletion in both CLI and TUI cleanup.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 29 rules

Review mode: Auto: 🧠 Deep: Broad integration change with dense independent logic across creation, deletion, grouping, and trust paths.

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[Copilot]

🔵 Needs a closer look

One or more reviewer sessions failed, leaving insufficient evidence to complete the approval-readiness review.

No open issues 🎉

What changed in this PR

This PR extends LazyWorktree’s Herdr integration to group workspaces by repository, optionally delegate worktree creation to Herdr, and close associated workspaces after deletion.

Changes:

• Opens grouped workspaces and recognises existing ones by checkout path as well as tags.
• Adds opt-in Herdr creation with Git fallback, post-init layouts, cancellation handling, and background focus control.
• Connects workspace cleanup to deletion flows and adds tests, configuration, and documentation.

Tests were not run in this review environment.

File	Description
lazyworktree.1	Documents grouping, creation options, and cleanup behaviour.
internal/​multiplexer/​herdr.go	Adds grouped opening, checkout matching, and cross-session cleanup.
internal/​multiplexer/​herdr_test.go	Tests grouping, reuse, fallback, and cleanup.
internal/​multiplexer/​herdr_create.go	Implements Herdr creation, Git fallback, and layout finalisation.
internal/​multiplexer/​herdr_create_test.go	Tests creation, recovery, rollback, layouts, and focus control.
internal/​models/​models.go	Adds the worktree creation request model.
internal/​git/​worktree_hook.go	Defines lifecycle hooks and parses supported worktree commands.
internal/​git/​worktree_hook_test.go	Tests command parsing and hook routing.
internal/​git/​service.go	Routes worktree operations through installed hooks.
internal/​config/​config.go	Adds creation settings, overrides, and default grouping.
internal/​config/​config_herdr.go	Parses grouping and resolves creation layout bindings.
internal/​config/​config_herdr_test.go	Tests grouping defaults, layout resolution, and overrides.
internal/​cli/​operations.go	Integrates deletion cleanup and post-init finalisation.
internal/​cli/​operations_test.go	Tests CLI finalisation and setup abandonment.
internal/​cli/​cleanup.go	Closes workspaces after successful cleanup removal.
internal/​bootstrap/​commands.go	Enables CLI creation hooks and grouped workspace opening.
internal/​bootstrap/​bootstrap.go	Prevents workspace focus when output selection is enabled.
internal/​app/​worktree_operations.go	Routes creation through setup handling and adds deletion cleanup.
internal/​app/​screen/​trust.go	Supports a custom cancellation label.
internal/​app/​screen/​help.go	Explains new Herdr options and Cancel Setup.
internal/​app/​herdr.go	Integrates grouped opening, palette matching, and cleanup.
internal/​app/​herdr_test.go	Tests grouped opening and repository workspace filtering.
internal/​app/​base_selection.go	Sends creation setup requests to the update loop.
internal/​app/​base_selection_test.go	Adapts tests to deferred setup handling.
internal/​app/​app.go	Installs the Herdr creator and handles setup messages.
internal/​app/​app_helpers.go	Adds background-only workspace focus control.
internal/​app/​app_git.go	Coordinates trust decisions, init commands, and finalisation.
internal/​app/​app_git_test.go	Tests setup ordering and trust prompt choices.
hack/​docsync/​main.go	Adds new options to generated configuration metadata.
docs/​guides/​multiplexer-integration.md	Explains grouping, creation, layouts, and lifecycle behaviour.
docs/​custom-commands.md	Documents the grouping option.
docs/​configuration/​reference.md	Adds generated entries for creation settings.
docs/​configuration.md	Summarises the new creation options.

_{Review effort: Balanced}