kunchenguid/treehouse

What it solves

Treehouse manages a pool of reusable, isolated git worktrees, eliminating the need to manually juggle multiple clones of the same repository or create new worktrees for every AI agent session. It prevents agents from conflicting with each other and ensures that dependencies and build caches are preserved across sessions, which speeds up agent execution.

How it works

Treehouse maintains a pool of worktrees stored in a configured root directory (defaulting to ~/.treehouse/). When a user or agent requests a worktree, Treehouse scans the pool for an idle, clean, and reusable one. If found, it resets the worktree to the latest default branch; otherwise, it creates a new one in detached HEAD mode.

Key mechanisms include:

• Subshell Access: Users are dropped into a subshell within the worktree; exiting the shell returns the worktree to the pool.
• Durable Leases: Worktrees can be leased for persistent use without a long-lived process, requiring an explicit return command to be recycled.
• In-use Detection: The tool scans running processes and reservations to ensure worktrees are not handed out while active.
• Safety Checks: Pruning and destruction of worktrees are dry-run by default and only remove worktrees that are clean and merged into the default branch unless specific override flags are used.

Who it’s for

Developers and AI agent operators who need multiple isolated environments for the same project without the overhead of cloning or the loss of build caches.

Highlights

• Instant Isolation: Quickly enter a clean worktree without manual setup.
• Reusable Environments: Preserves dependencies and build caches to avoid redundant installations.
• Conflict-Free: Automatic detection of in-use worktrees prevents agents from stepping on each other.
• Safe Management: Robust pruning and pruning of orphans and state recovery for damaged pool state files.