Which integrations are available for this server?

Manages [git](/mcp/servers/integrations/git) worktrees for parallel workflows, providing tools for creating, listing, locking, merging, and cleaning up worktrees with agent coordination and conflict resolution capabilities.

treehouse-worktree 🌲

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

NPM Version License: MIT Node Version

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:

.cursor/worktrees.json in current worktree
treehouse.json in current worktree
.cursor/worktrees.json in repo root
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

Treehouse Worktree