pinright

pinright

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.

Install

Node 20.9 or newer. One line, then restart the agent:

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.

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.

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 · results and caveats · technical report · reproduce it

Against a widely used docs MCP server

People ask how pinright compares with the docs MCP servers they already use. We added one, a widely used local server with a free API key, as an arm of the same benchmarks: run v8, 2026-11-04, every arm on the same day and the same advisory data. Range over Sonnet 5.5, Haiku 5.5 and Opus 5.5, 2 runs per cell.

¹ Sonnet and Haiku; the free key hit its monthly quota during the Opus runs.

The docs MCP server moved agents to newer versions and halved the alerts, but it does not check the version the agent picks: its most common vulnerable pin was next@16.2.9 (20 advisories, 11 runs), the Next.js version it served docs for. It used fewer tokens than pinright in most cells, because its answers are shorter. With both installed, the agent took its versions from pinright and called the docs server 6 times in 144 runs. One docs server, one release, tasks we wrote or picked, no shell. Per-model tables

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

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 · the hook · team policy · CLI · GitHub Action

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 lists each host. The hook reads commands and files statically: it is a guardrail, not a sandbox, and the threat model 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 · prompt injection · benchmark · security review · changelog · contributing · release runbook

The report we value most is a false positive: a command the hook blocked, or a package it