# pinright: full documentation for agents
Version-accurate docs and a dependency check for coding agents. This file concatenates the README and the main
docs of https://github.com/Hiper-AI/pinright (MIT, by Hiper AI). Short version: https://pinright.dev/llms.txt
---
# README
**Version-accurate docs and a dependency check for coding agents.** Your agent gets library
versions from one of two places: its memory, where about 40% of the pins it wrote in our benchmark
carried a known advisory, or a docs MCP server, which returns documentation and does not check the
version against advisories. pinright gives it the docs for the exact version it installs and a
verdict on every dependency it adds, before the install runs. MCP server, pre-install hook, CLI and
GitHub Action, all local.
[](https://www.npmjs.com/package/pinright)
[](https://github.com/Hiper-AI/pinright/actions/workflows/ci.yml)
[](https://github.com/Hiper-AI/pinright/blob/main/LICENSE)
[](https://cursor.com/en/install-mcp?name=pinright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBpbnJpZ2h0Il19)
[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pinright%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522pinright%2522%255D%257D)
## Install
Node 20.9 or newer. One line, then restart the agent:
```bash
npm i -g pinright && pinright init --user # just you, every project; the hook starts in about 0.2 s
npx -y pinright init # your team: writes project files you commit
```
`init` wires the MCP server, the pre-install hook where the client has one, and a starter
`.pinright.json`. 16 clients; six have a hook: Claude Code, Cursor, VS Code (GitHub Copilot),
OpenAI Codex, Gemini CLI and Windsurf. The Cursor and VS Code buttons above add the MCP server
only. [Every client, scopes and `pinright doctor`](https://github.com/Hiper-AI/pinright/blob/main/docs/install.md).
## Without pinright, with pinright
**Without.** The agent runs `npm install lodash@4.17.20`. It installs. The lockfile now carries
five advisories, two of them high, and nobody is told.
**With.** The hook answers before the command runs, and the agent reads this:
```
pinright blocked this dependency change:
- lodash@4.17.20 (npm) has 5 known advisories (CVE-2021-23337, CVE-2026-4800, CVE-2020-28500, HIGH). Use 4.x release 4.18.1: npm install lodash@4.18.1
Change the version (or the name) and try again. check-package and get-docs from the pinright MCP server explain each case.
```
The agent retries with `4.18.1`, on the same release line. When it asks first, `check-package`
and `get-docs` give it the same verdict with the full advisory list, the version to pin, and the
docs for that version. Real output of `pinright hook claude`, 2026-11-01.
## Why pinright
Docs MCP servers return documentation for a library. They do not check the version the agent pins,
and they do not see the install. To measure that kind of server we ran pinright's own server with its
security layer off (`PINRIGHT_ABLATION=docs-only`): docs for the version asked, no verdict. It is not
another product. Claude Code with Sonnet 5.5, Haiku 5.5 and Opus 5.5, 2 runs per cell, on the 1.0.0
code; each cell gives the range over the three models.
| | No docs | Docs-only context server | pinright |
|---|---|---|---|
| Direct dependencies pinned with a known advisory | 40% to 42% | 0% to 2% | 0% |
| Whole-tree alerts per project (`npm audit`, `pip-audit`) | 29.8 to 31.9 | 0.3 to 3.5 | 0.3 |
| Docs tasks that used the current API | 9 to 14 of 16 | 15 or 16 of 16 | 16 of 16 |
| Tokens per agent task | 15k to 21k | 56k to 94k | 42k to 74k |
| Tokens per docs task | 17k to 23k | 94k to 135k | 63k to 95k |
| Agent turns per agent task | 4.0 to 4.3 | 9.3 to 11.1 | 5.9 to 7.5 |
| MCP tool text read per agent task | none | 25k to 45k characters | 5k to 17k characters |
| Verdict on the version the agent pins | no | no | advisories, malware, lookalikes, versions that do not exist |
| Check when the install runs | no | no | pre-install hook in 6 clients |
| Whole-tree lockfile audit | no | no | `check-manifest`, SARIF, GitHub Action |
Current docs alone removed most alerts; the verdict removed the rest. Per model, pinright used 21% to
26% fewer tokens than the docs-only server on the 12 agent tasks and 26% to 33% fewer on the 8 docs
tasks. Every paired interval stays above zero; the lowest bound is 2%. Tokens count everything the
model processed, cache reads included. No tools at all costs less than either.
**Why fewer tokens.** With docs only, the agent looked versions up through the docs: it called
`get-docs` once per package, 5.2 to 5.7 times per agent task, before writing a file. 87% of those calls
named no version, so they returned the docs of the latest release, and 75% asked for "version" or
"latest" in the query. With pinright, every agent-task run opened with `check-packages` for the whole
list, about 600 characters of verdicts and versions to pin, then called `get-docs` 0.7 to 1.7 times per
task, with a version in 86 of 87 calls.
**Limits.** The 0.3 left is nuxt, whose current release pulls packages with no fix published;
installing with no version gets the same 0.3, and the docs-only and pinright alert intervals overlap.
One vendor's models, tasks we wrote, no shell, two days of advisory data, small n. In a second run
with a shell, the agents looked versions up with `npm view` or `pip index` before pinning, and every
arm ended at the same 6 alerts per model: there pinright made no measurable difference to the pins.
On APIs released after August 2026, 2 of 48 runs got the current API without docs, 45 of 48 with docs
only and 46 of 48 with pinright. On 12 tasks taken from public GitHub issues, 25% to 29% of direct
pins carried an advisory without docs and none with pinright. The hook blocked or asked on 1.46% of 25,077 public commands and
misread 10 of 154,402 tool calls from a month of our own agent sessions.
[Per-model tables](https://github.com/Hiper-AI/pinright/blob/main/docs/benchmark.md#efficiency-tokens-turns-and-cost-against-a-docs-only-server) ·
[results and caveats](https://github.com/Hiper-AI/pinright/blob/main/bench/RESULTS-v7.md) ·
[technical report](https://github.com/Hiper-AI/pinright/blob/main/paper/kit/pinright-report.md) ·
[reproduce it](https://github.com/Hiper-AI/pinright/blob/main/bench/RESULTS-v7.md#reproduce)
## Ask your agent
- "Add zod and pin a version with no known advisories."
- "Show me the docs for the version of next this project has installed."
- "Audit package-lock.json and tell me what to upgrade, on the same release lines."
- "What changed between express 4 and 5 before I move?"
## Tools
| Tool | What it does |
|---|---|
| `check-packages` | The verdict for up to 50 packages in one call: version to pin, short reason, full notice only where it matters |
| `check-package` | One package in depth: advisories with CVE and fix, deprecation, license, lookalike names, policy violations |
| `get-docs` | Docs from the published package and its repo at the release tag, for the version you name or the one installed |
| `find-library` | Library name to registry package (`next.js` to `npm:next`), with the safe version |
| `upgrade-guide` | What changes between two versions: breaking changes, renamed APIs, advisories the move fixes |
| `check-manifest` | Whole-tree audit of a lockfile or manifest, with SARIF; the GitHub Action runs it in CI |
Ecosystems: npm, PyPI, Cargo, Go, Maven and Gradle, NuGet, RubyGems, Composer, GitHub Actions.
Verdicts never say `ok` when a source did not answer. A committed `.pinright.json` sets allow and
deny lists, license rules, severity threshold and what to do when a source is down.
[How it works](https://github.com/Hiper-AI/pinright/blob/main/docs/how-it-works.md) ·
[the hook](https://github.com/Hiper-AI/pinright/blob/main/docs/hook.md) ·
[team policy](https://github.com/Hiper-AI/pinright/blob/main/docs/policy.md) ·
[CLI](https://github.com/Hiper-AI/pinright/blob/main/docs/cli.md) ·
[GitHub Action](https://github.com/Hiper-AI/pinright/blob/main/docs/action.md)
## Privacy and limits
No account, no telemetry. pinright sends package names and versions to deps.dev, OSV, the
registries, jsDelivr and GitHub, never your code;
[SECURITY.md](https://github.com/Hiper-AI/pinright/blob/main/SECURITY.md#what-it-sends-over-the-network-and-to-whom)
lists each host. The hook reads commands and files statically: it is a guardrail, not a sandbox,
and the [threat model](https://github.com/Hiper-AI/pinright/blob/main/docs/HOOK-THREAT-MODEL.md)
lists what gets past it. When a source is down the built-in default lets the install through;
the starter policy asks instead.
## More
[Install](https://github.com/Hiper-AI/pinright/blob/main/docs/install.md) ·
[prompt injection](https://github.com/Hiper-AI/pinright/blob/main/docs/prompt-injection.md) ·
[benchmark](https://github.com/Hiper-AI/pinright/blob/main/docs/benchmark.md) ·
[security review](https://github.com/Hiper-AI/pinright/blob/main/docs/SECURITY-REVIEW.md) ·
[changelog](https://github.com/Hiper-AI/pinright/blob/main/CHANGELOG.md) ·
[contributing](https://github.com/Hiper-AI/pinright/blob/main/CONTRIBUTING.md) ·
[release runbook](https://github.com/Hiper-AI/pinright/blob/main/docs/RELEASE.md)
The report we value most is a false positive: a command the hook blocked, or a package it
flagged, that should have passed. Open an issue with the template and paste the command and the
output of `npx pinright doctor --json`. Report a vulnerability in pinright privately, as
[SECURITY.md](https://github.com/Hiper-AI/pinright/blob/main/SECURITY.md) describes.
MIT. Built by [Hiper AI](https://hiperai.com) ([opensource@hiperai.com](mailto:opensource@hiperai.com)).
Site: [pinright.dev](https://pinright.dev). Everyone taking part follows the
[Code of Conduct](https://github.com/Hiper-AI/pinright/blob/main/CODE_OF_CONDUCT.md).
---
# How it works
pinright runs on your machine. It asks public registries and advisory databases about each package, and nothing else:
```
agent --MCP--> pinright --> registry + jsDelivr package files at the exact version (npm)
--> PyPI files wheel/sdist at the exact version (Python API)
--> jsDelivr (GitHub) repo docs at the release tag (GitHub API past 50 MB)
--> project site llms.txt / llms-full.txt
--> api.deps.dev versions, advisories, licenses, dependency graphs
--> api.osv.dev CVE details, fixed versions, malware (MAL-*)
--> packagist.org Composer versions and advisories
--> github.com (git) commits and tags behind GitHub Actions refs
```
[SECURITY.md](https://github.com/Hiper-AI/pinright/blob/main/SECURITY.md#what-it-sends-over-the-network-and-to-whom) lists each service and what it receives.
## What the agent sees
Docs for a version with known holes come back with the notice first, and for the version to move to:
```
get-docs { libraryId: "npm:next@15.1.0", query: "protect routes with middleware" }
SECURITY NOTICE: next (npm)@15.1.0 has 36 known advisories.
- GHSA-f82v-jwr5-mffw (CVE-2025-29927) [CRITICAL]: Authorization Bypass in Next.js Middleware fixed in 13.5.9, 14.2.25, 15.2.3
- ...
Recommended within 15.x: 15.5.28 (same release line, no API break expected). Upgrade: npm install next@15.5.28
Newest safe overall: 16.4.3 (a different major: read its migration guide before switching).
These docs are for 15.5.28, the version to move to, not 15.1.0.
Docs for next@15.5.28 (npm), 5 sections, all from the published package or the repo at its release tag.
### How to implement authentication in Next.js > Authorization > Optimistic checks with Middleware (Optional) [...]
...
```
Text from the package (docs, changelogs, release notes) always arrives inside an `untrusted-data` block
that names its source. See [Prompt injection](https://github.com/Hiper-AI/pinright/blob/main/docs/prompt-injection.md).
The hook, when the agent writes a manifest or runs an install:
```
pinright blocked this dependency change:
- jsonwebtoken@8.5.1 (npm) has 3 known advisories (CVE-2022-23539, ...). No clean release on this line;
the fix needs a new major, 9.0.3: npm install jsonwebtoken@9.0.3
- starlette==0.38.6 (pypi) has 7 known advisories (...). It comes in through fastapi: upgrade fastapi to
0.162.0 (new major), which pulls starlette 1.10.0 with no known advisories, and pin starlette to that
version or drop the pin.
- express@4.21.2 (npm) pulls dependencies with known advisories (path-to-regexp@0.1.12, qs@6.13.0).
npm install express@4.22.3 pulls fixed versions on the same release line.
```
## Tools
| Tool | What it does |
|---|---|
| `find-library` | Library name to registry package (`next.js` to `npm:next`, `pytorch` to `pypi:torch`), ranked by repo stars, with the safe version and a verdict. Hits the project already depends on carry `installedVersion` and `installedIn`. Suggests the real name for a misspelled one. |
| `get-docs` | Sections that answer the question, from the package at a given version. Without a version it documents the one installed in the project, or the safe one when the project does not use the package; with a vulnerable one it documents the same-line fix. GitHub repo ids (`/vercel/next.js`) work too. |
| `upgrade-guide` | What changes between two versions: breaking changes, removed or renamed APIs, config and default changes, packages that split off, deprecations, and the advisories the move fixes. Without `to` it targets the recommended version. |
| `check-packages` | The verdict for up to 50 packages in one call: one table row each (verdict, version to pin, short reason), and the full notice only for the ones that need attention. The cheap way to vet a dependency list. |
| `check-package` | The verdict for one package: advisories with CVE, severity and fixed versions, deprecation, license, safe version on the same line and overall, typosquat lookalikes, and team policy violations. Without a version it checks the installed one. |
| `check-manifest` | Whole-tree audit of `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements*.txt`, `poetry.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `go.mod`, `Gemfile.lock`, `packages.lock.json`, or a bare `package.json` / `pyproject.toml` / `Cargo.toml` resolved through deps.dev. Also Maven, Gradle, Composer and GitHub Actions files (see [Ecosystems](#ecosystems)). Each finding comes with its chain and fix. |
Verdicts: `ok`, `vulnerable`, `malicious`, `deprecated`, `possible-typosquat`, `unknown-package`,
`unknown`. `unknown` means a data source did not answer; pinright never says `ok` when it could not check.
deps.dev indexes new releases and new packages with a delay of hours. Before any tool calls a package
or version missing, pinright asks the registry (npm, PyPI, crates.io, RubyGems). If the registry
publishes it, the answer is unverified, not missing: `check-package` and the hook give `unknown` and say
deps.dev has no data for it yet, `check-packages` marks the row UNVERIFIED (or adds that note to a row
whose osv.dev advisories make it vulnerable or malware), and `check-manifest` keeps an exact pin of a
manifest in the tree, so osv.dev still checks it, with a note that its dependencies, licenses,
deprecation status and risk signals were not checked. A range on a package deps.dev has never seen
cannot be resolved, so `check-manifest` notes it as unverified and not audited. In `pinright audit` and
the GitHub Action these entries are a `pinright/not-indexed` finding: a note for a fresh version, a
warning for a package deps.dev has never seen, and never a failure on their own.
## How the safe version is chosen
The newest version that is stable (no `rc`, `beta`, `canary`, Go pseudo-versions), not deprecated,
has no advisory in deps.dev (which mirrors OSV and the GitHub Advisory Database), and was published at
least 3 days ago. The cooldown exists because compromised releases are usually pulled within days.
When the project already uses a version, pinright also gives the newest clean version on its release
line (`3.x`, or `0.28.x` before 1.0, where minors break), and says so when only a new major is clean.
In that case it first tries the lines between the project's and the newest one, oldest first: a
Spring 5.3 project is pointed at 6.2.19, still maintained, and not at 7.0, because the jump is
smaller. The order is the same everywhere (notice, hook, `check-packages`, audit fixes, upgrade
guide): same line, then the nearest newer line with a clean release, then the newest clean one.
In a manifest, the hook and `check-manifest` also check that version against the ranges the other
dependencies set on the package: requirements anywhere in the resolved graphs for pip and Composer,
which install one version per name, and, in the hook, peer ranges for npm. When the fix falls outside one, they name
the package that sets the range (`moviepy` 2.2.1, via `stirrup` 0.2.1, requires `pillow<12.0`) and
recommend the newest clean release inside it. If none is clean, they give the least exposed one in
range and say whether a newer release of that package accepts the fix. Graph ranges add no requests;
a conflict adds a version list, one OSV batch, and one version list and graph lookup for the package
that sets the range, all cached. Peer ranges are read only when the fix crosses a major, one lookup per
declared npm package, up to 20. A lockfile without the graph keeps the plain recommendation.
`check-packages` treats the list it is given as a project of its own. With two or more packages of one
ecosystem in the call, it checks each "use" version against the ranges the others set on it, with the
same rules: the resolved graphs of the other packages, at the version each will be pinned at, for pip
and Composer (one cached graph lookup per package, up to 20), and npm peer ranges when the version
recommended leaves the release line asked for. With `stirrup`, `moviepy` and `pillow` 11.3.0 in one
call, the pillow row no longer says 13.0.0: it names `moviepy`'s `pillow<12.0` and gives the newest clean
release in range as the version to use, or "-" and the options in the details when none is clean. A
version asked for that another package in the call excludes gets a note. These lookups share the call's
deadline (`PINRIGHT_BATCH_TIMEOUT_MS`); if they fail or run late, the table is the one it was without
them. A single package, or one call per package, has no such context.
When the recommended version belongs to a major less than a year old, the notice says so and points
the agent to that version's docs: its configuration may differ from what the model learned.
A version counts as clean only when both deps.dev and OSV agree; OSV publishes new advisories hours
before deps.dev mirrors them.
## Supply-chain signals
OSV marks a malicious release (`MAL-*`) days after the attack. The release's behavior shows earlier, so
for the version you would install (the one you pass, or the latest), pinright also reports a `risk`
section with signals at three levels: `info`, `warn` and `high`.
| Signal | Source | Level |
|---|---|---|
| Install scripts (`preinstall`, `install`, `postinstall`, implicit `node-gyp`) | npm version document | `info`; `warn` when the previous releases had none; `high` when the package is brand new, or when the scripts arrive with a new publisher |
| Provenance dropped: earlier releases had an npm provenance attestation, this one has none | npm version document | `warn`, `high` with a new publisher |
| Publisher change: the account that published this recent release published none of the previous ones | npm `_npmUser` | `warn`; `info` when that account was already a maintainer or the release has provenance |
| Young package, with weekly downloads | deps.dev first publish date, npm downloads API, pypistats.org | `warn` when young and under the download threshold, `info` otherwise |
| OpenSSF Scorecard below the threshold, or a dangerous workflow, with the notable failing checks | deps.dev project | `info` only |
| The package's own text gives AI agents instructions: deprecation message, npm description, or docs and changelogs that pinright served earlier for the same version (see [Prompt injection](https://github.com/Hiper-AI/pinright/blob/main/docs/prompt-injection.md)) | deps.dev, npm version document, pinright's cache | `warn` (the hook passes it on and never blocks on it) |
Install scripts, provenance and publisher come from npm only; Scorecard and age cover every ecosystem
deps.dev knows, and downloads cover npm and PyPI. npm download counts for unscoped packages go out in bulk requests of up to 128 names, so a
large manifest stays under api.npmjs.org's rate limit; scoped packages, which the bulk endpoint
rejects, go three at a time. pinright reads the version documents of the requested
release and up to 5 earlier ones (a few KB each), never the full packument. Missing data produces no
signal, and the notice lists sources that did not answer under "Not verified". Signals never change
the verdict.
| Variable | Default | Meaning |
|---|---|---|
| `PINRIGHT_RISK_NEW_PACKAGE_DAYS` | `14` | A package younger than this with install scripts is `high` (blocked by the hook). |
| `PINRIGHT_RISK_RECENT_DAYS` | `30` | Window for "young package" and for flagging a publisher change. |
| `PINRIGHT_RISK_LOW_DOWNLOADS` | `100` | Weekly downloads under this, on a young package, is a `warn`. |
| `PINRIGHT_RISK_SCORECARD_LOW` | `4` | Scorecard under this is noted. |
| `PINRIGHT_RISK_HISTORY` | `5` | Earlier releases compared for scripts, provenance and publisher. |
Typosquat lookalikes are checked against about 3,600 npm and 3,000 PyPI names, regenerated by
`npx tsx scripts/popular.ts` from pinned public rankings (see the header of `src/data/popular.ts`).
## Where the docs come from
1. The published package at the exact version, through jsDelivr: README, bundled docs, and the
`.d.ts` type definitions, which are the ground truth of an npm package's API.
For PyPI, the wheel (or sdist) of that version, read as text and never imported: signatures and
docstrings of public functions, classes and methods (`__all__` respected; private modules,
tests and vendored code skipped), `.pyi` stubs, and the typeshed `types-` package for
signatures when the distribution ships no types. The answer also names the import name when it
differs from the package name (`yaml` for `pyyaml`).
2. The source repository at the release tag (`v1.2.3`, `1.2.3`, `name@1.2.3`, `name==1.2.3`...):
`docs/` folders (including Django's reStructuredText `.txt` pages), guides, migration notes.
pinright skips translations, notes for contributors and coding agents (`AGENTS.md`,
`.agents/skills`, `docs/plans`), eval prompts, example apps and copies of an older major the
package still ships (Zod 4's `v3/`). When a page pulls its example from another file
(`{* docs_src/x.py *}`, `--8<--`, `literalinclude`, `<<<`, or an mkdocs macro such as Polars'
`{{code_block('user-guide/x', 'section')}}`), the answer shows that file, cut to the named
snippet section. Generated SDK types (files headed "generated from our OpenAPI spec") rank
below the README and guides unless the question asks for a signature or a type.
3. The project's `llms-full.txt` or `llms.txt`, which describe the current site and may be newer
than the version you use; sections from it are labeled as such. The site comes from the
package's metadata: the registry's homepage or docs URL, the homepage its GitHub repo declares
(supabase.com for `@supabase/supabase-js`), or the docs link of its README (platform.claude.com
for the Claude SDKs). pinright looks for the llms.txt in the site's folder, at `docs.` and
under `/docs`. A site without one is read from the GitHub repo it is built from, at its default
branch: `/docs`, `/-docs`, `/.dev`, `/` or the docs
folder of the org's monorepo, only when GitHub lists that repo's homepage as the same site
(Astro's docs come from `withastro/docs` this way). Every URL taken from metadata goes through the
same SSRF guard as llms.txt. Packages whose docs cannot be found that way (LangChain, LangGraph,
PyYAML, Streamlit, Selenium) are mapped in `src/data/docsRepos.ts`, and so is Tailwind CSS,
whose site repo is found but whose 200 utility pages need a hand-picked set of guides. For
LangChain's split packages, the answer lists the sibling packages the question needs that are
not dependencies (`langchain-text-splitters`, `langchain-community`).
pinright does not call any docs index: everything comes from the sources above, with no account
or key. A GitHub repo id (`/vercel/next.js`) also works and is mapped to the package.
Sections are ranked locally with BM25 against the question, and the answer is capped at about
2,500 tokens (`tokens` argument, or `PINRIGHT_DOCS_BUDGET` in characters). A question that asks
several things at once ("z.email, z.strictObject, z.record") gets the best section for each topic.
API names written as code (`z.record`, `field_validator`, `pattern=`) must match exactly.
If the question uses a name that the version renamed, pinright searches for the new name too and the
answer says so (`system` -> `instructions` in AI SDK 7, `on_event` -> `lifespan` in FastAPI). It reads
the renames from the package itself: `@deprecated` tags in its type definitions, deprecation
decorators and docstrings in its Python API, and the migration guide of its current major.
## Upgrade guides
When pinright recommends a new major, the agent tends to write code and config for the old API from
memory: a `tsconfig.json` without `rootDir` for TypeScript 6+, `middleware.ts` for Next.js 16 where
the file is now `proxy.ts`, an import from `langchain` for text splitters that moved to
`langchain-text-splitters`. `upgrade-guide` gives the agent the changes between the two versions
before it writes anything, and you can run it by hand to fix a Dependabot PR:
```
upgrade-guide { libraryId: "npm:next", from: "15.5.28", to: "16.4.3", query: "middleware" }
npx pinright upgrade npm next 15.5.28 16.4.3 --query="middleware"
npx pinright upgrade pypi pydantic 1.10.x 2.x # ranges resolve to their newest release
```
pinright recommends the clean release on your line first. Sometimes that release is clean while its
own dependencies are not: next 15.5.28 pins a postcss with advisories that only next 16 clears.
`check-package`, `check-packages` and the hook then add a note and keep the recommendation (npm,
PyPI, Cargo, Maven and Composer, where pinright has resolved graphs):
```
NOTE: next 15.5.28 has no advisories itself, but pulls postcss@8.4.31 (GHSA-6g55-p6wh-862q, ...); next 16.4.3 pulls a fixed one. Staying on 15.x keeps that alert; upgrade-guide from 15.5.28 to 16.4.3 explains the changes.
```
It reads, all at the target version and cached:
1. `CHANGELOG`, `HISTORY`, `CHANGES` and `RELEASES` files from the published package and from the repo
at the release tag, keeping only the sections for versions after `from` up to `to`;
2. GitHub release notes for the tags in that range, and the announcement post when a release body only
links to one (TypeScript's);
3. migration guides when the move crosses a major: files and `llms.txt` pages named after migrating or
upgrading to that major;
4. for npm, a diff of the exported API in the `.d.ts` files of both versions: removed exports, changed
signatures, removed members.
Entries come back tagged `BREAKING`, `CONFIG/DEFAULT`, `NEW PACKAGE` or `DEPRECATED`, each with its
version and source. The answer opens with the advisories the move fixes and any that remain at `to`.
It fits the same budget as `get-docs` (`tokens` argument). Without a `GITHUB_TOKEN` it reads fewer
release pages.
## Project detection
Agents rarely say which version the project uses, and docs for a newer version produce code against
APIs the project does not have. pinright reads the project's dependency files by itself:
- **Where.** The roots the MCP client announces (and re-reads them on `roots/list_changed`). Without
them, `PINRIGHT_PROJECT_DIR` (several directories separated by the OS path delimiter), else the working
directory: Claude Code and Cursor launch stdio servers inside the project. When that directory has
no dependency files, the nearest parent that has them, up to the repository root (a monorepo
subfolder uses the monorepo's lockfile). Two parents are never adopted: one whose `.gitignore` files
ignore the folder or a folder between them (scratch space, generated output, run folders: not part of
that project), and the home directory, unless the agent works in it directly. Subprojects up to
three levels down count too (monorepos), skipping `node_modules`, build output and hidden folders.
- **What.** One file per ecosystem and directory, lockfile first: the exact version from the lockfile;
for npm without a lockfile, the version in `node_modules`; an exact pin in a manifest; else the
version the manifest's range resolves to today, and the answer says so.
- **How it is used.** `get-docs` and `check-package` without a version use the installed one and say
so in one line, then apply the same checks as for an explicit version: a vulnerable installed
version gets the same-line fix and docs for it. An explicit version always wins.
```
get-docs { libraryId: "npm:next", query: "middleware" }
Using next 15.1.0, installed in this project (package-lock.json).
SECURITY NOTICE: next (npm)@15.1.0 has 36 known advisories.
...
These docs are for 15.5.28, the version to move to, not 15.1.0.
```
When a monorepo has several versions of the package, the line lists the others. pinright reads only
dependency files, keeps them parsed in memory and re-reads one when its modification time changes.
## Ecosystems
| Ecosystem | Hook: commands | Hook: file writes | `check-manifest` / `audit` | Versions and advisories |
|---|---|---|---|---|
| npm | `npm`/`pnpm`/`yarn`/`bun`, `npx`, `pnpm dlx` | `package.json` | `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `package.json` | deps.dev + OSV |
| PyPI | `pip`, `uv`, `uvx`, `pipx`, `poetry`, `pdm` | `requirements*.txt`, `pyproject.toml` | `requirements*.txt`, `poetry.lock`, `uv.lock`, `pdm.lock`, `pyproject.toml` | deps.dev + OSV |
| Cargo | `cargo add\|install` | `Cargo.toml` | `Cargo.lock`, `Cargo.toml` | deps.dev + OSV |
| Go | `go get\|install` | `go.mod` | `go.mod` | deps.dev + OSV (no graphs) |
| RubyGems | `gem install`, `bundle add` | | `Gemfile.lock` | deps.dev + OSV (no graphs) |
| NuGet | `dotnet add package` | | `packages.lock.json` | deps.dev + OSV (no graphs) |
| Maven / Gradle | | `pom.xml`, `build.gradle`, `build.gradle.kts`, `gradle/libs.versions.toml` | `gradle.lockfile`, or the build files resolved through deps.dev | deps.dev + OSV |
| Composer | `composer require`, `create-project` | `composer.json` | `composer.lock`, `composer.json` | Packagist + OSV + Packagist advisories |
| GitHub Actions | | `.github/workflows/*.yml`, `action.yml` | a workflow, `action.yml`, `.github/workflows`, or the project root | OSV + GitHub API |
**Maven and Gradle.** In `pom.xml`, `${...}` versions resolve from `` and `project.version`
in the same file. In Gradle scripts, pinright reads `"g:a:v"` and map notation, `$var` from simple
assignments and `gradle.properties`, and `libs.*` references to the version catalog. A dependency
without a version (managed by a parent POM, a BOM or a platform) or with a computed one is skipped:
checking some other version would be a guess. Without `gradle.lockfile`, deps.dev resolves the tree of
each direct dependency.
**Composer.** deps.dev does not index Packagist, so versions come from `repo.packagist.org/p2` and
advisories from two sources: OSV (`Packagist`) and Packagist's security advisories API, which also
carries FriendsOfPHP records. A version is clean only when both agree. Constraints (`^`, `~`, `*`,
ranges, `|`/`||`, `@stable`/`@beta` flags, `self.version`) resolve the way Composer does. deps.dev
resolves no Packagist graphs, so pinright builds them from each release's `require` in Packagist's
metadata: every requirement goes to the newest stable release that satisfies it, skipping platform
packages (`php`, `ext-*`, `lib-*`), virtual packages that only exist as `provide`, and names that a
package already in the graph replaces. That gives Composer the same hook checks as npm and PyPI (a pin
outside its parent's range, the parent upgrade that pulls a fixed dependency, vulnerable transitive
dependencies) and lets `check-manifest` audit a `composer.json` without a lock. Like deps.dev, it
resolves each direct dependency on its own; `composer.lock` is still the exact tree. Dev branches
(`dev-main`) are not releases and are never recommended.
An abandoned package shows as deprecated, with its replacement.
**GitHub Actions.** For every `uses: owner/repo[/path]@ref` (local `./` actions and `docker://` images
are skipped), pinright resolves the ref to its commit and its most specific tag (`v4` to `v4.2.2`) and
checks the OSV `GitHub Actions` advisories for that release. OSV cannot compare versions for this
ecosystem, so pinright reads the affected ranges itself. A compromised or vulnerable action
(`tj-actions/changed-files`, GHSA-mrrh-fwg8-r2c3) is blocked, with the fixed release pinned to its
SHA. A tag or branch ref gets a warning with the same release pinned to its SHA and the version as a
comment; `PINRIGHT_ACTIONS_PIN=enforce` blocks it. A branch, or a SHA that matches no recent tag, has
no known version: when the action has advisories, the result is "unverified", never clean.
pinright reads each action repo's tags and branches with one git request (what `git ls-remote`
does), cached for an hour because tags can move. That request does not count against GitHub's API
limit; the API is the fallback for short SHAs and private repos, and answers "latest release" for a
vulnerable action.
---
# The pre-install hook
Once `pinright init` has wired the hook ([Install](https://github.com/Hiper-AI/pinright/blob/main/docs/install.md)) and you have restarted the agent,
every install command and every write to a manifest or workflow goes through the hook first. When
the agent runs
`npm install lodash@4.17.20`, it gets this back and the command does not run:
```
pinright blocked this dependency change:
- lodash@4.17.20 (npm) has 5 known advisories (CVE-2021-23337, CVE-2026-4800, CVE-2020-28500, HIGH). Use 4.x release 4.18.1: npm install lodash@4.18.1
Change the version (or the name) and try again. check-package and get-docs from the pinright MCP server explain each case.
```
The agent reads the reason and usually retries with the version it names. Commands that install
nothing pass without a network call; a check of one package takes a few seconds the first time
and well under a second once cached (see [Latency](#latency)).
To let one package through (a private one, say), add it to `"allow"` in `.pinright.json`. To turn
the hook off, delete the pinright entry from the client's hook file (Claude Code: `hooks.PreToolUse`
in `.claude/settings.json`; Cursor: `.cursor/hooks.json`; the others under [Clients](https://github.com/Hiper-AI/pinright/blob/main/docs/install.md#clients)); the
MCP tools keep working. When deps.dev or OSV cannot be reached, the starter `.pinright.json` that
`init` writes has the hook ask you (`"onError": "ask"`). Without a policy file the hook allows the
change and tells the agent it was not verified (see [When a source is down](#when-a-source-is-down)).
## What it reads
`pinright hook ` reads what the agent is about to do, in each agent's hook format:
| Agent | Command | Events `init` registers | How it blocks |
|---|---|---|---|
| Claude Code | `hook claude` | `PreToolUse` on `Bash\|PowerShell\|Write\|Edit\|MultiEdit\|NotebookEdit` | `permissionDecision` deny or ask |
| Cursor | `hook cursor` | `beforeShellExecution`, `preToolUse` | `permission` deny or ask |
| VS Code / Copilot | `hook copilot` | `PreToolUse` in `.github/hooks/pinright.json` | `permissionDecision` deny or ask |
| OpenAI Codex | `hook codex` | `PreToolUse` on `Bash\|apply_patch` | `permissionDecision` deny |
| Gemini CLI | `hook gemini` | `BeforeTool` on `run_shell_command\|write_file\|replace` | `decision` deny |
| Windsurf | `hook windsurf` | `pre_run_command`, `pre_write_code` | exit code 2, reason on stderr |
Codex, Gemini CLI and Windsurf have no "ask a human" answer, so where Claude Code would ask,
pinright denies there and says why. For Codex `apply_patch`, the hook reads each added or updated
file out of the patch. What it checks:
- installs: `npm`/`pnpm`/`yarn`/`bun add|install`, `npx`/`pnpm dlx`/`bunx`, `pip install` (also `-r file`),
`uv add`/`uv pip install`, `uvx`, `pipx`, `poetry add`, `pdm add`, `cargo add|install`, `go get|install`,
`gem install`, `bundle add`, `dotnet add package`, `composer require`, `composer create-project`;
- writes to `package.json`, `requirements*.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`,
`build.gradle`, `build.gradle.kts`, `gradle/libs.versions.toml`, `composer.json`: only
dependencies that are new or changed version count, so editing an old project does not re-open
every old dependency;
- writes to `.github/workflows/*.yml` and `action.yml`: new or re-pointed `uses:` lines.
The command reader follows what a command runs: `bash -c`, `eval`, `$(…)`, `cmd /c`, `powershell
-Command`, wrappers like `sudo`, `env` and `xargs`, aliases and variables set in the same line, and
scripts run by name (`npm run`, lifecycle scripts, `make`, `just`, `sh script.sh`). Shell writes to a
manifest (`echo >>`, `tee`, `cat <`, `cp`) are read like a Write, and notebook cells with
`!pip install` like a command. Lockfiles, registry settings (`.npmrc`, `pip.conf`, `--index-url`) and
`overrides`/`resolutions` count too.
`npx ` runs the project's own bin when `node_modules/.bin` has it. The hook reads the whole line
before any of it runs, so in `npm install && npx tsc` the bin does not exist yet. The hook still treats
that `npx` as local when four things hold. An earlier command on the line ran `npm install`, `npm ci`,
`pnpm install` or `yarn` with no package names, no options that change what gets linked, and no
wrapper. The `package.json` in that folder lists the bin's package under `dependencies` or
`devDependencies`: a package with the bin's name, or `typescript` for `tsc` and `tsserver`
(`@angular/cli`, `@biomejs/biome`, `@playwright/test` and `@nestjs/cli` for theirs). `npx` runs in the
same folder with no version or `-p`. Between the two, only `&&`, `;`, a newline or a pipe into a
filter (`| tail`) join the commands, and none of them can remove the bin or leave the folder unknown.
A `||`, a background `&`, a subshell, `rm -rf node_modules`, `cd "$X"` or `popd` brings the check
back. If the install fails, `npx` downloads the package after all, as it would if you typed it.
What the hook cannot check (a package name in a variable, a git or URL source, another registry, a
manifest rewritten by `sed -i`) is *unverifiable*: it asks by default (`PINRIGHT_HOOK_UNVERIFIABLE`).
Changes to `.pinright.json` or to the hook's entry in the agent settings always ask a human. The hook is
a guardrail, not a sandbox: [HOOK-THREAT-MODEL.md](https://github.com/Hiper-AI/pinright/blob/main/docs/HOOK-THREAT-MODEL.md) lists what it covers,
what it does not, and each bypass we tried. After upgrading, run `pinright init` again to pick up the
new matcher.
It blocks malware, typosquats, packages or versions that do not exist, versions with known advisories
when a clean one exists, deprecated versions with a maintained successor, and dependencies whose
transitive tree has advisories that a same-line upgrade clears. When a vulnerable pin is itself a
dependency of another pinned package, it points at the parent upgrade, so the fix still installs.
It also blocks a manifest whose pinned versions contradict each other (a pin outside the range its
parent requires), because that install would fail. A pin outside a range set deeper in another pin's
tree gets a note instead, because the resolver may still find a release in between that accepts it.
Before it recommends a version, the hook checks it against the ranges the rest of the file sets on that
package: every requirement in the other pins' resolved graphs for pip and Composer, and peer ranges for
npm (read only when the fix moves to a new major). If the fix is out of range, the message names the
package that sets the range and recommends the newest release inside it with no known advisories. When
no release in range is clean, it names the least exposed one, says whether a newer release of the
package that sets the range accepts the fix, and leaves the choice between upgrading that package and
accepting the advisories. In the benchmark, `stirrup` 0.2.1 pulls `moviepy` 2.2.1, which requires
`pillow<12.0`, and `pillow` 11.3.0's advisories are fixed only in 13.0.0: the hook now says so instead
of suggesting an override to 13.0.0. The check never lifts a block; it changes the version recommended
and the explanation. A vulnerable pip or Composer pin that another pin pulls, with no clean release in
range, still asks a human, as before. The MCP tool `check-packages` applies the same check to the
packages passed in one call, so the version it says to use already fits the others. When no clean version exists at all, it asks a
human for high and critical advisories and lets the rest through with a note, so the work does not stop
on a moderate finding nobody can fix yet. It also blocks two supply-chain patterns (see [Supply-chain signals](https://github.com/Hiper-AI/pinright/blob/main/docs/how-it-works.md#supply-chain-signals)): a
package first published less than 14 days ago that runs install scripts, and a release that adds install
scripts and comes from a publisher the previous releases never had. Everything else passes, with notes
for the agent.
**Undeclared imports.** An agent can pin every dependency it lists and still import one it never
listed: in the benchmark, the hook-only agent wrote `from langchain_text_splitters import ...` without
`langchain-text-splitters` in `requirements.txt`, and the import failed. When the agent writes a Python
or JS/TS source file, the hook compares the imports that are new in that write with the manifests above
it (`requirements*.txt`, `pyproject.toml`, `setup.py`/`setup.cfg`/`Pipfile`, `package.json`, including
the ones of an enclosing workspace); when it writes `requirements*.txt`, `pyproject.toml` or
`package.json`, it compares the project's source files with the new content. Each missing package comes
back as a note with the newest clean version to pin, checked like any other dependency. It never blocks.
Python import names go through a curated map to distribution names (`yaml` is PyYAML, `PIL` is pillow,
`sklearn` is scikit-learn, LangChain's split packages, ...) and PEP 503 normalization otherwise.
Left alone: the standard library and Node builtins, relative imports, aliases (`@/`, `~/`, `#`, `$lib`,
`tsconfig` paths), project-local modules and workspace packages, imports guarded by `try`/`if`
(optional dependencies), and names the registry does not know. A package that is only pulled in by
another one still gets the note: it works today by accident. `PINRIGHT_IMPORTS_TIMEOUT_MS` (15000) bounds
the check.
The team policy in `.pinright.json` ([Team policy](https://github.com/Hiper-AI/pinright/blob/main/docs/policy.md)) sets the same knobs for the whole repo. The hook
reads the nearest one walking up from its working directory to the repository root. These variables
override the file:
| Variable | Default | Meaning |
|---|---|---|
| `PINRIGHT_ALLOW` | none | Comma list of names that skip the hook, `*` wildcard (`@acme/*`). Added to the file's `allow`. For private packages. |
| `PINRIGHT_HOOK_ON_ERROR` | `allow` (`ask` in the starter `.pinright.json`) | What to do when deps.dev or OSV cannot be reached: `allow`, `ask` or `deny`. A name one edit away from a popular package asks even with `allow`. |
| `PINRIGHT_HOOK_UNVERIFIABLE` | `ask` | What pinright cannot check (git or URL sources, another registry, a command or file it cannot read): `allow`, `ask` or `deny`. |
| `PINRIGHT_HOOK_NO_FIX` | `severity` | When no clean version exists: `severity` asks for high/critical and allows the rest; or `allow`, `ask`, `deny` for all. |
| `PINRIGHT_HOOK_COOLDOWN` | `warn` | `enforce` blocks an unpinned install whose newest version is inside the cooldown window. |
| `PINRIGHT_HOOK_TIMEOUT_MS` | `45000` | Deadline for the whole check, counted from the hook's start. On timeout the hook asks a human, whatever `onError` says (a stricter `deny` still denies); Codex, Gemini CLI and Windsurf have no ask and get a deny with the reason. Keep it below the hook timeout in the agent's settings (60 s as `init` writes it): past that, the agent lets the change through. |
| `PINRIGHT_HOOK_RISK` | `enforce` | Supply-chain signals: `enforce` blocks the two patterns above, `warn` only notes them, `off` ignores them. |
| `PINRIGHT_SEVERITY_THRESHOLD` | `low` | Advisories below this severity (`low`, `moderate`, `high`, `critical`) become notes instead of blocks. |
| `PINRIGHT_ACTIONS_PIN` | `warn` | `enforce` blocks a GitHub Action referenced by a tag or branch instead of a commit SHA. |
## When a source is down
pinright says "ok" only when deps.dev and OSV both answered. If either one fails, the verdict is
`unknown` and names the host and the cause (`api.osv.dev unreachable (DNS lookup failed)`,
`HTTP 503`, `no answer within 15 s`). With OSV down, a version that deps.dev already flags stays
`vulnerable`; one deps.dev calls clean becomes `unknown`, because deps.dev mirrors OSV hours late
and malware reports reach OSV first.
The hook then applies `onError` and says so. With the default `allow`, the agent gets a note
ending in `Allowed unverified (onError: allow)`. With `ask` or `deny`, the reason heads the block
message: `... could not be verified (...). The project's onError policy is "deny" for checks that
cannot complete.` The same goes for transitive dependencies it could not check and for GitHub
Actions refs it could not resolve (reported as unverified, never as "does not exist").
A check that outlives `PINRIGHT_HOOK_TIMEOUT_MS` (45 s) is different. The agents give the hook 60 s
and then run the tool anyway, so pinright answers first and asks you, even with `onError: allow`:
`pinright could not finish checking left-pad in time (45 s, PINRIGHT_HOOK_TIMEOUT_MS); a human should
approve it, or retry once deps.dev and OSV answer.` The deny list, unverifiable sources and lookalike
names still decide as usual, since they need no network.
| What fails | Verdict / tool answer | Hook (`onError: allow` / `deny`) |
|---|---|---|
| No network, DNS failure | `unknown`: "deps.dev did not answer (api.deps.dev unreachable (DNS lookup failed))" | allow with the note / deny with the reason |
| deps.dev 5xx | `unknown`, with the HTTP status | same |
| OSV down, deps.dev up | deps.dev's advisories still count; otherwise `unknown` ("osv.dev did not answer ...; unverified") | same for the unverified ones |
| deps.dev has not indexed a fresh release yet (404 there, published on npm, PyPI, crates.io or RubyGems) | `unknown`: "version 3.8 of jsonpointer is published on pypi.org (...), but deps.dev has no data for it yet ..."; advisories and malware from osv.dev alone. A whole package deps.dev has never seen but the registry publishes is `unknown` too | the version: allow with the note / deny with the reason. The package: ask (deny with `onError: deny`), since it is hours old. If the registry also answers 404 it is "never published"; if the registry does not answer, deps.dev's 404 stands |
| A host that never answers | timeout after `PINRIGHT_TIMEOUT_MS`; later calls to that host fail at once for 30 s | ask by `PINRIGHT_HOOK_TIMEOUT_MS` at the latest |
| GitHub rate limit | the answer ends with what it is missing and when the limit resets | Actions refs: unverified, `onError` decides |
| jsDelivr 5xx (docs) | fewer docs, and a closing NOTE naming the hosts that failed | not involved |
Every MCP answer and every `check`/`audit`/`upgrade` run ends with a `NOTE: some sources did not
answer: ...` line when an upstream failed while it ran, including failures the tool worked around.
Two cases stop instead: `audit` when OSV does not answer its batch query, and `upgrade` when deps.dev
does not answer. They print `[pinright] fatal: ...` with the host and exit 1, the same code as
findings, so nothing passes; the GitHub Action reports them as exit code 3.
`check-packages` answers within `PINRIGHT_BATCH_TIMEOUT_MS`: packages still pending get an
`ERROR, not checked` row. `pinright doctor` shows which upstreams answer from your machine.
## Latency
The hook runs before every shell command and every manifest or workflow write, so the agent waits
on it. The table below times the hook itself, run as `node dist/cli.js hook claude`, which is what
the global `pinright` binary runs. The launcher in the agent's config adds its own start-up on top
(Windows 11, Node 24.20, npm 11.19, 7 runs after a warm-up, the hook on `npm test`, 2026-11-01):
| Launcher in the agent config | p50 / p95 per hook call |
|---|---|
| `pinright hook claude` (global install: what `init --user` or `--bin` writes) | 157 / 182 ms |
| `npx -y pinright hook claude` (what project files get), with the global install present | 949 / 1,317 ms |
| `npx -y ` from npx's cache, no global install (measured with `semver`; npx revalidates the package with the registry on each call) | 1,069 / 1,113 ms |
| the same pinned to its major (`semver@7`), which adds an advisories request | 1,287 / 1,382 ms |
| `node -e 0`, for reference | 84 / 119 ms |
The budget for the hook itself:
| Case | Budget | Measured p50 / p95 |
|---|---|---|
| A command that installs nothing (`npm test`) | under 150 ms above Node's own start | 121 / 177 ms, with `node -e 0` at 88 ms |
| One install, warm cache (`npm i express`) | under 1 s | 358 / 372 ms |
| One install, cold cache | under 5 s | 2.4 / 3.7 s |
| A 15-line `requirements.txt`, warm / cold | under 1 s / under 5 s | 1.0 / 1.5 s and 4.6 / 5.6 s |
| A `package.json` with 30 new dependencies, warm / cold | under 1.5 s / bounded by `PINRIGHT_HOOK_TIMEOUT_MS` | 1.2 / 1.5 s and 10.9 / 15.2 s |
| A workflow with 3 `uses:` lines, warm / cold | under 1 s / under 5 s | 392 / 436 ms and 1.5 / 2.0 s |
Measured with `scripts/latency.ts` (5 runs per cell, Windows, Node 24, no `GITHUB_TOKEN`; with a
token the numbers stay in the same range) against the live services, so the cold column moves with
their load. A new 30-dependency manifest makes about 600 requests the first time: the verdict, the
dependency graph and the supply-chain signals of each package. The hook checks only the lines a
write adds or changes, so editing an existing manifest costs what the changed lines cost.
How it stays there: the hook loads only the command parser until it finds a dependency change; it
fetches the verdict, the dependency graph and the risk signals of a package side by side; it probes
candidate versions a few at a time, newest first; and it skips a host that failed to connect or timed
out for 30 seconds instead of paying one timeout per lookup. `scripts/mcp-latency.ts` measures the
MCP tools the same way.
---
# Team policy (.pinright.json)
A `.pinright.json` at the project root, committed with the code, gives every developer and every agent
the same rules. It is JSON with `//` comments allowed. Every key is optional:
```jsonc
{
"allow": ["@acme/*"], // skip every check (private packages); "*" is a wildcard
"deny": [
"left-pad", // any ecosystem
{ "name": "request", "ecosystem": "npm", "reason": "unmaintained; use undici" }
],
"licenses": {
"deny": ["AGPL-*", "SSPL-*"], // SPDX ids, "*" wildcard
"allow": ["MIT", "Apache-2.0", "BSD-*", "ISC"] // when set, anything else is denied
},
"severityThreshold": "high", // low | moderate | high | critical
"cooldownDays": 7, // minimum age of a recommended version
"cooldown": "enforce", // warn | enforce
"noFix": "severity", // severity | allow | ask | deny
"onError": "ask", // allow | ask | deny
"unverifiable": "ask", // allow | ask | deny (git/URL sources, other registries)
"actionsPin": "warn" // off | warn | enforce (GitHub Actions pinned to a SHA)
}
```
| Key | Hook | MCP tools |
|---|---|---|
| `allow` | Listed names pass without a check. `allow` wins over `deny`. | No policy findings for them. |
| `deny` | Denied with the reason, before any lookup. Only new or changed lines of a manifest count. | `POLICY:` line in `check-package` and `get-docs`; every match in the tree in `check-manifest`. |
| `licenses` | A version whose license expression has no acceptable alternative is denied (`MIT OR AGPL-3.0` passes a deny on `AGPL-*`). A missing or non-SPDX license is a note. | Same, for the version checked; direct dependencies in `check-manifest`. |
| `severityThreshold` | When every advisory of a version is rated below it, the hook allows with a note. Unrated advisories and malware always count. Applies to transitive findings too. | Not applied: the tools report every advisory. |
| `cooldownDays`, `cooldown` | As `PINRIGHT_COOLDOWN_DAYS` and `PINRIGHT_HOOK_COOLDOWN`. | `cooldownDays` changes the recommended version. |
| `noFix`, `onError`, `unverifiable` | As `PINRIGHT_HOOK_NO_FIX`, `PINRIGHT_HOOK_ON_ERROR` and `PINRIGHT_HOOK_UNVERIFIABLE`. | |
Precedence is built-in defaults, then the file, then environment variables. Lists merge
(`PINRIGHT_ALLOW` adds to `allow`); single values from the environment replace the file's.
The built-in `onError` is `allow`, so installing pinright never blocks an offline laptop. The starter
file that `pinright init` writes sets `"onError": "ask"`: with it, a registry that is down or slowed
on purpose cannot turn the check off, and you approve each install by hand until it answers again.
A developer who works offline can set `PINRIGHT_HOOK_ON_ERROR=allow` for themselves.
A file that is not valid JSON, or has an unknown key or a wrong value, does not count as "no policy":
the hook denies every dependency change with the error until someone fixes the file, and the MCP tools
start their answer with `POLICY ERROR`. The agent can propose the fix: a write to
`.pinright.json` asks a human instead of being denied, as every change to the policy does.
---
# CLI and configuration
## Commands
```bash
npx pinright check npm axios@1.7.9 # exit 1 if not ok
npx pinright audit . --fail-on=high # whole-tree audit for CI, exit 1 on findings
npx pinright audit package-lock.json --json
npx pinright upgrade npm zod 3.25.76 4.6.7 # what changes between two versions
npx pinright audit .github/workflows # GitHub Actions: advisories and SHA pinning
npx pinright check composer guzzlehttp/guzzle:7.4.0
npx pinright audit . --fail-on high --sarif pinright.sarif # SARIF 2.1.0 for code scanning
npx pinright doctor # setup check: Node, upstreams, cache, GitHub auth, wiring
npx pinright cache prune # drop expired entries, cap the size
npx pinright cache clear # delete the disk cache
npx pinright check --help # every command has --help
```
`pinright --help` lists the commands, `pinright --help` shows one, `pinright --version`
prints the version. A mistyped command or flag gets a suggestion (`pinright chek` answers
`Did you mean "pinright check"?`) and exit code 2, instead of being ignored. Colors appear
only on a terminal; `NO_COLOR` turns them off and `FORCE_COLOR` turns them on through a pipe.
Run `pinright` with no arguments in a terminal and you get the help; an agent starting it over a
pipe gets the MCP server, and `pinright serve` starts the server either way.
Exit codes, for every command:
| Code | Meaning |
|---|---|
| 0 | Done. `check`: verdict ok. `audit`: nothing at or above `--fail-on`. `doctor`: no check failed. |
| 1 | `check`: the verdict is anything but ok, `unknown` included. `audit`: findings at or above `--fail-on`. `upgrade`: no target version. `doctor`: a check failed. |
| 2 | Usage error: unknown command or flag, missing or bad argument, nothing to audit. |
`pinright hook` puts its decision on stdout and exits 0; for Windsurf it blocks with exit 2 and the
reason on stderr. An error while deciding asks a human. Input that is not JSON exits 1, which Claude
Code and Cursor read as "proceed": the agent application builds that input, not the model (see
[HOOK-THREAT-MODEL.md](https://github.com/Hiper-AI/pinright/blob/main/docs/HOOK-THREAT-MODEL.md)).
**`pinright doctor`** checks, and only reads: the Node version against `engines`; whether deps.dev,
OSV, the npm registry, PyPI, Packagist and jsDelivr answer, with the time each took (deps.dev and
OSV are the verdict, so those two failing fails the run); the cache directory, writable or not,
with its size; how pinright authenticates to GitHub (`GITHUB_TOKEN`, `GH_TOKEN`, the GitHub CLI
login or anonymous) and how many API requests are left this hour, never the token; which agents
have pinright configured, from the same client list `init` uses (project and user files), and for
those with a hook whether it is wired; how each client starts the server and the hook (the global
`pinright`, npx or a checkout), with a warning and the npx cost measured on the spot when a hook
goes through npx, and when a user hook and a different project hook would both run; the nearest `.pinright.json` and whether it parses; and how long the hook takes
on a command that installs nothing, run directly. `--json` prints the same as JSON, `--offline`
skips the network probes and the npx measurement.
**Cache.** Answers from the registries and advisory databases are kept on disk:
`%LOCALAPPDATA%\pinright` on Windows, `$XDG_CACHE_HOME/pinright` or `~/.cache/pinright` elsewhere
(`XDG_CACHE_HOME` wins on Windows too when it is set), or `PINRIGHT_CACHE_DIR`. `pinright cache path` prints it. Advisories and versions expire after 24
hours, docs after 7 days, file listings of a release tag after a year. An expired entry is deleted
when it is next read. The MCP server and `check`/`audit`/`upgrade` prune once a day: expired entries
first, then the oldest until the cache fits `PINRIGHT_CACHE_MAX_MB` (200). The hook never prunes,
since the agent waits on it. `pinright cache prune` does it now, `pinright cache clear` deletes
everything.
`audit` flags: `--fail-on low|moderate|high|critical|none` (default `low`; `none` reports
and exits 0), `--json`, `--sarif `, `--sarif-root ` (SARIF paths are relative to
it; default is the git repository root), `--config ` (a `.pinright.json` other than the
nearest one) and `--no-supply-chain` (skip the per-package checks below).
Besides the advisories of the whole tree, `audit` checks each direct dependency for a
typosquat name, a package or version the registry does not have, deprecation and the
[supply-chain signals](https://github.com/Hiper-AI/pinright/blob/main/docs/how-it-works.md#supply-chain-signals), and applies the deny and license rules of
`.pinright.json`. Exit codes: 0 clean, 1 findings, 2 bad input or nothing to audit. At any
`--fail-on` level other than `none`, these findings fail the run whatever their severity:
malware, a typosquat, an install script in a brand-new package or from a new publisher, a
package or license the policy denies, and an action ref that does not exist. A
`.pinright.json` that does not parse fails it even with `none`. A missing version, deprecation
and the other risk signals show up in the report and never fail it. Neither does a package or
version the registry publishes and deps.dev has not indexed yet (it does so with a delay of hours):
it is reported as unverified (`pinright/not-indexed` in SARIF), with osv.dev's advisories for it
counted as usual.
## Configuration
| Variable | Default | Meaning |
|---|---|---|
| `PINRIGHT_COOLDOWN_DAYS` | `3` | Minimum age of a version to be recommended. |
| `PINRIGHT_MAX_CANDIDATES` | `12` | Versions inspected, newest first, before giving up on a safe one. |
| `GITHUB_TOKEN` / `GH_TOKEN` | none | Raises GitHub's API limit from 60 to 5,000 requests an hour. Read-only use; sent only to `api.github.com`. |
| `PINRIGHT_GH_CLI` | unset | `1` uses the GitHub CLI login (`gh auth token`) when no `GITHUB_TOKEN` is set. |
| `PINRIGHT_DEBUG_HTTP` | unset | `1` logs each request (method, URL, status, start offset and duration; never headers) to stderr. |
| `PINRIGHT_DOCS_BUDGET` | `10000` | Characters of docs per answer. |
| `PINRIGHT_CACHE_DIR` | OS cache dir `/pinright` | Disk cache (docs 7 days, advisories 24 h, repo listings at a tag 1 year). |
| `PINRIGHT_NO_CACHE` | unset | `1` disables the cache. |
| `PINRIGHT_CACHE_MAX_MB` | `200` | Size the daily prune brings the cache down to. |
| `PINRIGHT_TIMEOUT_MS` | `15000` | Per-request timeout, body included. A host that times out or refuses is skipped for 30 s. |
| `PINRIGHT_BATCH_TIMEOUT_MS` | `45000` | Deadline for `check-packages`; packages still pending come back as "not checked". The check of the ranges the packages set on each other runs within the same deadline and is skipped when it runs out. |
| `PINRIGHT_PROJECT_DIR` | working directory | Project to read installed versions and `.pinright.json` from, when the client does not announce roots. |
No telemetry. Requests go from your machine to the public APIs listed in [How pinright works](https://github.com/Hiper-AI/pinright/blob/main/docs/how-it-works.md) and nowhere else. Docs
content is data for the agent; pinright does not execute anything it downloads. [SECURITY.md](https://github.com/Hiper-AI/pinright/blob/main/SECURITY.md)
lists each service and what it receives, and how to report a vulnerability. A docs-site URL from
package metadata goes through a guard that refuses loopback, private and cloud-metadata addresses
(see SECURITY.md). Behind a proxy, set
`HTTPS_PROXY` with `NODE_USE_ENV_PROXY=1` (recent Node 22 and 24).
## GitHub rate limit
Without a token, GitHub's API allows 60 requests an hour per IP. pinright spends little of it:
- Repo files at a release tag come from jsDelivr's GitHub mirror (`data.jsdelivr.com` listings,
`cdn.jsdelivr.net/gh` files), which has no rate limit and keeps a tag forever. pinright caches the
listing for a year. The API lists only the default branch and repos over jsDelivr's 50 MB limit.
- Actions refs come from one git request per repo, outside the API limit.
- Upgrade guides read GitHub release notes through the API: 3 pages without a token, 10 with one.
Measured on a cold cache, 2026-10-29: docs for 8 popular npm and PyPI packages took 1 API request
(next.js, too large for jsDelivr), down from 9. `upgrade npm next 15.5.0 16.0.0` took 4, down from 6.
Auditing a workflow with 10 actions took 2, down from 23. The hook on a workflow with 3 actions took
none, down from 6.
When GitHub says the budget is spent (403 or 429 with `x-ratelimit-remaining: 0`, or `retry-after`),
pinright stops calling the API until the reset and remembers that in its cache, so a hook process
started a second later does not try again. The answer then ends with a note: what it is missing,
when GitHub resets, and how to add a token.
To raise the limit to 5,000 an hour, use one of these:
- Export `GITHUB_TOKEN` in the environment that starts your agent. A fine-grained token with
read-only access to public repositories is enough.
- Set `PINRIGHT_GH_CLI=1` (or run `pinright init --gh-cli`) to use your GitHub CLI login. pinright runs
`gh auth token` once, the first time it needs the API. You have to opt in because that token
carries your account's full scopes (`repo`, `workflow`), far more than reading public repos needs.
pinright sends the token only to `api.github.com` over HTTPS. It never logs it, never puts it in a
cache key or a tool answer, and `init` never writes it into `.mcp.json` or settings files.
---
# Install: every client
Node 20.9 or newer. Two ways in:
```bash
# Just you, in every project: your user files, started from the installed binary.
npm i -g pinright
pinright init claude --user # or cursor, codex, gemini, vscode, ...
pinright doctor # optional: shows what answers, what is wired, what is missing
# Your team: project files that everyone gets from the repository.
npx -y pinright init # the clients this project already uses; then commit the files
```
The project files start pinright with `npx -y pinright`, which works on any machine with Node and
needs no install, at about 1 s per agent tool call on Windows. Your user files start the installed
binary, at about 0.2 s (see [Latency](https://github.com/Hiper-AI/pinright/blob/main/docs/hook.md#latency)). Pick one per project: when a project commits its
hook, a user hook with a different command would run beside it, so `init --user` leaves the hook out
there and says why (see [Choosing a launcher and a scope](#choosing-a-launcher-and-a-scope)).
Restart the agent so it picks up the MCP server and the hook ([Clients](#clients) lists what each one needs). [The hook](https://github.com/Hiper-AI/pinright/blob/main/docs/hook.md) shows what the agent gets back once it is wired.
## Choosing a launcher and a scope
`init` adds pinright to an agent client: the MCP server, the pre-install hook when the client has
hooks, and a starter [`.pinright.json`](https://github.com/Hiper-AI/pinright/blob/main/docs/policy.md) for the project.
```bash
pinright init # the clients this project already uses (Claude Code if none)
pinright init cursor # one client, in this project
pinright init codex --user # one client, for your user instead of this project
pinright init vscode --print # print what it would write and write nothing
```
Each line works the same as `npx -y pinright init ...`. What changes is the command `init` writes
for the agent, and `init` prints it next to each file with the reason:
- Project files (`.mcp.json`, `.claude/settings.json`, `.cursor/`, `.vscode/`, `.github/hooks/`,
`.gemini/`, `.codex/` in the repo) get `npx -y pinright` and `npx -y pinright hook `. A team
commits them, and they work on any machine with Node, at about 1 s per hook call on Windows.
Pinning the major (`pinright@1`) does not avoid npx's registry lookup, so `init` does not pin it.
- Your user files (`--user`, and clients that only have user files) get `pinright` and
`pinright hook ` when a global install is on your PATH: about 0.2 s per hook call. `init`
checks that this `pinright` is the package (its `package.json`, not a project's
`node_modules/.bin` or npx's cache) and of the same major; without one, they get npx too.
- `--bin` writes the binary into project files as well, for teams that all install pinright
globally. A teammate without it gets a hook that does not start, and the agent then runs the tool
unchecked; `init` says so and `doctor` warns. `--npx` writes npx everywhere.
One pinright hook per client: Claude Code merges the hooks of the user and the project settings and
runs both when their commands differ (it merges identical commands into one). A user hook through
the binary does not make a project with a committed npx hook faster; both run, the check happens
twice and the agent waits for the slower one. So `init --user` leaves the hook out of the user file
while you run it in a project that has its own, and says why; `init` in a project with a different
user hook writes the project's hook, which the team needs, and notes the double check. `doctor`
warns about both cases.
What `init` does to your files:
- It edits only the `pinright` entry. Other servers, other hooks and comments (JSONC) stay as you
left them, and so does the indentation, except that an entry written on one line next to the new
one can come back spread over several lines. In a Codex `config.toml` it replaces the
`[mcp_servers.pinright]` table and leaves the other lines alone.
- Before it changes a file, it copies it to `.pinright.bak`. A second run finds nothing to
change and writes nothing.
- If a file does not parse, `init` stops before it writes anything and tells you which file.
- It never writes a token. If an entry it replaces already sets variables, it keeps them and
warns about any that look like a credential. `--gh-cli` adds `PINRIGHT_GH_CLI=1` instead.
- `--project` (the default where the client has a project file) or `--user` picks the scope.
Windsurf has no project MCP file, so `init windsurf` writes your user files (server and hook)
without `--user` and creates no `.pinright.json`; its output says so.
`--no-hook`, `--no-mcp` and `--no-config` skip a part. The starter `.pinright.json` never replaces
an existing one.
With no client named, `init` sets up the clients whose directory or config is already in the
project (`.cursor/`, `.vscode/`, `.gemini/`, `.codex/`, `opencode.json`, ...). It lists the clients
installed for your user and the command for each, but leaves their user-level files alone.
No key is required. A `GITHUB_TOKEN` helps with large monorepos and upgrade guides; see
[GitHub rate limit](https://github.com/Hiper-AI/pinright/blob/main/docs/cli.md#github-rate-limit). Put it in the environment that starts your agent.
## Install links
[](https://cursor.com/en/install-mcp?name=pinright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBpbnJpZ2h0Il19)
[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pinright%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522pinright%2522%255D%257D)
[](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pinright%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522pinright%2522%255D%257D)
These links add the MCP server only. Run `init` in the project for the hook.
## Clients
| Client | MCP server | Pre-install hook | `init` |
|---|---|---|---|
| Claude Code | yes | yes (`PreToolUse`) | yes |
| Claude Desktop | yes | no hooks in the app | yes, or the `.mcpb` extension below |
| Cursor | yes | yes (`beforeShellExecution`, `preToolUse`) | yes |
| VS Code (GitHub Copilot) | yes | yes, preview (`.github/hooks`) | yes |
| Windsurf (Devin Desktop) | yes, user only | yes (`pre_run_command`, `pre_write_code`) | yes |
| OpenAI Codex | yes | yes (`PreToolUse`, Bash and `apply_patch`) | yes |
| Gemini CLI | yes | yes (`BeforeTool`) | yes |
| Zed | yes | no hooks (`agent.tool_permissions` deny lists only) | yes |
| JetBrains Junie | yes | no hooks | yes |
| JetBrains AI Assistant | yes, in the IDE settings | no hooks | prints the JSON to paste |
| Cline | yes, user only | not wired: Cline hooks are executable files and run on macOS and Linux only | yes |
| Roo Code | yes, project only | no hooks | yes |
| Continue | yes, project only | no hooks | yes |
| Amp | yes | not wired: Amp intercepts tools through TypeScript plugins | yes |
| opencode | yes | not wired: opencode intercepts tools through JS plugins | yes |
| Kiro | yes | not wired: Kiro's docs do not describe the tool input a hook receives | yes |
Where a client has no hook, the MCP tools still give the agent the verdict when it asks for one,
and `pinright audit` in CI catches what got through.
Some clients need one more step after `init`:
- Codex reads a project's `.codex/` only when you trust the project, and runs a new hook only after
you review it in `/hooks`.
- Gemini CLI asks before it runs a project hook it has not seen.
- Claude Code asks once to approve the servers in `.mcp.json`. Amp needs `amp mcp approve pinright`
for a workspace server.
- Claude Desktop and Windsurf load the server after a restart (Windsurf: refresh the MCP list).
- VS Code hooks are a preview. The Copilot agent reads `.github/hooks/`; for local agent sessions,
turn on `chat.useHooks`.
On native Windows, a client that cannot start `npx` (or the global `pinright`) directly works with
`cmd` as the command and `["/c", "npx", "-y", "pinright"]` (or `["/c", "pinright"]`) as the arguments.
Claude Code starts both directly.
#### Claude Code
Server: project `.mcp.json`; user `~/.claude.json`.
Hook (`pinright hook claude`): project `.claude/settings.json`; user `~/.claude/settings.json`.
```bash
npx -y pinright init claude
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Claude Desktop
Server: user `~/.config/Claude/claude_desktop_config.json` (Linux), `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
```bash
npx -y pinright init claude-desktop
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Cursor
Server: project `.cursor/mcp.json`; user `~/.cursor/mcp.json`.
Hook (`pinright hook cursor`): project `.cursor/hooks.json`; user `~/.cursor/hooks.json`.
```bash
npx -y pinright init cursor
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### VS Code (GitHub Copilot)
Server: project `.vscode/mcp.json`; user `~/.config/Code/User/mcp.json` (Linux), `~/Library/Application Support/Code/User/mcp.json` (macOS), `%APPDATA%\Code\User\mcp.json` (Windows).
Hook (`pinright hook copilot`): project `.github/hooks/pinright.json`; user `~/.copilot/hooks/pinright.json`.
```bash
npx -y pinright init vscode
```
```json
{
"servers": {
"pinright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Windsurf (Devin Desktop)
Server: user `~/.config/devin/mcp_config.json` (Linux, macOS), `%APPDATA%\devin\mcp_config.json` (Windows).
Hook (`pinright hook windsurf`): project `.devin/hooks.json`; user `~/.codeium/windsurf/hooks.json`.
```bash
npx -y pinright init windsurf
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Zed
Server: project `.zed/settings.json`; user `~/.config/zed/settings.json` (Linux, macOS), `%APPDATA%\Zed\settings.json` (Windows).
```bash
npx -y pinright init zed
```
```json
{
"context_servers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### JetBrains Junie
Server: project `.junie/mcp/mcp.json`; user `~/.junie/mcp/mcp.json`.
```bash
npx -y pinright init junie
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### JetBrains AI Assistant
AI Assistant keeps its MCP servers in the IDE settings, not in a file pinright can edit. Settings | Tools | AI Assistant | Model Context Protocol (MCP) > Add > STDIO, and paste:
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### OpenAI Codex
Server: project `.codex/config.toml`; user `~/.codex/config.toml`.
Hook (`pinright hook codex`): project `.codex/hooks.json`; user `~/.codex/hooks.json`.
```bash
npx -y pinright init codex
```
```toml
[mcp_servers.pinright]
command = "npx"
args = ["-y", "pinright"]
```
#### Gemini CLI
Server: project `.gemini/settings.json`; user `~/.gemini/settings.json`.
Hook (`pinright hook gemini`): project `.gemini/settings.json`; user `~/.gemini/settings.json`.
```bash
npx -y pinright init gemini
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Cline
Server: user `~/.cline/data/settings/cline_mcp_settings.json`.
```bash
npx -y pinright init cline
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Roo Code
Server: project `.roo/mcp.json`.
```bash
npx -y pinright init roo
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### Continue
Server: project `.continue/mcpServers/pinright.yaml`.
```bash
npx -y pinright init continue
```
```yaml
name: pinright
version: 0.0.1
schema: v1
mcpServers:
- name: pinright
type: stdio
command: "npx"
args: ["-y", "pinright"]
```
#### Amp
Server: project `.amp/settings.json`; user `~/.config/amp/settings.json`.
```bash
npx -y pinright init amp
```
```json
{
"amp.mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
#### opencode
Server: project `opencode.json`; user `~/.config/opencode/opencode.json`.
```bash
npx -y pinright init opencode
```
```json
{
"mcp": {
"pinright": {
"type": "local",
"command": ["npx", "-y", "pinright"],
"enabled": true
}
}
}
```
#### Kiro
Server: project `.kiro/settings/mcp.json`; user `~/.kiro/settings/mcp.json`.
```bash
npx -y pinright init kiro
```
```json
{
"mcpServers": {
"pinright": {
"command": "npx",
"args": ["-y", "pinright"]
}
}
}
```
## Claude Desktop extension
`npm run build:mcpb` builds `build/mcpb/pinright-.mcpb`, a Claude Desktop extension that
bundles the server with its dependencies and asks for an optional GitHub token, which Claude Desktop
keeps in the OS keychain. The build validates the manifest against the MCPB 0.3 schema and with the
official `mcpb` CLI. It is not published anywhere yet.