Primeros pasos

Instala failproofai, activa las políticas y deja que tus agentes funcionen de forma fiable

​

Requisitos

• Node.js >= 20.9.0
• Bun >= 1.3.0 (opcional - solo necesario para compilar desde el código fuente)

---

​

Instalación

npm

npm install -g failproofai

bun add -g failproofai

---

​

Inicio rápido

1. Activar las políticas

   Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtración de secretos y otros modos de fallo antes de que causen daño.

   failproofai policies --install
   

   Esto escribe entradas de hooks en los CLIs de agentes que tengas instalados (en ~/.claude/settings.json de Claude Code, ~/.codex/hooks.json de OpenAI Codex, ~/.copilot/hooks/failproofai.json de GitHub Copilot CLI, ~/.cursor/hooks.json de Cursor Agent, el shim de plugin generado en ~/.config/opencode/plugins/failproofai.mjs de OpenCode junto con una entrada de registro en el array plugin de ~/.config/opencode/opencode.json, ~/.pi/agent/settings.json de Pi, o ~/.gemini/settings.json de Gemini CLI). Si hay más de uno presente, se te pedirá que elijas; pasa --cli claude codex copilot cursor opencode pi gemini (cualquier subconjunto) para omitir el aviso.

   El soporte de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi y Gemini CLI está en beta — instala con --cli copilot, --cli cursor, --cli opencode, --cli pi, o --cli gemini.

   failproofai policies --install --scope project
   failproofai policies --install --cli codex --scope project
   failproofai policies --install --cli copilot --scope project
   failproofai policies --install --cli cursor --scope project
   failproofai policies --install --cli opencode --scope project
   failproofai policies --install --cli pi --scope project
   failproofai policies --install --cli gemini --scope project
   failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
   
2. Verificar

   failproofai policies
   

   Muestra todas las políticas, si están activadas y los parámetros configurados.

3. Abrir el panel de control

   failproofai
   

   Abre un panel de control local en http://localhost:8020 donde puedes explorar sesiones, inspeccionar llamadas a herramientas y gestionar políticas.

4. Ejecutar tu agente

   Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo ejecutarse sin supervisión y revisa lo que ocurrió en el panel de control.

---

​

Cómo funcionan las políticas

Cada vez que un agente ejecuta una herramienta, Claude Code llama a failproofai como subproceso:

Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout

Cada política devuelve una de tres decisiones:

• allow - el agente continúa con normalidad
• deny - la acción se bloquea y se le indica al agente el motivo
• instruct - se añade contexto adicional al prompt del agente

Las políticas se ejecutan en tu proceso local. No se envía nada a un servicio remoto.

---

​

Configurar políticas de equipo mediante políticas basadas en convenciones

La forma más rápida de establecer estándares de calidad en tu equipo es la convención .failproofai/policies/. Coloca archivos de políticas en este directorio y se cargan automáticamente — sin flags, sin cambios de configuración, sin comandos de instalación.

1. Crear el directorio de políticas

   mkdir -p .failproofai/policies
   
2. Añadir archivos de políticas

   Copia los ejemplos iniciales o escribe los tuyos propios:

   cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
   

   O crea uno nuevo:

   // .failproofai/policies/team-policies.mjs
   import { customPolicies, allow, deny, instruct } from "failproofai";
   
   customPolicies.add({
     name: "test-before-commit",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
         return instruct("Run tests before committing.");
       }
       return allow();
     },
   });
   
3. Confirmar en git

   git add .failproofai/policies/
   git commit -m "Add team quality policies"
   

   Cada miembro del equipo que tenga failproofai instalado recibirá estas políticas automáticamente. No se necesita configuración por desarrollador.

Confirma .failproofai/policies/ en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que descubráis nuevos modos de fallo, añade políticas y publícalas — todos recibirán la actualización en su próximo git pull. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que no deja de mejorar.

---

​

Almacenamiento de datos

Toda la configuración y los registros permanecen en tu máquina:

Ruta	Qué almacena
~/.failproofai/policies-config.json	Configuración global de políticas
~/.failproofai/hook-activity.jsonl	Historial de ejecución de hooks
~/.failproofai/hook.log	Registro de depuración para errores de hooks personalizados
.failproofai/policies-config.json	Configuración por proyecto (confirmada en el repositorio)
.failproofai/policies-config.local.json	Overrides personales (incluido en .gitignore)

---

​

Desinstalación

failproofai policies --uninstall

Elimina las entradas de hooks de ~/.claude/settings.json. Los archivos de configuración en ~/.failproofai/ se conservan.

---

​

Próximos pasos

Configuración

Ámbitos y formato de los archivos de configuración

Políticas integradas

Las 26 políticas con sus parámetros

Políticas personalizadas

Escribe tus propias políticas en JavaScript

Monitor de agentes

Supervisa sesiones y revisa la actividad de las políticas