wtx

Git-Worktree-Manager mit integriertem MCP-Server. Erstelle, inspiziere und bereinige isolierte Arbeitsbereiche von deinem Terminal aus – oder lass deine KI-Coding-Agenten es selbst erledigen.

Parallele KI-Coding-Agenten haben das Jonglieren mit git stash überflüssig gemacht – aber das rohe git worktree add ../foo -b foo && cd ../foo && cp ../.env . ist eine lästige Aufgabe, die niemand fünfmal am Tag wiederholen möchte. wtx verwandelt Worktrees in einen Ein-Wort-Workflow für Menschen und für Agenten:

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

Dein Agent erhält dieselben Fähigkeiten über MCP:

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

Warum wtx

• Ein Tool, zwei Schnittstellen. Eine schnelle CLI für dich, einen MCP-Server (wtx mcp) für Claude Code, Cursor, Codex oder jeden MCP-fähigen Agenten.

• Null Abhängigkeiten. Eine einzige Node.js-Binärdatei, die ausschließlich git aufruft. Nichts zu prüfen, nichts, das kaputtgehen kann.

• Hygienebewusst. Jeder Worktree zeigt seinen Speicherbedarf und die letzte Aktivität. Mit wtx clean --dry-run holst du Gigabyte veralteter node_modules-Klonen zurück.

• Standardmäßig sicher. Weigert sich, dirty Worktrees zu löschen, fasst den Haupt-Checkout nie an, löscht Branches nur, wenn sie vollständig gemergt sind, und versteckt .worktrees/ über .git/info/exclude (keine .gitignore-Verschmutzung).

• Rundum-Sorglos-Paket. Kopiert Env-Dateien in neue Worktrees und führt den Setup-Hook deines Projekts automatisch aus.

Installation

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

Erfordert Node.js ≥ 18 und ein modernes git.

Schnellstart

$ 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)

Befehle

Globale Flags: --json (maschinenlesbare Ausgabe), --base <ref>, --setup <cmd>, --no-copy, --no-setup.

Von KI-Agenten verwenden (MCP)

Füge dies zu deiner MCP-Client-Konfiguration hinzu:

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

Der Server stellt vier Tools bereit: list_worktrees, create_worktree, remove_worktree, clean_worktrees. Alle akzeptieren ein optionales repo_path; andernfalls wird das Arbeitsverzeichnis des Servers verwendet. Die Antworten sind JSON, sodass Agenten sie verketten können: erstellen → arbeiten → entfernen – ohne jemals in deinem Haupt-Checkout die Branches zu wechseln.

Beispiel-Agenten-Prompt: "Richte einen Arbeitsbereich namens oauth-fix auf Basis von develop ein, führe darin pnpm install aus und nenne mir dann den Pfad."

Konfiguration

Lege eine wtx.config.json (oder .wtxrc) in deinem Repository-Root ab:

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

Sicherheitsmodell

• Das Haupt-Worktree wird von rm oder clean niemals entfernt.

• Dirty-Worktrees werden von clean immer belassen, und rm verlangt --force.

• Branches werden nur bei vollständigem Merge in den Standard-Branch gelöscht (Fallback: origin/HEAD → main → master).

• Worktree-Verzeichnisse liegen unter .worktrees/ und werden über .git/info/exclude ausgeschlossen– so bleibt deine .gitignore unberührt.

• Namen werden bereinigt; Traversal wie ../evil wird abgewiesen.

Im Vergleich

Entwicklung

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

Architektur: src/core.ts (Engine), src/cli.ts (UI für Menschen), src/mcp.ts (UI für Agenten). Die MCP-Implementierung ist ein abhängigkeitsfreies JSON-RPC 2.0 mit zeilenweise begrenzten Nachrichten (newline-delimited).

Roadmap

• wtx exec <name> -- <cmd> – Befehle über alle Worktrees ausführen

• tmux-/iTerm-Sitzungen pro Worktree starten

• Homebrew-Formel

• GitHub Action: PRs mit Vorschauen pro Worktree kommentieren

License

MIT