@henryqw/pi-deps

Start locked Node and uv dependency installs whenever Git creates a worktree for an opted-in repository. Developers using several worktree tools get one shared hook without adding work to every Pi startup.

Install

pi install npm:@henryqw/pi-deps

Use

Run /deps in a trusted repository to enable preparation. Create a worktree through Git so its post-checkout hook runs, then open Pi in TUI mode there to see quiet install progress. Run /deps again to disable future preparation.

• The shared post-checkout hook applies to every worktree in the repository; run /deps from any worktree to toggle it.
• Hooks without this package’s marker are never overwritten or removed.
• After updating the package, run /deps twice in each opted-in repository. This replaces the copied hook with the current version.

Flow

• Worktree creation returns without waiting for dependency installation when the hook runs.
• The hook validates lockfiles synchronously. Conflicting Node lockfiles, packageManager mismatches, and unsupported declarations still fail the worktree command fast.
• A detached installer runs frozen installs in the background.
• A Pi TUI session in the worktree watches for install progress without waiting for completion at startup. It shows a dim footer status such as ⠋ deps · installing 12s, clears it without a success message, and reports failures, including missing executables, that it observes during its ten-minute wait. RPC, JSON, and print sessions do not show or consume this status.

Node and uv both run when both lockfile types exist.

State and storage

The installer stores its result in <worktree gitdir>/pi-deps/status.json. Command output is in the adjacent install.log.

The status file is removed once a Pi TUI session reports it. Other tools that create worktrees get the same background install only when they invoke Git’s post-checkout hook; tools that do not run the hook, including those that create detached worktrees without a checkout, do not prepare dependencies. Non-Pi consumers must read the status file themselves.

Limits and recovery

Dependency installation may execute repository-controlled build and install scripts. Enable only repositories you trust.

• A configured core.hooksPath replaces the shared hooks directory. /deps refuses instead of installing where Git would ignore or share the hook.
• Only Git-root lockfiles are inspected.
• Root npm and uv workspaces remain package-manager concerns. Nested independent projects are not scanned.
• Already-present node_modules skips Node installs; .pnp.cjs skips Yarn installs only; .venv skips uv installs.
• Worktrees created with git worktree add --no-checkout never run post-checkout, so they are not prepared. git worktree add --detach with a checkout does run the hook.
• Installs finish after creation returns. A consumer may use a worktree before dependencies are ready.
• If status is still running after ten minutes, the TUI watcher removes it, clears the footer status, and shows an error with the log path. This stops watching, not the installer. Check the adjacent <worktree gitdir>/pi-deps/install.log for installer command output and any pi-deps: failure message; the log remains available when the status file is removed. Reopening Pi does not restore a status already removed by the watcher.
• Closing Pi stops its progress watcher and animation without cancelling the detached installer or consuming its pending result.

The root lockfile selects the manager and command below. A matching packageManager declaration selects the same command regardless of its declared version; versions are not checked against the installed executable. Explicit [email protected] declarations fail fast because Yarn Classic is unsupported. With only yarn.lock and no packageManager, the hook assumes modern Yarn and runs --immutable; if the executable is Yarn Classic, installation fails in the background.