https://github.com/kunchenguid/treehouse
Manage worktrees without managing worktrees.
https://github.com/kunchenguid/treehouse
agents coding git worktree
Last synced: 23 days ago
JSON representation
Manage worktrees without managing worktrees.
- Host: GitHub
- URL: https://github.com/kunchenguid/treehouse
- Owner: kunchenguid
- License: mit
- Created: 2026-03-14T19:20:20.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-28T18:52:41.000Z (30 days ago)
- Last Synced: 2026-03-28T20:40:37.372Z (30 days ago)
- Topics: agents, coding, git, worktree
- Language: Go
- Homepage:
- Size: 1.51 MB
- Stars: 28
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
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
```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
🌳 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
```
**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 `~/.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`
```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
```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
```