treehouse-worktree 🌲

A cross-platform git worktree manager designed for parallel AI agent workflows. Supports both CLI and MCP (Model Context Protocol) interfaces.

Why Treehouse?

When multiple AI agents need to work on the same repository simultaneously, git worktrees provide isolated working directories without the overhead of multiple clones. Treehouse simplifies worktree management with:

• Agent coordination - Lock worktrees to prevent conflicts between agents
• Automatic setup - Run install commands when creating worktrees
• MCP support - Integrate with AI tools via Model Context Protocol
• Cursor compatibility - Works with .cursor/worktrees.json config format

Quick Start

# Install globally
npm install -g treehouse-worktree

# Initialize in your repo
cd your-repo
treehouse init

# Create a worktree for an agent
treehouse create feature-api --agent claude-1

# List all worktrees
treehouse list

# Complete and merge work
treehouse complete feature-api --merge

# Remove when done
treehouse remove feature-api

Installation

# npm
npm install -g treehouse-worktree

# Or run directly with npx
npx treehouse-worktree init

CLI Commands

Basic Operations

# Initialize configuration
treehouse init

# Create a new worktree
treehouse create <name> [branch]
treehouse create feature-api              # uses 'feature-api' as branch
treehouse create agent-1 feature/new-api  # uses custom branch name

# List all worktrees
treehouse list

# Get status
treehouse status                  # all worktrees
treehouse status feature-api      # specific worktree

# Remove a worktree
treehouse remove <name>
treehouse remove feature-api --force  # force remove with uncommitted changes

Agent Coordination

# Create and lock for an agent
treehouse create feature-api --agent claude-1 --message "Working on API endpoints"

# Lock an existing worktree
treehouse lock feature-api --agent claude-2 --expiry 120

# Unlock a worktree
treehouse unlock feature-api

Completing Work

# Just mark as complete (no merge)
treehouse complete feature-api

# Merge into current branch
treehouse complete feature-api --merge

# Squash merge with custom message
treehouse complete feature-api --merge --squash --message "Add new API endpoints"

# Merge and delete branch
treehouse complete feature-api --merge --delete-branch

# Merge into specific branch
treehouse complete feature-api --merge --target main

Conflict Resolution

# Check for conflicts
treehouse conflicts
treehouse conflicts feature-api  # in specific worktree

# Resolve conflicts
treehouse resolve --ours         # keep current branch changes
treehouse resolve --theirs       # accept incoming changes
treehouse resolve feature-api --theirs

# Abort merge
treehouse abort
treehouse abort feature-api

Maintenance

# Prune orphaned worktree entries
treehouse prune

# Clean old worktrees (based on config)
treehouse clean --dry-run   # preview
treehouse clean             # actually remove

Configuration

Create treehouse.json in your repository root (or use .cursor/worktrees.json for Cursor compatibility):

{
  "dir": "../worktrees",
  "defaultTargetBranch": "current",
  "lockExpiryMinutes": 60,
  "setup-worktree": [
    "npm install",
    "cp \"$ROOT_WORKTREE_PATH/.env\" .env"
  ],
  "worktree.cleanup.enabled": true,
  "worktree.cleanup.retentionDays": 7,
  "worktree.cleanup.maxSizeGB": 10
}

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | dir | Directory for worktrees (relative or absolute) | ../worktrees | | defaultTargetBranch | Default branch for merges (current or branch name) | current | | lockExpiryMinutes | How long locks last before auto-expiring | 60 | | setup-worktree | Commands to run after creating a worktree | [] | | setup-worktree-unix | Unix-specific setup commands | - | | setup-worktree-windows | Windows-specific setup commands | - | | worktree.cleanup.enabled | Enable automatic cleanup | false | | worktree.cleanup.retentionDays | Remove worktrees older than N days | 7 | | worktree.cleanup.maxSizeGB | Max total size of worktrees | 0 (unlimited) |

Setup Commands

Setup commands support:

• Comments: Lines starting with # are skipped
• Environment Variables: ROOT_WORKTREE_PATH environment variable contains main repo path
• Script files: Point to external scripts instead of inline commands

Example using the environment variable:

{
  "setup-worktree": [
    "npm install",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

{
  "setup-worktree-unix": ".cursor/setup.sh",
  "setup-worktree-windows": ".cursor/setup.ps1"
}

MCP Integration

Treehouse includes an MCP server for integration with AI tools like Claude.

Setup

Add to your MCP configuration:

{
  "mcpServers": {
    "treehouse": {
      "command": "treehouse-mcp"
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "treehouse": {
      "command": "npx",
      "args": ["treehouse-worktree", "mcp"]
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | treehouse_init | Initialize configuration | | treehouse_list | List all worktrees | | treehouse_create | Create a new worktree | | treehouse_status | Get worktree status | | treehouse_complete | Complete work on a worktree | | treehouse_remove | Remove a worktree | | treehouse_lock | Lock a worktree for an agent | | treehouse_unlock | Unlock a worktree | | treehouse_conflicts | Check for merge conflicts | | treehouse_resolve | Resolve conflicts | | treehouse_abort | Abort a merge | | treehouse_prune | Prune orphaned entries | | treehouse_clean | Clean old worktrees |

Multi-Agent Workflow Example

# Agent 1 starts working on API
treehouse create api-work --agent agent-1 --message "Implementing REST endpoints"

# Agent 2 starts working on UI (different worktree)
treehouse create ui-work --agent agent-2 --message "Building dashboard components"

# Check what's being worked on
treehouse list

# Agent 1 finishes and merges
treehouse complete api-work --merge --delete-branch
treehouse remove api-work

# Agent 2 finishes
treehouse complete ui-work --merge
treehouse remove ui-work

Programmatic Usage

import { treehouse } from 'treehouse-worktree';

// Create a worktree
const result = await treehouse.create({
  name: 'feature-api',
  agentId: 'my-agent',
  lockMessage: 'Working on API'
});

// List worktrees
const list = await treehouse.list();

// Complete work
await treehouse.complete({
  name: 'feature-api',
  merge: true,
  deleteBranch: true
});

Config File Search Order

Treehouse looks for configuration in this order:

1. .cursor/worktrees.json in current worktree
2. treehouse.json in current worktree
3. .cursor/worktrees.json in repo root
4. treehouse.json in repo root

Requirements

• Node.js 18+
• Git 2.5+ (worktree support)

Troubleshooting

Common Issues

"Git is not available"

• Solution: Install git and ensure it's in your PATH
• Verify with: git --version
• Treehouse requires git 2.5 or higher

"Not in a git repository"

• Solution: Run git init first, or navigate to an existing git repository
• Check with: git status

"Worktree already exists"

• Solution: Choose a different name or remove the existing worktree first
• List worktrees with: treehouse list
• Remove with: treehouse remove <name>

"Worktree has uncommitted changes"

• Solution: Commit or stash changes before removing/completing the worktree
• Use --force flag to remove anyway (caution: will lose changes)

Setup commands fail on Windows

• Solution: Use platform-specific setup commands
• Set setup-worktree-windows in your config
• Ensure PowerShell or cmd commands are properly formatted

Lock expired but worktree still shows as locked

• Solution: Manually unlock with treehouse unlock <name>
• Locks auto-expire based on lockExpiryMinutes config

Metadata out of sync with actual worktrees

• Solution: Run treehouse prune to clean up orphaned entries
• This syncs metadata with actual git worktrees

Getting Help

• Check the GitHub Issues
• Read the Contributing Guide
• Review the Changelog for recent changes

License

MIT