Saltar al contenido principal

​
Requisitos

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

​
Instalación

npm install -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:
RutaQué almacena
~/.failproofai/policies-config.jsonConfiguración global de políticas
~/.failproofai/hook-activity.jsonlHistorial de ejecución de hooks
~/.failproofai/hook.logRegistro de depuración para errores de hooks personalizados
.failproofai/policies-config.jsonConfiguración por proyecto (confirmada en el repositorio)
.failproofai/policies-config.local.jsonOverrides 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