herdr-treehouse

A Herdr plugin that bridges Herdr workspaces with Treehouse worktree leases. It provides a popup for opening a Git branch as a leased Treehouse worktree in Herdr, and keeps the worktree pool clean by returning leases for workspaces that no longer exist.

Behavior

• Branch popup (branch-worktree): prompts with Gum for an existing local/remote branch or a new branch name, leases a Treehouse checkout, and opens it as a Herdr workspace. If the pane is cancelled or fails after leasing, the lease is released so no worktree is left dangling.
• Lifecycle reconciliation: on startup and on workspace, worktree, and pane lifecycle events, the plugin snapshots the current Herdr workspaces and returns any Treehouse checkout that is no longer leased by a live workspace. Reconciliation runs under a non-blocking process-wide lock, so concurrent events never double-return a lease. Worktrees still referenced by a workspace are never touched.
• Parent focus restoration: when a focused linked-worktree workspace closes, the plugin matches its repository identity to the surviving main-worktree workspace and focuses that parent instead of leaving Herdr on an unrelated list neighbor.

Dependencies

Runtime:

• Herdr >= 0.7.5 — external; the plugin is installed and run by Herdr.
• Git — used by the scripts to enumerate branches and resolve repositories.
• Python 3
• Gum — powers the branch picker in the popup.
• Treehouse — provides the worktree leases.

Installation

Herdr 0.7.5 installs plugins from GitHub shorthand only. This repository is hosted on Forgejo, so clone it and link the checkout:

git clone https://git.fryuni.dev/Fryuni/herdr-treehouse.git
herdr plugin link ./herdr-treehouse --enabled

If it was linked disabled, enable it explicitly:

herdr plugin enable local.herdr-treehouse

The manifest defines no default keybinding, so open the branch picker pane explicitly (or bind it yourself in your Herdr configuration):

herdr plugin pane open --plugin local.herdr-treehouse --entrypoint branch-worktree --focus

Development

Link the local checkout into Herdr instead of installing from GitHub:

herdr plugin link /path/to/herdr-treehouse --enabled

Nix shell

A development shell with Python 3, Gum, and Treehouse is provided by the flake (Herdr itself is an external dependency and is intentionally not included):

nix develop

Tests

The test suite uses the Python standard library only:

python3 -m unittest

License

See LICENSE.