tmux-treehouse

A tmux plugin that leases a Treehouse worktree from the current pane's directory, opens it in a detached tmux session, and returns the lease when that session closes.

Prerequisite

Install and configure the Treehouse CLI first. This plugin targets Treehouse v2.1.1, including its lease JSON interface. The current pane must be in a directory from which treehouse get --lease can obtain a worktree.

Installation

TPM

Add the plugin after TPM in ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'https://git.fryuni.dev/Fryuni/tmux-treehouse'

Reload tmux and press prefix then I to install through TPM.

Direct installation

Clone the repository somewhere persistent and source the root plugin entrypoint from ~/.tmux.conf:

run-shell '/absolute/path/to/tmux-treehouse/treehouse.tmux'

The direct install uses the Treehouse CLI and required tools already available on your PATH.

Nix flake package

The flake exports both packages.<system>.default and packages.<system>.tmux-treehouse. Installing either produces the conventional tmux plugin tree, including:

share/tmux-plugins/tmux-treehouse/treehouse.tmux

For example, add the package to a Nix profile:

nix profile install git+https://git.fryuni.dev/Fryuni/tmux-treehouse

Then source its store path in tmux configuration (replace the placeholder with the package output path):

run-shell '/nix/store/...-tmux-treehouse/share/tmux-plugins/tmux-treehouse/treehouse.tmux'

The packaged helper scripts are wrapped with treehouse v2.1.1, tmux, python3, and the POSIX shell utilities they use. This does not alter direct installation: direct installs continue to use the caller's PATH.

Nix overlay and Home Manager

The flake's overlays.default adds the package at pkgs.tmuxPlugins.treehouse. In a NixOS or Home Manager flake input named tmux-treehouse, add the overlay:

nixpkgs.overlays = [ tmux-treehouse.overlays.default ];

Home Manager can then load it using its normal tmux plugin support:

programs.tmux = {
  enable = true;
  plugins = [ pkgs.tmuxPlugins.treehouse ];
};

Configuration and behavior

By default press prefix then W (uppercase) in a pane whose current directory is a Treehouse pool. The plugin leases a worktree, creates a detached tmux session rooted at that leased path, and moves the invoking client into the new session.

Set @treehouse-key before sourcing the plugin to use a different key in the prefix table:

set -g @treehouse-key 'L'
run-shell '/absolute/path/to/tmux-treehouse/treehouse.tmux'

When the leased session closes, the plugin uses Treehouse's lease identity to return exactly that lease. Its lifecycle hook is additive, so other session-closed hooks remain installed.