Exemples - FailproofAI

Des exemples prêts à l’emploi pour les scénarios courants. Chacun montre comment installer et ce à quoi s’attendre.

Configurer des hooks pour Claude Code

Failproof AI s’intègre à Claude Code via son système de hooks. Lorsque vous exécutez failproofai policies --install, il enregistre des commandes de hook dans le fichier settings.json de Claude Code, qui se déclenchent à chaque appel d’outil.

Installer failproofai

npm install -g failproofai

Activer toutes les politiques intégrées

failproofai policies --install

Vérifier que les hooks sont enregistrés

cat ~/.claude/settings.json | grep failproofai

Vous devriez voir des entrées de hook pour les événements PreToolUse, PostToolUse, Notification et Stop.

Lancer Claude Code

claude

Les politiques s’exécutent désormais automatiquement à chaque appel d’outil. Essayez de demander à Claude d’exécuter sudo rm -rf / — la commande sera bloquée.

Configurer des hooks pour le Agents SDK

Si vous développez avec le Agents SDK, vous pouvez utiliser le même système de hooks de manière programmatique.

Installer failproofai dans votre projet

npm install failproofai

Configurer les hooks dans votre agent

Passez des commandes de hook lors de la création de votre processus d’agent. Les hooks se déclenchent de la même façon que dans Claude Code — via du JSON sur stdin/stdout :

failproofai --hook PreToolUse   # appelé avant chaque outil
failproofai --hook PostToolUse  # appelé après chaque outil

Écrire une politique personnalisée pour votre agent

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();
  },
});

Installer la politique personnalisée

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

Bloquer les commandes destructrices

La configuration la plus courante — empêcher les agents de causer des dommages irréversibles.

failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh

Ce que cela fait :

block-sudo — bloque toutes les commandes sudo
block-rm-rf — bloque la suppression récursive de fichiers
block-force-push — bloque git push --force
block-curl-pipe-sh — bloque l’exécution de scripts distants via un pipe vers le shell

Empêcher la fuite de secrets

Empêchez les agents de voir ou de divulguer des identifiants dans la sortie des outils.

failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens

Ces politiques se déclenchent sur PostToolUse — après l’exécution d’un outil, elles nettoient la sortie avant que l’agent ne la consulte.

Recevoir des alertes Slack lorsque les agents ont besoin d’attention

Utilisez le hook de notification pour transférer les alertes d’inactivité vers 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 {
      // ne jamais bloquer l'agent si Slack est inaccessible
    }

    return allow();
  },
});

Installez-le :

SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

Maintenir les agents sur une branche

Empêchez les agents de changer de branche ou de pousser vers des branches protégées.

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();
  },
});

Exiger des tests avant les commits

Rappeler aux agents d’exécuter les tests avant de faire un 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();
  },
});

Verrouiller un dépôt de production

Commitez une configuration au niveau du projet afin que tous les développeurs de votre équipe bénéficient des mêmes politiques. Créez .failproofai/policies-config.json dans votre dépôt :

{
  "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"]
    }
  }
}

Puis commitez-le :

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

Chaque membre de l’équipe ayant failproofai installé récupérera automatiquement ces règles.

Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

La configuration la plus impactante : commitez .failproofai/policies/ dans votre dépôt avec des politiques adaptées à votre projet. Tous les membres de l’équipe les récupèrent automatiquement — sans commandes d’installation ni modifications de configuration.

Créer le répertoire et ajouter des politiques

mkdir -p .failproofai/policies

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

// Enforce your team's preferred package manager
// (or enable the built-in prefer-package-manager policy instead)
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();
  },
});

// Remind the agent to run tests before committing
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();
  },
});

Commiter dans git

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

Continuer à améliorer

Au fil des nouveaux problèmes rencontrés par votre équipe, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain git pull. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe.

Plus d’exemples

Le répertoire examples/ du dépôt contient :

Fichier	Ce qu’il illustre
`policies-basic.js`	Politiques de base — blocage des écritures en production, des force-push et des scripts piped
`policies-notification.js`	Alertes Slack pour les notifications d’inactivité et la fin de session
`policies-advanced/index.js`	Imports transitifs, hooks asynchrones, nettoyage de la sortie PostToolUse, gestion de l’événement Stop

​Configurer des hooks pour Claude Code

​Configurer des hooks pour le Agents SDK

​Bloquer les commandes destructrices

​Empêcher la fuite de secrets

​Recevoir des alertes Slack lorsque les agents ont besoin d’attention

​Maintenir les agents sur une branche

​Exiger des tests avant les commits

​Verrouiller un dépôt de production

​Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

​Plus d’exemples