treehouse: a reusable git worktree pool for parallel coding agents
Manage worktrees without managing worktrees.
At a glance
- What is it?
- treehouse is a Go CLI that keeps a pool of git worktrees per repository, hands each agent session an isolated checkout, and returns it afterwards with dependencies and build cache intact. It is a good fit if you run several agents in one repo; it is not a general worktree manager for human branches.
- Who is it for?
- Adopt treehouse if you run multiple agent sessions against one repository and want each to start from an isolated checkout without re-cloning or rebuilding from scratch. Do not adopt it if you need branch-based human workflows, since worktrees run in detached HEAD and are reset on return.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem treehouse solves: agent sessions that keep paying setup cost
The README frames the problem as a choice between two bad habits. Either you work on one task at a time, or you juggle a few clones of the same repository by hand. A third option, starting a fresh worktree for every agent session, is worse than it sounds: the README says you lose installed dependencies and build cache each time, and asks why your agents are slow.
treehouse targets that third case. It maintains a pool of git worktrees per repository and hands one to each session, so the checkout is isolated but the expensive setup work is not repeated. The audience is narrow and specific: people running coding agents in a repository where dependency installation or a warm build cache is the slow part of starting work. If your project builds in two seconds from a clean clone, the pool buys you little. If your agent spends minutes reinstalling packages, the pool is the point.
How the pool works: fetch, scan, reset or create, subshell
The README's flow diagram is the clearest description of the mechanism. Running treehouse finds the repository root, runs git fetch origin, then scans the pool for a worktree that is safely reusable: idle, unleased, clean, and with HEAD merged into the exact reset target. If safety cannot be proven, the scan skips that worktree. If one is found, it is reset to the latest default branch. If not, a new worktree is created with a detached HEAD at the latest default branch and added to the pool. Either way, treehouse spawns a subshell in the worktree and the agent works there.
On exit, the sequence reverses. treehouse terminates lingering processes in the worktree and verifies none remain, then resets the worktree and returns it to the pool. The demo output in the README shows this concretely: exiting prints a line naming a terminated process by name and pid, then a line saying the worktree was returned to the pool. That process termination step is what makes reuse safe in practice, and it is also the sharpest edge of the design, discussed below.
Two structural choices stand out. There is no daemon: the README states all operations are inline CLI commands, and pool state is a small on-disk file written under a lock by each command. And worktrees use detached HEAD, reset to whichever of the local or remote default branch is further ahead, which the README says avoids branch name conflicts entirely. That is a real trade-off, not just a convenience: detached HEAD means no branch is checked out, so anything that assumes a branch name will not find one.
The default pool root is ~/.treehouse/, and the README describes an in-project alternative, --root ., which keeps the pool next to the code so it is removed with the project. Several knobs are opt-in and creation-only: base_branch or treehouse get --base selects the commit new worktrees start at (still detached HEAD, it does not create a branch); unique_leaf or treehouse get --unique-leaf names new slots <repo>-<slot> so tooling that derives identity from the directory name can tell slots apart; worktree_path or treehouse get --worktree-path '<template>' places new worktrees elsewhere. The README is explicit that worktree_path applies only to creation, and that worktrees already in the pool keep their recorded paths.
Installing treehouse and getting your first worktree
The README lists five install paths. On macOS and Linux the install script is the shortest:
curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | shOn Windows the PowerShell equivalent pipes the install script into iex:
irm https://kunchenguid.github.io/treehouse/install.ps1 | iexIf you already have Go 1.25.5 or later, the module install works too, and the go.mod in the repository confirms the module path:
go install github.com/kunchenguid/treehouse@latestNix users can run it without installing, or pin the v2.3.0 release tag:
nix run github:kunchenguid/treehouse
nix run github:kunchenguid/treehouse/v2.3.0For a first real use, the README's quick start is two commands. Change into your repository, then run treehouse with no arguments:
cd myproject
treehouseWhat you should see is a message stating you entered a worktree, with a path of the shape ~/.treehouse/myproject-a1b2c3/1/myproject, and a note to type exit to return. At that point you are inside a subshell in the isolated worktree, so you can start your agent there. When you are done, exit the subshell. The README's example output shows treehouse reporting any lingering processes it terminated, then a line stating the worktree was returned to the pool. If you want the pool to live inside the project instead of ~/.treehouse/, pass --root . on that first invocation.
Where treehouse gets uncomfortable: process termination and unprovable safety
The reuse check is deliberately conservative. A worktree is reused only if it is idle, unleased, clean, and has HEAD merged into the exact reset target; the README says the scan skips a worktree when safety cannot be proven. In practice that means a worktree with uncommitted changes, or one whose HEAD is not merged into the reset target, will not be handed to the next session. The pool then grows a new worktree instead. If your agents routinely leave uncommitted work behind, the pool turns into accumulation rather than reuse, and you will be creating worktrees at roughly the rate you create sessions. The README does not document an automatic reclamation policy for those skipped worktrees beyond the prune lifecycle command it mentions.
The second sharp edge is exit-time process termination. treehouse terminates lingering processes in the worktree and verifies none remain. That is what prevents a background dev server or a stuck agent from corrupting the next session, but it also means anything you leave running in the subshell is killed on exit. If your workflow depends on a long-lived process inside the worktree, this design is working against you. The README documents the termination behaviour but does not document rollback or a way to opt out of it.
The third is shell handling. On macOS and Linux, treehouse, treehouse get, and treehouse enter start $SHELL as an interactive login shell when it resolves to bash, fish, or zsh. Other shells, fallback shells, and Windows use their default invocation. The README calls out an accepted limitation: a regular executable merely named like a supported shell, for example a wrapper script at /opt/tools/bash, will not accept -i -l, and the resolved basename is treated as the contract rather than probing PATH identity. If you use a shell wrapper, expect the wrong invocation.
Finally, in-use detection scans running processes and short-lived owner reservations, with reservations persisted only while the get, destroy, and prune lifecycle work is running. That is a reasonable design for a daemonless tool, but it means correctness depends on process visibility. In containers or sandboxes where process listings are restricted, the detection has less to work with. The README does not claim otherwise.
treehouse compared with plain git worktree and manual clones
The obvious alternative is git worktree itself, which already creates additional checkouts sharing one object database. The difference is what happens between sessions. A plain git worktree is a checkout you create and later remove; nothing tracks whether it is idle, nothing resets it to a fresh commit, and nothing terminates the processes your agent left behind. You get the disk and clone savings but you manage the lifecycle yourself, including the cleanup step people tend to skip.
treehouse adds the pool and the lifecycle on top: a scan for a safely reusable slot, a reset to the latest default branch, a subshell that scopes the session, and process termination plus verification on exit. It also adds state, a lock, and commands like get, enter, destroy, and prune. The cost of that is the detached HEAD model and the reset semantics: a returned worktree is not preserved as you left it, it is reset for the next agent. If you want a worktree to keep a branch and your uncommitted work for days, plain git worktree or a manual clone is the better tool, and treehouse's reuse check will deliberately refuse to hand that worktree to someone else anyway.
A second alternative is one clone per agent session, which is what the README contrasts against. Clones are simpler to reason about and have no shared pool state, but each clone pays full setup cost, which is exactly the cost treehouse exists to avoid.
Maintenance, upgrades and the MIT licence
The repository is not archived, and the last push was on 2026-09-14, the day before this writing, so the project is being worked on. Release cadence is visible in the tags: v2.2.0 and v2.2.1 on 2026-08-21, and v2.3.0 on 2026-08-22. The repository also carries release-please-config.json and .release-please-manifest.json, which indicates automated release management, and CHANGELOG.md for the resulting history.
Upgrade cost depends on how you installed it. The curl and PowerShell install scripts fetch a release, Go installs track @latest or a pinned version, and Nix users can pin a tag such as v2.3.0 or follow the flake. The Makefile shows the build is a single go build with a version ldflag, so building from source is not a large undertaking. The configuration surface is small: treehouse.toml with keys like base_branch, unique_leaf, and worktree_path, plus a treehouse.toml.example in the repository root to start from. The README notes that worktree_path and unique_leaf are creation-only, so changing them does not move worktrees already in the pool. That is the main upgrade hazard: config changes apply to new slots, not existing ones.
The licence is MIT. That is permissive and places few obligations on how you redistribute or modify the tool. This is not legal advice; read the LICENSE file in the repository if the distinction matters to your organisation.
Editorial conclusion
Adopt treehouse if you run multiple agent sessions against one repository and want each to start from an isolated checkout without re-cloning or rebuilding from scratch. Do not adopt it if you need branch-based human workflows, since worktrees run in detached HEAD and are reset on return. Before rolling it out, verify two things on your own machine: that your agents' processes are visible to treehouse's in-use detection, and that its reset target (the further-ahead of the local or remote default branch) matches the commit you actually want agents working from.
Frequently asked questions
What is treehouse?
treehouse is a Go command-line tool that manages a pool of reusable git worktrees per repository, so each coding agent session gets an isolated checkout without re-cloning or rebuilding dependencies from scratch. It runs as inline CLI commands with no daemon, and pool state is a small on-disk file written under a lock.
Does treehouse still exist?
The repository is not archived and the last push was on 2026-09-14, with v2.3.0 released on 2026-08-22. It installs from an install script, Nix, or go install github.com/kunchenguid/treehouse@latest.
How do I install treehouse?
On macOS and Linux the README gives curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh; on Windows it gives the PowerShell install script. Go and Nix installs are also documented, and building from source uses make install.
Does treehouse create a branch for each worktree?
No. According to the README, worktrees use detached HEAD mode and are reset to whichever of the local or remote default branch is further ahead, which it says avoids branch name conflicts entirely. The base_branch setting selects the commit new worktrees start at; it does not create or check out a branch.
What happens to processes I leave running in a treehouse worktree?
On exit from the subshell, treehouse terminates lingering worktree processes and verifies none remain before resetting the worktree and returning it to the pool. The README's example output shows a terminated process reported by name and pid.
Where does treehouse store its worktrees?
The default treehouse root is ~/.treehouse/. The README also documents keeping the pool inside the project with --root ., so it lives next to the code and is removed with the project.
Community notes