Instalar

Un comando y después reinicia el agente

init agrega el servidor MCP, el hook en los clientes que tienen hooks y un .pinright.json inicial. Solo edita la entrada de pinright y antes hace una copia de respaldo de cada archivo.

Inicio rápido

Solo tú, en cada proyecto

Instala pinright una vez y escribe tu configuración de usuario. El agente arranca el binario instalado, que es más rápido que npx.

$ npm i -g pinright
# o cursor, codex, gemini, vscode, windsurf
$ pinright init claude --user
# opcional: qué responde y qué está conectado
$ pinright doctor

Tu equipo, en el repositorio

Escribe archivos del proyecto que arrancan pinright con npx. Súbelos al repositorio y cada persona del equipo que tenga Node recibe la misma configuración.

# los clientes que este proyecto ya usa
$ npx -y pinright init

Elige una opción por proyecto. Si un proyecto sube su propio hook, un hook de usuario con otro comando correría a su lado, así que init --user deja el hook afuera en ese caso y explica por qué. --print muestra lo que escribiría init y no escribe nada.

Node 20.9 o posterior. No hace falta ninguna clave; un GITHUB_TOKEN en el entorno del agente ayuda con monorepos grandes y con las guías de actualización.

Clientes con hook

Estos seis reciben el servidor MCP y el hook de preinstalación. Nombra el cliente para configurar solo ese.

Claude Code MCP + hook

$ npx -y pinright init claude
Servidor
.mcp.json · usuario ~/.claude.json
Hook
PreToolUse en .claude/settings.json
Después
Aprueba el servidor de .mcp.json una vez.

Cursor MCP + hook

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

VS Code (GitHub Copilot) MCP + hook

$ npx -y pinright init vscode
Servidor
.vscode/mcp.json
Hook
.github/hooks/pinright.json (preview)
Después
Para sesiones locales del agente, activa chat.useHooks.

OpenAI Codex MCP + hook

$ npx -y pinright init codex
Servidor
.codex/config.toml
Hook
PreToolUse en Bash y apply_patch
Después
Marca el proyecto como de confianza y revisa el hook en /hooks.

Gemini CLI MCP + hook

$ npx -y pinright init gemini
Servidor
.gemini/settings.json
Hook
BeforeTool en el mismo archivo
Después
Gemini CLI pregunta una vez antes de ejecutar un hook de proyecto nuevo.

Windsurf MCP + hook

$ npx -y pinright init windsurf
Servidor
Solo configuración de usuario (Windsurf no tiene archivo MCP de proyecto)
Hook
pre_run_command, pre_write_code
Después
Reinicia Windsurf y actualiza la lista de MCP.

Clientes solo MCP: Claude Desktop, Zed, JetBrains Junie, JetBrains AI Assistant, Cline, Roo Code, Continue, Amp, opencode y Kiro reciben el servidor MCP con init <cliente>. No tienen hook de pinright, así que el agente recibe el veredicto cuando lo pide, y la GitHub Action detecta lo que pase. Configuración de cada cliente (en inglés)

Configuración manual

Solo el servidor MCP, si prefieres editar el archivo tú. Ejecuta init para tener el hook.

En Windows nativo, un cliente que no puede arrancar npx directamente funciona con cmd como comando y ["/c", "npx", "-y", "pinright"] como argumentos.

// .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

Ejecuta pinright audit sobre lockfiles y workflows, escribe un resumen del job, anota el pull request y sube SARIF a code scanning. No instala nada desde npm.

En los pull requests lee .pinright.json del commit base, así un PR no puede relajar sus propias revisiones. Repositorios privados sin GitHub Code Security: usa upload-sarif: false.

name: dependencies
on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '17 6 * * 1'   # aparecen avisos nuevos sin ningún 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> # fija la versión que revisaste
        with:
          fail-on: high

Política de equipo: .pinright.json

Súbelo a la raíz del proyecto y cada desarrollador, agente y ejecución de CI aplica las mismas reglas. Todas las claves son opcionales. Las variables de entorno tienen prioridad sobre el archivo.

Un archivo que no se puede leer rechaza todo cambio de dependencias hasta que alguien lo arregle. Un cambio en la política siempre le pregunta a una persona.

{
  "allow": ["@acme/*"],              // los paquetes privados no se revisan
  "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,                 // edad mínima de una versión recomendada
  "cooldown": "enforce",             // warn | enforce
  "noFix": "severity",               // severity | allow | ask | deny
  "onError": "ask",                  // allow | ask | deny
  "unverifiable": "ask",             // fuentes git/URL, otros registros
  "actionsPin": "warn"               // off | warn | enforce
}

CLI

El mismo veredicto que recibe el agente, para personas y scripts. El código de salida 1 indica hallazgos.

pinright check npm axios@1.7.9            # sale con 1 si no está ok
pinright audit . --fail-on=high           # todo el árbol, para CI
pinright audit . --sarif pinright.sarif   # SARIF 2.1.0
pinright upgrade npm zod 3.25.76 4.6.7    # qué cambia entre dos versiones
pinright audit .github/workflows          # Actions: avisos y fijado por SHA
pinright doctor                           # revisa la configuración