Saltar al contenido principal
Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalarlo y qué esperar.

​
Configurar hooks para Claude Code

Failproof AI se integra con Claude Code a través de su sistema de hooks. Cuando ejecutas failproofai policies --install, registra comandos de hook en el settings.json de Claude Code que se activan en cada llamada a una herramienta.
1

Instalar failproofai

npm install -g failproofai
2

Habilitar todas las políticas integradas

failproofai policies --install
3

Verificar que los hooks están registrados

cat ~/.claude/settings.json | grep failproofai
Deberías ver entradas de hook para los eventos PreToolUse, PostToolUse, Notification y Stop.
4

Ejecutar Claude Code

claude
Las políticas ahora se ejecutan automáticamente en cada llamada a una herramienta. Prueba pedirle a Claude que ejecute sudo rm -rf / — será bloqueado.

​
Configurar hooks para el Agents SDK

Si estás desarrollando con el Agents SDK, puedes usar el mismo sistema de hooks de forma programática.
1

Instalar failproofai en tu proyecto

npm install failproofai
2

Configurar hooks en tu agente

Pasa comandos de hook al crear el proceso de tu agente. Los hooks se activan de la misma manera que en Claude Code — mediante JSON por stdin/stdout:
failproofai --hook PreToolUse   # se llama antes de cada herramienta
failproofai --hook PostToolUse  # se llama después de cada herramienta
3

Escribir una política personalizada para tu agente

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Keep the agent inside the project directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    const path = String(ctx.toolInput?.file_path ?? "");
    if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
      return deny("Agent is restricted to the project directory");
    }
    return allow();
  },
});
4

Instalar la política personalizada

failproofai policies --install --custom ./my-agent-policies.js

​
Bloquear comandos destructivos

La configuración más habitual: evitar que los agentes causen daños irreversibles. 
failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
Qué hace cada uno:
  • block-sudo — bloquea todos los comandos sudo
  • block-rm-rf — bloquea la eliminación recursiva de archivos
  • block-force-push — bloquea git push --force
  • block-curl-pipe-sh — bloquea la ejecución de scripts remotos mediante pipe al shell

​
Prevenir la filtración de secretos

Impide que los agentes vean o filtren credenciales en la salida de las herramientas. 
failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
Estas políticas se activan en PostToolUse — después de que se ejecuta una herramienta, limpian la salida antes de que el agente la vea.

​
Recibir alertas en Slack cuando los agentes necesitan atención

Usa el hook de notificación para reenviar alertas de inactividad a Slack. 
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // nunca bloquear al agente si Slack no está disponible
    }

    return allow();
  },
});
Instálalo: 
SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

​
Mantener a los agentes en una rama

Evita que los agentes cambien de rama o hagan push a ramas protegidas. 
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

​
Requerir pruebas antes de los commits

Recuerda a los agentes que ejecuten las pruebas antes de hacer commit. 
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

​
Proteger un repositorio de producción

Incluye una configuración a nivel de proyecto en el repositorio para que todos los desarrolladores de tu equipo compartan las mismas políticas. Crea .failproofai/policies-config.json en tu repositorio: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}
Luego haz commit: 
git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"
Todos los miembros del equipo que tengan failproofai instalado adoptarán estas reglas automáticamente.

​
Construir un estándar de calidad para toda la organización con políticas de convención

La configuración más efectiva: incluye .failproofai/policies/ en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las reciben automáticamente — sin comandos de instalación, sin cambios de configuración.
1

Crear el directorio y agregar políticas

mkdir -p .failproofai/policies

// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

// Imponer el gestor de paquetes preferido del equipo
// (o habilitar la política integrada prefer-package-manager en su lugar)
customPolicies.add({
  name: "enforce-bun",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
    return allow();
  },
});

// Recordar al agente que ejecute las pruebas antes de hacer commit
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();
  },
});
2

Hacer commit en git

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

Seguir mejorando

A medida que tu equipo encuentre nuevos problemas, agrega políticas y haz push. Todos reciben la actualización en su próximo git pull. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo.

​
Más ejemplos

El directorio examples/ del repositorio contiene:
ArchivoQué muestra
policies-basic.jsPolíticas básicas — bloquear escrituras en producción, force-push y scripts mediante pipe
policies-notification.jsAlertas de Slack para notificaciones de inactividad y fin de sesión
policies-advanced/index.jsImportaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y manejo del evento Stop