treehouse

Manage worktrees without managing worktrees.

Are you still only working on one task at a time? Are you manually juggling between a few clones of the same repo? Or... are you starting a new worktree for every agent session, losing all your installed dependencies and build cache each time, and wondering why your agents are slow?

treehouse demo

Treehouse helps you manage a pool of reusable, isolated worktrees so each of your agents gets its own environment instantly — no cloning, no conflicts, no coordination overhead. - **Instant isolation** — `treehouse` puts you into a clean worktree with zero hassel. - **Reusable worktrees** — worktrees are preserved in a pool when you're done, with dependencies and build cache intact, ready for the next agent. - **Conflict-free** — automatic detection of in-use worktrees and your agents never step on each other's toes. ## Quick Start ```sh $ cd myproject # start in your repo as usual $ treehouse # get a worktree and drop into a subshell 🌳 Entered worktree at ~/.treehouse/myproject-a1b2c3/1/myproject. Type 'exit' to return. # You're now in an isolated worktree. # Run your AI agent, make changes, do whatever you need. $ exit # exit the subshell when you're done 🌳 Terminated lingering processes: opencode (pid 12345) 🌳 Worktree returned to pool. ``` ## Install **macOS / Linux** ```sh curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh ``` **Windows (PowerShell)** ```powershell irm https://kunchenguid.github.io/treehouse/install.ps1 | iex ``` **Nix** ```sh nix run github:kunchenguid/treehouse ``` Or add to your flake inputs: ```nix treehouse = { url = "github:kunchenguid/treehouse"; inputs.nixpkgs.follows = "nixpkgs"; }; ``` **Go** ```sh go install github.com/kunchenguid/treehouse@latest ``` **From source** ```sh git clone https://github.com/kunchenguid/treehouse.git cd treehouse make install ``` ## How It Works Treehouse manages a **pool of git worktrees** per repository, stored under the configured treehouse root. The default treehouse root is `~/.treehouse/`. ``` treehouse │ ▼ Find repo root │ ▼ git fetch origin │ ▼ ┌───────────────────────────────────────┐ │ Scan pool for available worktree │ │ (not leased, not in-use, not dirty) │ └──────────┬────────────────────────────┘ │ ┌────┴────┐ │ Found? │ └────┬────┘ yes/ \no / \ ▼ ▼ Reset to Create new worktree latest (detached HEAD at default latest default branch branch) & add to pool \ / \ / ▼ Spawn subshell in worktree (agent works here) │ ▼ exit subshell │ ▼ Terminate lingering worktree processes, reset worktree, & return to pool (ready for next agent) ``` - **Detached HEAD** — worktrees use detached HEAD mode, reset to whichever of the local or remote default branch is further ahead, avoiding branch name conflicts entirely. - **No daemon** — all operations are inline CLI commands. No background processes, no state to get corrupted. - **In-use detection** — treehouse scans running processes and short-lived owner reservations to determine which worktrees are in-use. Reservations are persisted only while `get`, `destroy`, and `prune` lifecycle work is running. - **Durable leases** — `treehouse get --lease` reserves a worktree as a persistent home without keeping a process inside it. The lease is recorded in treehouse's own state, so the worktree is never handed out by a later `get` and never removed by `prune` until you release it with `treehouse return`. Unlike process-based in-use detection, a lease survives with zero processes running inside the worktree. - **Dirty detection** - treehouse treats tracked changes and untracked files as dirty, even when repository config hides untracked files from normal `git status` output. - **Safe pruning** - By default, `treehouse prune` removes only idle managed worktrees whose HEAD is already merged into the default branch and whose working tree is clean. `treehouse prune --all` applies the same safety checks across every managed pool under the user-level treehouse root. Backing-repository-missing orphans are reported by default; `--prune-orphans` includes them as unverified prune candidates, and `--yes` is required before deletion. It is a dry run unless you pass `--yes`. ## CLI Reference | Command | Description | | -------------------------- | ---------------------------------------------------- | | `treehouse` | Get a worktree and open a subshell (alias for `get`) | | `treehouse get` | Acquire a worktree from the pool | | `treehouse get --lease` | Durably lease a worktree without a subshell; print its path | | `treehouse status` | Show pool status (highlights leased and current worktrees) | | `treehouse return [path]` | Release any lease, terminate lingering worktree processes, and return it to the pool | | `treehouse prune` | Dry-run removal of stale idle worktrees in the current repo pool | | `treehouse prune --all` | Dry-run removal of stale idle worktrees across every managed pool | | `treehouse destroy ` | Dry-run removal of one worktree (safe by default; `--yes` to execute) | | `treehouse destroy --all` | Dry-run removal of every disposable worktree in that pool | | `treehouse init` | Create a default `treehouse.toml` config file | | `treehouse update` | Update treehouse to the latest version | ### Flags | Command | Flag | Description | | --------- | --------- | --------------------------------- | | `get` | `--lease` | Durably lease the worktree without opening a subshell; print only its path to stdout | | `get` | `--lease-holder` | Optional label recorded as the lease holder (defaults to `$TREEHOUSE_LEASE_HOLDER`) | | `return` | `--force` | Clean, reset, and return without prompting | | `prune` | `--yes` | Delete listed prune candidates instead of doing a dry run | | `prune` | `--all` | Sweep every managed pool under the user-level treehouse root | | `prune` | `--global` | Alias for `--all` | | `prune` | `--prune-orphans` | Include backing-repository-missing orphans in prune candidates | | `prune` | `--verbose`, `-v` | Show detailed skip diagnostics | | `destroy` | `--all` | Remove all worktrees in the named pool (requires a pool path) | | `destroy` | `--yes` | Execute the removal instead of doing a dry run | | `destroy` | `--include-unlanded` | Also remove dirty, unmerged, or unverified worktrees (irreversible data loss) | | `destroy` | `--include-in-use` | Also remove worktrees with a running process or owner reservation (processes are terminated cleanly first) | | `destroy` | `--include-leased` | Also remove a leased worktree; only when the exact path is named, never via `--all` | ### Leasing a worktree (no subshell) `treehouse get` normally opens an interactive subshell whose lifetime is the hold: when the shell exits, the worktree returns to the pool. That is awkward for callers that need a worktree to persist as a permanent home with no long-lived process inside it. `treehouse get --lease` is the non-interactive, durable alternative: ```sh path=$(treehouse get --lease) # $path is the leased worktree's absolute path; all banners went to stderr. ``` It acquires a worktree exactly like `get`, but instead of opening a subshell it marks the worktree **leased** in treehouse's persistent state and prints only the worktree's absolute path to stdout (every human-facing message goes to stderr, so command substitution stays clean). A leased worktree is never handed out by a later `get` and never removed by `prune`, regardless of whether any process runs inside it, until the lease is explicitly released. A bulk `treehouse destroy --all` never removes it either; only naming its exact path with `treehouse destroy --include-leased --yes` will. Pass `--lease-holder ` (or set `$TREEHOUSE_LEASE_HOLDER`) to record who holds the lease; `treehouse status` then shows it next to the `leased` state. Release a lease with `treehouse return `, which clears the lease, terminates any lingering processes, resets the worktree, and returns it to the pool. When you pass an explicit path, `treehouse return` can run from outside the repository because it resolves the managed pool from that worktree path. ### Pruning stale worktrees and orphans `treehouse prune` is a dry run by default. By default, it lists stale idle managed worktrees that would be deleted and shows the reclaimable disk space. Pass `treehouse prune --yes` to delete those worktrees. By default, prune only inspects the current repository's pool and must be run inside a git repo. Pass `treehouse prune --all` or `treehouse prune --global` to inspect every managed pool under the user-level treehouse root from any directory. Global prune reads the user-level config and hooks, derives each worktree's owning repository from git metadata, then fetches and checks merge safety against that repository. Without `--prune-orphans`, pass `treehouse prune --all --yes` to delete only the globally safe stale candidates. Prune ignores worktrees that are currently in use, leased, or reserved by another lifecycle operation. It skips idle worktrees that are unsafe to remove and prints the skip reason, such as uncommitted tracked or untracked changes, or a HEAD commit that is not merged into the default branch. Skip output is grouped by reason so large global sweeps stay scannable. When `origin` exists, prune fetches it and proves each HEAD against the current remote default branch tracking ref. Without `origin`, prune uses the local default branch ref. If `origin` cannot be reached, prune reports `origin unreachable (cannot verify)` and leaves the worktree untouched, even when `--prune-orphans` is set. If a linked worktree points at a missing backing repository, prune reports `orphaned (backing repository missing)`. Plain `treehouse prune` and `treehouse prune --all` never delete those orphans. Pass `--prune-orphans` to include true backing-repository-missing orphans in the dry run, then add `--yes` to delete them. Treehouse cannot verify orphan contents after the backing git metadata is gone, so each orphan candidate is marked `content could not be verified`. Use `--verbose` to show the underlying git diagnostic details for skipped worktrees. ### Destroying worktrees `treehouse destroy` is the deliberate tool for removing a worktree even though it still has unlanded work, but it is safe by default and holds itself to the same bar as `prune`. Targets are narrow and explicit: - `treehouse destroy ` targets exactly one worktree. - `treehouse destroy --all` targets worktrees in THAT pool only. The pool path can be the pool directory, a worktree inside it, or the repository (`.` works from inside a repo). There is no cross-pool or global destroy: `--all` without a pool path is an error, so a stray command can never reach beyond the pool you named. Destroy is a dry run by default. It prints a risk-revealing preview - one or more status labels (`[disposable]`, `[leased]`, `[in-use:]`, `[unmerged]`, `[dirty]`, `[unverified]`, or a comma-separated combination such as `[leased,dirty]`), the path, and the size of each target - and removes nothing. Pass `--yes` to execute. It never prints a blind "all worktrees destroyed"; the summary always reports exactly what was destroyed and what was skipped. A bare `treehouse destroy --all --yes` removes only the genuinely disposable set (merged, clean, idle, unleased - the same set `prune` would take) and SKIPS everything else, telling you which flag would include it. Each risky class is its own opt-in, so removing risky worktrees can never be a reflexive `--yes`: - `--include-unlanded` also removes worktrees with uncommitted changes, a HEAD not merged into the default branch, or contents treehouse cannot verify, such as a missing backing repository (irreversible data loss). - `--include-in-use` also removes worktrees with a running process or owner reservation; their processes are terminated cleanly first and their pids are shown in the preview. - `--include-leased` also removes a leased worktree, but only when you name the exact worktree path. Leased worktrees are NEVER removed by `--all`; combining `--include-leased` with `--all` is rejected. A single named worktree that is skipped for lack of a flag makes the command exit non-zero, so scripts notice that nothing happened. Bulk `--all` skips are normal and exit zero; inspect the summary to see what remains. #### Migrating from `--force` The old blunt `treehouse destroy --force` flag has been removed. It overrode every protection at once - in-use, unmerged, dirty, and leased - which is what made it dangerous. Replace it with the specific `--include-*` flag(s) for the risk you actually intend to override, plus `--yes`: | Old | New | | --- | --- | | `treehouse destroy --force` | `treehouse destroy --yes` (add `--include-unlanded` / `--include-in-use` / `--include-leased` as needed) | | `treehouse destroy --all --force` | `treehouse destroy --all --yes` (add `--include-unlanded` for dirty, unmerged, or unverified targets, and `--include-in-use` for in-use targets; leased homes are never included) | ## Configuration Create a repo config file with `treehouse init`, or add one manually: **Repo-level:** `treehouse.toml` in the repository root **User-level:** `~/.config/treehouse/config.toml` ```toml # Maximum number of worktrees in the pool max_trees = 16 # Optional worktree root directory. # Empty uses $HOME/.treehouse. # Relative paths are resolved from the repo root for repo-scoped commands. # Use an absolute user-level root for treehouse prune --all. # root = "$HOME/worktrees" ``` The repo-level config takes precedence for repo-safe settings. `treehouse prune --all` can run without a repository, so it uses only the user-level config and does not read per-repo `treehouse.toml` files while sweeping. If no config is found, the default pool size is 16. ### Hooks You can run commands automatically at worktree lifecycle points by adding a `[hooks]` section to the user-level config at `~/.config/treehouse/config.toml`. Hooks in repo-level `treehouse.toml` are ignored for safety. `treehouse destroy` always reads `pre_destroy` from the user-level config because it can target a pool by path. ```toml [hooks] post_create = ["./scripts/setup-venv.sh"] pre_destroy = ["./scripts/teardown.sh"] ``` - `post_create` runs after a worktree is provisioned or reset and right before `treehouse get` hands it to you. For `treehouse get --lease`, stdout from `post_create` is routed to stderr so stdout remains the leased path. - `pre_destroy` runs before a worktree is removed by `treehouse destroy --yes`, `treehouse destroy --all --yes`, or prune deletion commands such as `treehouse prune --yes` and `treehouse prune --prune-orphans --yes`. Commands in each list run sequentially in the worktree directory, via the OS shell (`/bin/sh -c` on Linux/macOS, `%COMSPEC% /c` on Windows). If a command exits non-zero, treehouse logs the command, exit code, and stderr, then continues with the remaining commands. A failing hook does not fail the overall `get`, `destroy`, or `prune` operation. ## Development ```sh make build # Build the binary make test # Run tests make lint # Run gofmt + go vet make dist # Cross-compile for all platforms make install # Install to $GOPATH/bin or /usr/local/bin make clean # Remove build artifacts ```