hol-guard

HOL Guard

HOL Guard protege entornos de ejecución de IA locales antes de que las herramientas se ejecuten. Usa esta habilidad cuando el usuario desee comportamiento antivirus para IA, revisión de aprobaciones local, protección para Codex, protección para Claude Code, comprobaciones de seguridad de MCP, verificación de habilidades/paquetes o puertas de lanzamiento de hol-guard y plugin-scanner.

Reglas estrictas

• Nunca leer archivos .env.
• Nunca omitir aprobaciones de Guard.
• No marcar un área de trabajo como protegida hasta que un comando de Guard demuestre el estado.
• Preferir comandos reversibles de Guard sobre ediciones directas de configuración del entorno.
• No mutar la configuración del entorno a nivel de usuario a menos que el comando hol-guard sea el propietario de esa mutación.
• Tratar los fallos del escáner como reales hasta que se inspeccionen.
• Preservar los cambios existentes del usuario e inspeccionar git status --short antes de editar en un repositorio.

Verificación de instalación

Verificar ambos CLIs de forma independiente:

command -v hol-guard
command -v plugin-scanner

Si hol-guard falta y el usuario solicitó configuración en tiempo de ejecución, preferir:

pipx install hol-guard

Si plugin-scanner falta y el usuario solicitó escaneo, instalar la distribución separada del escáner:

pipx install plugin-scanner

No asumir que la distribución hol-guard proporciona el comando plugin-scanner. Si pipx no está disponible, explicar que se recomienda la instalación de CLI aislada en lugar de cambiar silenciosamente el entorno Python del usuario.

Después de la instalación en tiempo de ejecución:

hol-guard status
hol-guard detect --json

Proteger un entorno de ejecución local

Usar este flujo para Codex, Claude Code, Copilot CLI, Cursor, Gemini, Hermes, OpenClaw, OpenCode o Antigravity.

hol-guard bootstrap
hol-guard install <entorno>
hol-guard run <entorno> --dry-run
hol-guard run <entorno>
hol-guard status

Nombres de entornos:

• codex
• claude-code
• copilot
• cursor
• gemini
• hermes
• openclaw
• opencode
• antigravity

Alias de entornos:

• claude se asigna a claude-code
• gemini-cli se asigna a gemini
• open-code se asigna a opencode
• open-claw se asigna a openclaw
• copilot-cli se asigna a copilot

Usar bootstrap específico del entorno cuando esté disponible:

hol-guard hermes bootstrap

Claude Code

Usar esto cuando el área de trabajo tenga .claude/settings.local.json, .claude/agents, hooks de Claude, .mcp.json o superficies de aprobación de herramientas gestionadas por Claude.

hol-guard install claude-code
hol-guard run claude-code --dry-run
hol-guard run claude-code
hol-guard doctor claude-code --json

Claude Code es un objetivo de primera clase para Guard. Preferir hooks de Claude propiedad de Guard sobre ediciones manuales directas a la configuración de Claude.

Codex

Usar esto cuando el área de trabajo tenga configuración de Codex, .codex/hooks.json, servidores MCP de Codex o flujos de herramientas de Codex App/CLI.

hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
hol-guard doctor codex --json

Codex admite hooks Bash PreToolUse propiedad de Guard y obtención de MCP en el mismo chat cuando esté disponible.

Otros entornos

Usar el mismo flujo de Guard para:

• Copilot CLI: hol-guard install copilot
• Cursor: hol-guard install cursor
• Gemini CLI: hol-guard install gemini
• Hermes: hol-guard hermes bootstrap
• OpenClaw: hol-guard install openclaw
• OpenCode: hol-guard install opencode
• Antigravity: hol-guard install antigravity

Trabajo con aprobaciones

Si Guard bloquea o pone en cola trabajo:

hol-guard approvals
hol-guard approvals open
hol-guard receipts
hol-guard diff <entorno>

Para resolución solo por terminal:

hol-guard approvals approve <id-solicitud>
hol-guard approvals deny <id-solicitud>

Solo aprobar después de leer el motivo del riesgo y comprender el alcance solicitado.

Trabajo con evidencia

Usar comandos de evidencia cuando el usuario necesite pruebas, rastro de auditoría o artefactos de traspaso:

hol-guard receipts
hol-guard inventory
hol-guard abom --format json
hol-guard events
hol-guard explain <id-artefacto>

Para sincronización en la nube, mantenerlo opcional y dirigido por el usuario:

hol-guard connect
hol-guard connect status
hol-guard connect repair
hol-guard sync

Escanear un complemento o paquete de habilidad

Usar el modo escáner para complementos de Codex, superficies de proyecto de Claude Code, mercados .agents, habilidades, configuraciones de servidores MCP y puertas de lanzamiento.

plugin-scanner lint .
plugin-scanner verify .

Si se escanea un paquete específico:

plugin-scanner lint <ruta>
plugin-scanner verify <ruta>

Si el objetivo es una raíz de mercado de Codex con .agents/plugins/marketplace.json, escanear la raíz del repositorio para que las entradas de complementos locales puedan ser descubiertas.

Orientación de objetivos del escáner:

• Complemento de Codex: escanear la raíz del repositorio o la carpeta del complemento que contiene .codex-plugin/plugin.json.
• Mercado de Codex: escanear la raíz del repositorio que contiene .agents/plugins/marketplace.json.
• Proyecto de Claude Code: escanear la raíz del área de trabajo que contiene .claude/, .mcp.json, hooks o carpetas de agentes.
• Paquete de servidor MCP: escanear la raíz del paquete que contiene la configuración del servidor y los metadatos del paquete.
• Paquete de habilidad: escanear la carpeta que contiene SKILL.md.
• Área de trabajo de agentes mixtos: escanear la raíz del repositorio para que las superficies de complementos locales, habilidades, MCP y configuración del entorno se descubran juntas.

Comandos comunes de depuración

hol-guard doctor
hol-guard doctor <entorno> --json
hol-guard detect --json
hol-guard settings show
hol-guard explain install-connect
plugin-scanner verify . --json

Patrón de respuesta

Al usar Guard, informar:

• Qué comando se ejecutó.
• Qué encontró Guard.
• Qué permanece bloqueado o riesgoso.
• Qué prueba existe.
• El siguiente comando exacto si el usuario debe actuar.

No afirmar protección, aprobación o preparación para el lanzamiento sin la salida del comando que lo demuestre.