wtx

Git worktree manager with a built-in MCP server. Create, inspect, and clean isolated workspaces from your terminal — or let your AI coding agents do it themselves.

Parallel AI coding agents made git stash-juggling obsolete — but raw git worktree add ../foo -b foo && cd ../foo && cp ../.env . is a chore nobody wants to repeat five times a day. wtx turns worktrees into a one-word workflow for humans and for agents:

$ wtx new fix-login
✔ created worktree fix-login
  path:   ~/code/myapp/.worktrees/fix-login
  branch: wt/fix-login (new)
  copied: .env, .env.local

Your agent gets the same power through MCP:

{ "name": "create_worktree", "arguments": { "name": "fix-login", "setup": "npm install" } }

Why wtx

• One tool, two interfaces. A fast CLI for you, an MCP server (wtx mcp) for Claude Code, Cursor, Codex, or any MCP-capable agent.

• Zero dependencies. Single Node.js binary that only shells out to git. Nothing to audit, nothing to break.

• Hygiene-aware. Every worktree shows its disk footprint and last activity. Reclaim gigabytes of stale node_modules clones with wtx clean --dry-run.

• Safe by default. Refuses to delete dirty worktrees, never touches the main checkout, deletes branches only when fully merged, and hides .worktrees/ via .git/info/exclude (no .gitignore pollution).

• Batteries included. Copies env files into new worktrees and runs your project's setup hook automatically.

Install

npm install -g wtx        # or: brew install wtx (planned)

Requires Node.js ≥ 18 and any modern git.

Quickstart

$ cd myapp
$ wtx new feat-search          # isolated workspace at .worktrees/feat-search on branch wt/feat-search
$ cd $(wtx path feat-search)   # jump in
$ wtx ls                       # see every workspace, its state and size
NAME       BRANCH         STATUS       AGE      SIZE     PATH
myapp*     main           ✓ clean      2d ago   412 MB   ~/code/myapp
feat-api   wt/feat-api    ● dirty (1)  3h ago   38 MB    ~/code/myapp/.worktrees/feat-api
$ wtx clean --dry-run          # preview reclaimable space
· feat-api (branch merged, 38 MB)
would free: 38 MB · kept 0 worktree(s)

Commands

Global flags: --json (machine-readable output), --base <ref>, --setup <cmd>, --no-copy, --no-setup.

Use it from AI agents (MCP)

Add to your MCP client config:

// e.g. claude_desktop_config.json / opencode.json / .mcp.json
{
  "mcpServers": {
    "wtx": { "command": "npx", "args": ["-y", "wtx", "mcp"] }
  }
}

The server exposes four tools: list_worktrees, create_worktree, remove_worktree, clean_worktrees. All accept an optional repo_path; otherwise the server's working directory is used. Responses are JSON, so agents can chain them: create → work → remove without ever switching branches in your main checkout.

Example agent prompt: "Set up a workspace called oauth-fix based on develop, run pnpm install in it, then tell me the path."

Configuration

Drop a wtx.config.json (or .wtxrc) in your repo root:

{
  "dir": ".worktrees",
  "copyFiles": [".env", ".env.local"],
  "setup": "pnpm install",
  "branchPrefix": "wt/"
}

Safety model

• The main worktree is never removed by rm or clean.

• Dirty worktrees are always preserved by clean, and rm requires --force.

• Branches are deleted only when fully merged into the default branch (origin/HEAD → main → master fallback).

• Worktree directories live under .worktrees/, excluded via .git/info/exclude so your .gitignore stays untouched.

• Names are sanitized; traversal like ../evil is rejected.

How it compares

Development

git clone https://github.com/willkhinz/wtx && cd wtx
npm install
npm test        # build + 32 integration/unit tests
node dist/src/cli.js help

Architecture: src/core.ts (engine), src/cli.ts (human UI), src/mcp.ts (agent UI). The MCP implementation is dependency-free newline-delimited JSON-RPC 2.0.

Roadmap

• wtx exec <name> -- <cmd> run commands across all worktrees

• tmux/iTerm session spawning per worktree

• Homebrew formula

• GitHub Action: comment PRs with per-worktree previews

License

MIT