@lanquarden/pi-dev-worktrees

A pi extension that provides isolated branch workspaces using git worktrees (via wtp) and optional devcontainer targeting.

Features

• Worktree isolation — create/switch/remove git worktrees per branch; all bash commands run inside the active worktree
• Devcontainer targeting — start, stop, rebuild, and route bash commands into the project's devcontainer
• File tool routing — read/write/edit with relative paths automatically route to the active worktree
• Composable — worktree + devcontainer combine: commands run in the container at the worktree path
• HOST: escape hatch — prefix any command with HOST: to bypass all routing
• Git/gh passthrough — git, gh, and find commands always run on the host
• External/Herdr mode — disable extension-owned worktrees while keeping cwd-rooted devcontainers
• Native TUI feedback — DEV, HOST, RTK, RTK fallback, managed CWD, and error chips without changing executable commands
• Local generated-artifact excludes — uses Git's resolved info/exclude; never modifies .gitignore

Install

pi install npm:@lanquarden/pi-dev-worktrees

Requirements

• git
• wtp v2+ (for worktree features)
• devcontainer CLI (for container features)

Configuration

~/.pi/agent/pi-dev-worktrees.config.json supports independent default-on capability flags; repos is optional:

{
  "worktrees": { "enabled": false },
  "devcontainer": { "enabled": true },
  "advisories": { "rtkLoadOrder": "once" }
}

With worktrees disabled, pi's exact session cwd is authoritative. No .wtp.yml, wtp invocation, worktree/file-path routing, managed-worktree dashboard UI, or worktree tool remains active. Devcontainer discovery, override/log generation, probes, labels, lifecycle calls, and exec routing all use that exact cwd, including non-Git directories. Config changes require /reload or a new session runtime.

Set devcontainer.enabled to false to disable all container side effects, routing, tool exposure, and feedback independently of worktrees.

advisories.rtkLoadOrder controls the pi-rtk-optimizer load-order startup info message: "once" (default) shows it only once per machine, "always" shows it every session, "off" suppresses it entirely. Once shown, the marker persists at ~/.pi/agent/pi-dev-worktrees.advisory-state.json; delete that file to see the advisory again. Conflict warnings (e.g. an incompatible spawnHook-based pi-rtk) are always emitted regardless of this setting.

Generated artifacts are excluded through git rev-parse --git-path info/exclude, including linked worktrees and external Git directories. .gitignore is preserved byte-for-byte.

Plain-pi status shows only container:starting or container:on. TUI bash rows preserve stock execution/results and add width-aware routing chips; external mode omits CWD.

Commands

| Command | Description | |---------|-------------| | /worktree [set] <branch> | Create or switch to a wtp-managed worktree | | /worktree off | Deactivate worktree routing | | /worktree status | Snapshot of all worktrees and container status | | /worktree remove <branch> | Remove a worktree | | /worktree prune | Clear stale worktree metadata | | /worktree init | Interactively create .wtp.yml | | /worktree hooks ... | Manage post-create hooks | | /devcontainer on | Start or reuse the devcontainer | | /devcontainer off | Disable container targeting (leaves container running) | | /devcontainer stop | Stop the container entirely | | /devcontainer rebuild | Rebuild the container image (--build-no-cache) | | /devcontainer logs | Tail the startup log |

When a capability is disabled, its LLM tool is removed. The corresponding slash command remains registered but is explanatory and non-mutating.

See the repo README for full documentation.

Dashboard Plugin

For pi-agent-dashboard integration, install @lanquarden/pi-dev-worktrees-dashboard-plugin.