Git Worktrees for ZCode

Jeder Thread bekommt seinen eigenen Worktree – automatisch. Git Worktrees gibt jedem neuen ZCode-Thread einen isolierten Checkout deines Repos, damit Aufgaben parallel laufen können – ohne Stashen, ohne ewiges Branch-Gewechsel und ohne dass sich Änderungen gegenseitig überschreiben. Starte einfach mit dem Chatten; du bist bereits isoliert.

/worktree:new fix-auth "Refactor the login flow"   ← worktree + background agent
/worktree                                          ← dashboard: branches, sizes, agents
/worktree:end fix-auth                             ← commit everything, remove cleanly

Warum du es willst

• Keine Einrichtung. Der Auto-Session-Modus (standardmäßig aktiviert) gibt jedem neuen Thread in dem Moment, in dem er startet, einen eigenen Worktree – und eine wiederaufgenommene Session führt zurück zu genau diesem. Keine Befehle nötig, jemals.

• Nie wieder Arbeit verlieren. Das Entfernen von dirty Worktrees, laufenden Agenten oder ungemergten Branches wird ohne force verweigert – und selbst dann werden uncommittete Änderungen zuerst gesichert (getrackter Diff plus untracked Dateien) in einem wiederherstellbaren Verzeichnis. Branches werden standardmäßig behalten.

• Deine Umgebung reist mit. .env und Verwandte (alles, was gitignored ist und in .worktreeinclude gelistet ist) werden in neue Worktrees übernommen; setupCommands (pnpm install, docker compose up -d) laufen automatisch.

• Es stört dich nicht. Worktrees liegen in einem zentralen Store (~/.zcode/worktrees), deine Repos bleiben makellos, und ein Retention-Sweep hält den Plattenverbrauch im Rahmen. Es wird nie etwas stillschweigend gelöscht.

Installation

1. Öffne in ZCode Desktop Einstellungen → Plugin-Verwaltung und klicke auf Marktplatz hinzufügen.

2. Übertrage das Repo – ein GitHub-owner/repo-Slug oder eine vollständige Git-URL, beides reicht:

agallardol/zcode-git-worktrees

3. Installiere Git Worktrees aus dem Katalog.

4. Öffne ein beliebiges Git-Repo und starte einen Thread – du bist bereits in verlassen Exploit. Tippe für das Dashboard /worktree ein.

Voraussetzungen: ZCode ≥ 3.8.1, node (≥ 3.0.1) im PATH, git.

Falls /worktree nicht erscheint: Führe in einem Terminal node --version aus (der MCP-Server benötigt node), stelle sicher, dass das Plugin unter „Installed“ aktiviert ist, und starte ZCode erneut, wenn du es bei geöffneter App installiert hast.

Related MCP server: hop-mcp

Die Befehle

Dahinter stehen neun MCP-Tools (worktrees_create, worktrees_list, worktrees_status, worktrees_remove, worktrees_cleanup, worktrees_prune, worktrees_snapshot, worktrees_set_task, worktrees_auto_session) sowie ein model-oriented Skill und Hooks – sodass der Workspace-Worktree auch von allein greift, wenn du nach paralleler oder isolierter Arbeit fragst.

Auto-Session-Worktrees (standardmäßig aktiviert)

Jede neue Session in einem Haupt-Checkout eines Repos erhält einen eigenen Worktree (zcode/sess-…); beim Fortsetzen geht wieder in denselben Worktree, und Editierung am Haupt-Checkout ist blockiert und wird in den Session-Worktree unt README. Man schaltet das um in Einstellungen → Plugins → Git Worktrees oder mit /worktree:auto (die letzte Änderung gewinnt). Ein Repo kann sich jederzeit gegen die Automatik entscheiden:

// .zcode/worktree.json in the repo
{ "autoSession": false }

Repo-seitige Konfiguration (optional)

.worktreeinclude – Muster im Gitignore-Stil; nur Dateien, die auch gitignored sind, werden in neue Worktrees übernommen (getrackte Dateien werden niemals dupliziert):

.env
config/secrets.json

.zcode/worktree.json – explizite Dateien, Lifecycle-Hooks und die Auto-Session-Verschriftung:

{
  "autoSession": true,
  "copyFiles": [".env.local"],
  "setupCommands": ["pnpm install"],
  "preRemoveCommands": ["docker compose down"]
}

Plugin-Einstellungen (Einstellungen → Plugins → Git Worktrees): Worktree-Root, Standard-Basis (fresh = origin/HEAD mit Offline-Fallback oder head), Behalte-Tage 14, maximale Worktrees pro Projekt (15).

Safety-Model

• Nichts entkommt dem Store. – Namen werden auf Pfad- und Git-Ref-Sicherheit geprüft (Traversal, .lock, Case-Twin, Unicode-Tricks werden verhindert), vollständige Pfade werden an denselben Symlinks geschützt, store paths canonicalized; ein erfolgloser git worktree add rollt den Branch zurück.

• Concurrency-fest: Mutationen sind über eine in-process Queue und zusätzlich eine Cross-process Lockfile serialisiert; paralleles Anlegen fleischwird nie zurückgerollt.

• Self-healing: korrupter Zustand wird quarantine and rebuildet, Worktrees werden wieder aus Git übernommen, out-of-band Deleting werden durch prune/cleanup reconcileert.

• Keine Ausführung aus untrusted repos: setupCommands / preRemoveCommands laufen nur auf Worktrees, die du ausdrücklich erstellst. Auto-Session erstellt niemals repo-eigene Commands: Öffnen eines Geklonten Repos ist keine Code-Laufzeit. Jeder Git-Call läuft über execFile; die einzige Shell-Ausführung sind Lifecycle-Befehle, für die du dich entschieden hast.

Verglichen mit den Tools, die dazu inspirierten: ein PR-Number-Checkout und die .worktreeinclude-Semantik stammen von Claude Code, Snapshot aus und der zentrale Store von Codex, Retention-Grenzen von Cursor/Codex – dazu geben-Orchestrierung in einem Background-Agenten und hart edit-isolation, die keinen von ihnen für Pluginsengebote.

Tests

npm test   # 129 tests: 80 unit (validators, state, carry-over, hooks, edit guard)
           #        + 13 integration (real MCP stdio JSON-RPC + protocol edges)
           #        + 36 adversarial & security (hostile names, races, corrupt
           #           state, out-of-band damage, exploit regressions)

CI runs the suite on macOS and Linux (Node 20 and 22).

Die Suites laufen vollständig auf lokalen test fixtures -- kein Netzwerk, keine Modell-Aud.

Hinweise &

• Die Auto-Session-Isolation ist soft für Commands, hart für Edits: Da die Write/Edit-Steuerung gegen den Haupt-Checkout blockiert wird durch einen PreToolUse-Guard; Bash wird per injected context bewerkger, nicht statistisch überwacht.

• ZCode hat kein Session-Ende-Event; daher wird nichts automatisch committet oder gelöscht. /worktree:end ist der explizite Endpunkt, und ein Retention-Sweep sammelt das, was dort erledigt ist.

• One-Session-Verzug für Auto-Session-Einstellungen (hooks read a marker, den der MCP-Server beim Session-Start synchronisiert).

Lizenz

MIT © Alfredo Gallardo