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.

CI npm license

---

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

Command	Description
wtx new <name>	Create .worktrees/<name> on branch wt/<name>, copy env files, run setup hook
wtx ls	Table of worktrees: branch, ahead/behind, dirty state, last-commit age, disk usage
wtx rm <name> [--force]	Remove a worktree; refuses if dirty; deletes merged branches
wtx clean [--dry-run] [--stale-days <n>]	Remove worktrees whose branches are fully merged and/or inactive
wtx open [name]	Spawn $SHELL inside a worktree (--print to just echo the path)
wtx path [name]	Print a worktree's absolute path (shell-script friendly)
wtx mcp	Run as an MCP server over stdio

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/"
}

Key	Default	Meaning
dir	.worktrees	Where worktrees live, relative to repo root (auto-added to .git/info/exclude)
copyFiles	[".env", ".env.local"]	Files copied from the main checkout into each new worktree
setup	(none)	Shell command run inside a new worktree after creation
branchPrefix	wt/	Prefix for branches created by wtx new

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

	raw git worktree	TUI managers	wtx
One-command create + env copy + setup hook	✗	partial	✓
Disk usage & staleness per worktree	✗	rare	✓
Machine-readable --json everywhere	✗	✗	✓
MCP server for coding agents	✗	✗	✓
Zero runtime dependencies	n/a	✗ (usually heavy)	✓

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