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 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

$ 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
🌳 Worktree returned to pool.

Install

macOS / Linux

curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh

Windows (PowerShell)

irm https://kunchenguid.github.io/treehouse/install.ps1 | iex

Go

go install github.com/kunchenguid/treehouse@latest

From source

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 ~/.treehouse/.

  treehouse
      │
      ▼
  Find repo root
      │
      ▼
  git fetch origin
      │
      ▼
  ┌────────────────────────────────────┐
  │  Scan pool for available worktree  │
  │  (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
           │
           ▼
  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 to determine which worktrees are in-use. Usage state is never persisted, so it's always accurate.

CLI Reference

Command	Description
treehouse	Get a worktree and open a subshell (alias for get)
treehouse get	Acquire a worktree from the pool
treehouse status	Show pool status (highlights your current worktree)
treehouse return [path]	Return a worktree to the pool
treehouse destroy [path]	Remove a worktree from the pool
treehouse init	Create a default treehouse.toml config file
treehouse update	Update treehouse to the latest version

Flags

Command	Flag	Description
return	--force	Skip dirty-check prompt
destroy	--force	Force destroy even if in-use
destroy	--all	Destroy all worktrees in the pool

Configuration

Create a config file with treehouse init, or add one manually:

Repo-level: treehouse.toml in the repository root

User-level: ~/.config/treehouse/config.toml

# Maximum number of worktrees in the pool
max_trees = 16

The repo-level config takes precedence. If no config is found, the default pool size is 16.

Development

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