iTerm2 Worktree

Provides automated git worktree management with dynamic iTerm2 tab control via MCP for streamlined feature development.

python

12

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "timoconnellaus-claude-code-iterm-worktree-mcp": {
      "command": "python3",
      "args": [
        "path/to/worktree_mcp_server.py"
      ]
    }
  }
}

This MCP server automates git worktree management with seamless iTerm2 integration, enabling you to create, open, switch between, and safely close worktrees directly from your MCP client. It provides dynamic tab discovery, per-worktree isolation, and a streamlined workflow for feature development with terminal automation.

How to use

You interact with this MCP server through your MCP client to manage git worktrees and their corresponding iTerm2 tabs. Use the provided tools to create new worktrees, open existing ones in new iTerm2 tabs, switch focus to a worktree tab, and close worktrees once you have finished development. The server handles safety checks to ensure worktrees are clean and pushed before removal, and it can discover active tabs dynamically across windows.

How to install

Prerequisites: ensure you have Python 3 installed on your system and that the Claude MCP integration is available in your environment.

Run the MCP installation command to register the server with Claude Code integrating this worktree automation.

Additional notes

This MCP server supports core worktree operations, including creating a new worktree with a feature branch and opening it in an iTerm2 tab, safely closing worktrees after ensuring they are clean and pushed, and opening existing worktrees in new tabs with an optional force to override if they’re already open. You can discover active worktrees across windows, and switch between them by name or tab ID. Dynamic discovery means you don’t rely on metadata files to locate running tabs.

Security and reliability notes

Rely on built-in checks to ensure a worktree is clean and pushed before closing. When opening a worktree, you can enforce a force option to override if a tab already exists for that worktree. Tab discovery happens at runtime by inspecting the working directories of open iTerm2 tabs, reducing the need for static metadata.

Available tools

createWorktree

Create a new git worktree with a feature branch and open it in a new iTerm2 tab.

closeWorktree

Validate the worktree is clean and pushed, then safely close the worktree and clean up resources.

activeWorktrees

List all active worktrees and show which iTerm2 tabs they are running in.

switchToWorktree

Switch focus to a worktree's iTerm2 tab by name or tab ID.

openWorktree

Open an existing worktree in a new iTerm2 tab, with an option to force if already open.