Primeros pasos

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

bun add -g failproofai

Inicio rápido

Activa 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, filtraciones 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 instalados (el ~/.claude/settings.json de Claude Code, el ~/.codex/hooks.json de OpenAI Codex, el ~/.copilot/hooks/failproofai.json de GitHub Copilot CLI, el ~/.cursor/hooks.json de Cursor Agent, el shim de plugin generado de OpenCode en ~/.config/opencode/plugins/failproofai.mjs junto con una entrada de registro en el array plugin de ~/.config/opencode/opencode.json, el ~/.pi/agent/settings.json de Pi, o el ~/.hermes/config.yaml de Hermes). Si hay más de uno presente, se te pedirá que elijas; pasa --cli claude codex copilot cursor opencode pi hermes (cualquier subconjunto) para omitir la pregunta.El soporte para GitHub Copilot CLI, Cursor Agent, OpenCode y Pi es beta — instala con --cli copilot, --cli cursor, --cli opencode o --cli pi. Hermes (hermes-agent, una puerta de enlace para Slack/Telegram) se instala con alcance de usuario mediante --cli hermes y es también una fuente de auditoría sin conexión.

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 hermes --scope user
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys

Verifica la instalación

failproofai policies

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

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

Ejecuta tu agente

Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr desatendido 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 es bloqueada 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.

Configura políticas de equipo con 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.

Crea el directorio de políticas

mkdir -p .failproofai/policies

Añade archivos de políticas

Copia los ejemplos de inicio 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();
  },
});

Confirma los cambios 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 tu equipo descubra nuevos modos de fallo, añade políticas y haz push — 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 git)
`.failproofai/policies-config.local.json`	Sobreescrituras personales (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

Alcances y formato del archivo 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

Conceptos principales

CLI

Herramientas

Avanzado

Ejemplos

Primeros pasos

Requisitos

Instalación

Inicio rápido

Cómo funcionan las políticas

Configura políticas de equipo con políticas basadas en convenciones

Almacenamiento de datos

Desinstalación

Próximos pasos

Configuración

Políticas integradas

Políticas personalizadas

Monitor de agentes

​Requisitos

​Instalación

​Inicio rápido

​Cómo funcionan las políticas

​Configura políticas de equipo con políticas basadas en convenciones

​Almacenamiento de datos

​Desinstalación

​Próximos pasos

Configuración

Políticas integradas

Políticas personalizadas

Monitor de agentes

Requisitos

Instalación

Inicio rápido

Cómo funcionan las políticas

Configura políticas de equipo con políticas basadas en convenciones

Almacenamiento de datos

Desinstalación

Próximos pasos