---
title: "@henryqw/pi-deps"
seo:
  description: "Prepare Node and uv dependencies when opted-in Git worktrees are created."
---

<div class="not-prose my-6 flex flex-wrap items-center gap-3"><span class="text-sm text-muted-foreground">v0.3.8</span><a href="https://www.npmjs.com/package/@henryqw/pi-deps" aria-label="View @henryqw/pi-deps on npm"><img alt="Monthly npm downloads" height="20" src="https://img.shields.io/npm/dm/%40henryqw%2Fpi-deps?cacheSeconds=7200&amp;color=1d4ed8&amp;label=downloads&amp;labelColor=101828&amp;style=flat-square" width="144"></a></div>

Prepare locked Node and uv dependencies when Git creates a new worktree for an opted-in repository.

## Why

- **Created for**: Install locked dependencies whenever Git creates a new worktree in an opted-in repository.
- **Advantage**: Prepare each checkout regardless of which tool creates it. Do not pay install cost at every Pi startup.

## Install

```bash
pi install npm:@henryqw/pi-deps
```

Node 22.19 or newer, Git, and each selected package manager must be available on `PATH` used by Git.

## Use

Use `/deps` to toggle dependency preparation for future worktrees in the current repository.

### Enable, disable, and update

- Run `/deps` once from any worktree to enable preparation through the repository's shared `post-checkout` hook.
- Run `/deps` again to disable 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.
- A configured `core.hooksPath` replaces the shared hooks directory. `/deps` refuses instead of installing where Git would ignore or share the hook.

### What it prepares

- Only Git-root lockfiles are inspected.
- npm, pnpm, Yarn, and Bun use frozen installs. uv uses `uv sync --locked`.
- Node and uv both run when both lockfile types exist.
- Root npm and uv workspaces remain package-manager concerns. Nested independent projects are not scanned.

### Background install and status

- Worktree creation returns immediately.
- 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.
- Its result is stored in `<worktree gitdir>/pi-deps/status.json`. Command output is in the adjacent `install.log`.
- The status file is removed once a Pi session reports it.
- A Pi session in the worktree shows an editor widget while installing. It auto-dismisses success after five seconds and keeps failures visible, including missing executables.
- Other tools that create worktrees get the same background install. They must consume the status file themselves.

### Limits and safety

- Already-present `node_modules`, `.pnp.cjs`, or `.venv` are skipped.
- Worktrees created with `git worktree add --no-checkout` never run `post-checkout`, so they are not prepared.
- Installs finish after creation returns. A consumer may use a worktree before dependencies are ready.
- Dependency installation may execute repository-controlled build and install scripts. Enable only repositories you trust.

## Supported managers

Only current major versions are supported. Older majors are not handled and fall back to the lockfile default below.

| Manager | Command | Lockfile |
| --- | --- | --- |
| npm | `npm ci` | `package-lock.json`, `npm-shrinkwrap.json` |
| pnpm | `pnpm install --frozen-lockfile` | `pnpm-lock.yaml` |
| Yarn | `yarn install --immutable` | `yarn.lock` (Yarn Classic 1.x is not supported) |
| Bun | `bun install --frozen-lockfile` | `bun.lock`, `bun.lockb` |
| uv | `uv sync --locked` | `uv.lock` |