Pastoralist is an audit trail for package manager overrides.

Overrides often start as real fixes: a CVE patch, a compatibility pin, a fork, or a temporary transitive dependency workaround. Months later, the override is still in package.json, but the reason is usually somewhere else.

Pastoralist keeps the package-manager instruction where it belongs and adds the missing review record: why the override exists, which packages still need it, which security provider found it, and when it can be removed.

Start with a read-only check:

npx pastoralist doctor

For first-run guidance across local use, agents, and CI:

npx pastoralist onboard

The onboarding output includes quick scripts and copy/paste prompts for agents. See the Onboarding guide for the same checklist in the docs.

Set up the Pastoralist agent skill in a repo:

npx pastoralist --init agent-skill

Set up local dev with selected skills and hooks:

npx -p pastoralist pastoralist-setup-local-dev --skills all --hooks git,postinstall

When you are ready to add it to the project:

npm install pastoralist --save-dev
npx pastoralist init
npx pastoralist

Optionally keep the appendix current after installs:

{
  "scripts": {
    "postinstall": "pastoralist"
  }
}

Pastoralist can add that hook for you:

npx pastoralist --setup-hook

Package managers already know how to force a version:

{
  "overrides": {
    "qs": "6.11.2"
  }
}

That may be exactly the right fix. The missing part is the operational record. Pastoralist adds one without moving the override:

{
  "overrides": {
    "qs": "6.11.2"
  },
  "pastoralist": {
    "appendix": {
      "[email protected]": {
        "dependents": {
          "express": "[email protected]"
        },
        "ledger": {
          "addedDate": "2026-05-30T00:00:00.000Z",
          "reason": "Pin qs while upstream dependencies adopt the patched version.",
          "source": "manual"
        }
      }
    }
  }
}

The override controls installation. The appendix explains the decision. When security checks run, the same ledger can include CVEs, severity, provider, and patched-version metadata.

• Tracks npm and Bun overrides, pnpm pnpm.overrides, and Yarn resolutions
• Records why an override was added and which packages still depend on it
• Connects security metadata such as CVEs, severity, provider, and patched version
• Links patch-package files to the override entries they support
• Reports stale overrides and removes them only when you pass --remove-unused
• Reads workspace manifests and writes one consolidated root appendix
• Provides dry-run, summary, quiet, and JSON output for CI

Pastoralist can use package.json, .pastoralistrc, .pastoralistrc.json, pastoralist.json, pastoralist.config.cjs, pastoralist.config.js, or pastoralist.config.mjs. External JSON config files use top-level settings; package.json keeps settings under pastoralist.

{
  "pastoralist": {
    "depPaths": "workspace",
    "checkSecurity": true,
    "security": {
      "provider": "osv",
      "severityThreshold": "medium",
      "hasWorkspaceSecurityChecks": true
    }
  }
}

See Configuration and Workspaces for the full setup surface.

Check override tracking on pull requests:

name: Override Check
on: [pull_request]

jobs:
  pastoralist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: yowainwright/pastoralist@v1
        with:
          mode: check
          check-security: false

The action can also run security checks, update files, or open scheduled maintenance PRs. See the GitHub Action docs.

Pastoralist can write to package.json, so the package should be boring to verify.

• Releases are published from GitHub Actions with npm provenance
• Published tarballs are packed before release and attached to GitHub Releases with artifact attestations
• CI runs CodeQL, OpenSSF Scorecard, unit, integration, e2e, and dependency policy checks

You can verify registry signatures from your project:

npm audit signatures

• Why Pastoralist
• Setup
• Onboarding
• Configuration
• Security
• Workspaces
• GitHub Action
• API Reference
• Architecture

Shout out to Bryant Cabrera and Mardin for the conversation, insight, and pairing around this topic.

Made by @yowainwright. MIT, 2022.