Install

One command, then restart the agent

init adds the MCP server, the hook where the client has hooks, and a starter .pinright.json. It edits only the pinright entry and backs up each file first.

Quick start

Just you, every project

Installs pinright once and writes your user config. The agent starts the installed binary, which is faster than npx.

$ npm i -g pinright
# or cursor, codex, gemini, vscode, windsurf
$ pinright init claude --user
# optional: what answers, what is wired
$ pinright doctor

Your team, in the repo

Writes project files that start pinright through npx. Commit them and every teammate with Node gets the same setup.

# the clients this project already uses
$ npx -y pinright init

Pick one per project. If a project commits its own hook, a user hook with a different command would run beside it, so init --user leaves the hook out there and says why. --print shows what init would write and writes nothing.

Node 20.9 or newer. No key required; a GITHUB_TOKEN in the agent's environment helps with large monorepos and upgrade guides.

Clients with the hook

These six get the MCP server and the pre-install hook. Name the client to set up only that one.

Claude Code MCP + hook

$ npx -y pinright init claude
Server
.mcp.json · user ~/.claude.json
Hook
PreToolUse in .claude/settings.json
Then
Approve the server in .mcp.json once.

Cursor MCP + hook

$ npx -y pinright init cursor
Server
.cursor/mcp.json
Hook
beforeShellExecution, preToolUse in .cursor/hooks.json

VS Code (GitHub Copilot) MCP + hook

$ npx -y pinright init vscode
Server
.vscode/mcp.json
Hook
.github/hooks/pinright.json (preview)
Then
For local agent sessions, turn on chat.useHooks.

OpenAI Codex MCP + hook

$ npx -y pinright init codex
Server
.codex/config.toml
Hook
PreToolUse on Bash and apply_patch
Then
Trust the project, and review the hook in /hooks.

Gemini CLI MCP + hook

$ npx -y pinright init gemini
Server
.gemini/settings.json
Hook
BeforeTool in the same file
Then
Gemini CLI asks once before it runs a new project hook.

Windsurf MCP + hook

$ npx -y pinright init windsurf
Server
User config only (Windsurf has no project MCP file)
Hook
pre_run_command, pre_write_code
Then
Restart Windsurf and refresh the MCP list.

MCP-only clients: Claude Desktop, Zed, JetBrains Junie, JetBrains AI Assistant, Cline, Roo Code, Continue, Amp, opencode and Kiro get the MCP server from init <client>. They have no pinright hook, so the agent gets the verdict when it asks, and the GitHub Action catches what gets through. Setup for each client

Manual config

The MCP server alone, if you prefer to edit the file yourself. Run init for the hook.

On native Windows, a client that cannot start npx directly works with cmd as the command and ["/c", "npx", "-y", "pinright"] as the arguments.

// .mcp.json, .cursor/mcp.json, .gemini/settings.json, ...
{
  "mcpServers": {
    "pinright": { "command": "npx", "args": ["-y", "pinright"] }
  }
}
// .vscode/mcp.json
{
  "servers": {
    "pinright": { "type": "stdio", "command": "npx", "args": ["-y", "pinright"] }
  }
}
# .codex/config.toml
[mcp_servers.pinright]
command = "npx"
args = ["-y", "pinright"]

GitHub Action

Runs pinright audit on lockfiles and workflows, writes a job summary, annotates the pull request and uploads SARIF to code scanning. It installs nothing from npm.

On pull requests it reads .pinright.json from the base commit, so a PR cannot relax its own checks. Private repos without GitHub Code Security: set upload-sarif: false.

name: dependencies
on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '17 6 * * 1'   # new advisories appear without a commit

permissions:
  contents: read

jobs:
  pinright:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # upload-sarif
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: Hiper-AI/pinright@<commit SHA> # pin the release you reviewed
        with:
          fail-on: high

Team policy: .pinright.json

Commit it at the project root and every developer, agent and CI run applies the same rules. Every key is optional. Environment variables override the file.

A file that does not parse denies every dependency change until someone fixes it. A change to the policy always asks a human.

{
  "allow": ["@acme/*"],              // private packages skip the check
  "deny": [
    "left-pad",
    { "name": "request", "ecosystem": "npm", "reason": "unmaintained; use undici" }
  ],
  "licenses": {
    "deny": ["AGPL-*", "SSPL-*"],
    "allow": ["MIT", "Apache-2.0", "BSD-*", "ISC"]
  },
  "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",             // git/URL sources, other registries
  "actionsPin": "warn"               // off | warn | enforce
}

CLI

The same verdict the agent gets, for people and scripts. Exit code 1 means findings.

pinright check npm axios@1.7.9            # exit 1 if not ok
pinright audit . --fail-on=high           # whole tree, for CI
pinright audit . --sarif pinright.sarif   # SARIF 2.1.0
pinright upgrade npm zod 3.25.76 4.6.7    # what changes between two versions
pinright audit .github/workflows          # Actions: advisories and SHA pinning
pinright doctor                           # setup check