Prise en main

Prérequis

Node.js >= 20.9.0
Bun >= 1.3.0 (optionnel - uniquement nécessaire pour compiler depuis les sources)

Installation

npm install -g failproofai

bun add -g failproofai

Démarrage rapide

Activer les politiques

Les politiques sont des règles qui s’exécutent avant et après chaque appel d’outil d’un agent. Elles interceptent les commandes destructrices, les fuites de secrets et autres modes de défaillance avant qu’ils ne causent des dommages.

failproofai policies --install

Cette commande inscrit des entrées de hook dans vos CLIs d’agents installés (le ~/.claude/settings.json de Claude Code, le ~/.codex/hooks.json d’OpenAI Codex, le ~/.copilot/hooks/failproofai.json de GitHub Copilot CLI, le ~/.cursor/hooks.json de Cursor Agent, le shim de plugin généré par OpenCode dans ~/.config/opencode/plugins/failproofai.mjs ainsi qu’une entrée dans le tableau plugin de ~/.config/opencode/opencode.json, le ~/.pi/agent/settings.json de Pi, ou le ~/.gemini/settings.json de Gemini CLI). Si plusieurs CLIs sont présents, vous serez invité à en sélectionner un ; passez --cli claude codex copilot cursor opencode pi gemini (ou tout sous-ensemble) pour ignorer cette invite.La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi et Gemini CLI est en bêta — installez avec --cli copilot, --cli cursor, --cli opencode, --cli pi ou --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

Vérifier

failproofai policies

Affiche toutes les politiques, leur état d’activation et les paramètres configurés.

Lancer le tableau de bord

failproofai

Ouvre un tableau de bord local à l’adresse http://localhost:8020 où vous pouvez parcourir les sessions, inspecter les appels d’outils et gérer les politiques.

Lancer votre agent

Démarrez Claude Code comme d’habitude. Si l’agent tente quelque chose de risqué, failproofai l’intercepte automatiquement. Laissez-le tourner sans surveillance et examinez ce qui s’est passé dans le tableau de bord.

Fonctionnement des politiques

À chaque fois qu’un agent exécute un outil, Claude Code appelle failproofai comme sous-processus :

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

Chaque politique retourne l’une des trois décisions suivantes :

allow - l’agent continue normalement
deny - l’action est bloquée et l’agent est informé de la raison
instruct - du contexte supplémentaire est ajouté au prompt de l’agent

Les politiques s’exécutent dans votre processus local. Rien n’est envoyé à un service distant.

Définir des politiques d’équipe avec les politiques par convention

La façon la plus rapide d’établir des standards de qualité au sein de votre équipe est la convention .failproofai/policies/. Déposez des fichiers de politiques dans ce répertoire et ils sont chargés automatiquement — pas d’options, pas de modifications de configuration, pas de commandes d’installation.

Créer le répertoire des politiques

mkdir -p .failproofai/policies

Ajouter des fichiers de politiques

Copiez les exemples de démarrage ou écrivez les vôtres :

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

Ou créez-en un nouveau :

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

Valider dans git

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

Chaque membre de l’équipe qui a failproofai installé récupère ces politiques automatiquement. Aucune configuration individuelle n’est nécessaire.

Committez .failproofai/policies/ dans votre dépôt pour que toute l’équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez des politiques et poussez-les — tout le monde reçoit la mise à jour au prochain git pull. Au fil du temps, ces politiques deviennent un standard de qualité vivant qui ne cesse de s’améliorer.

Stockage des données

Toute la configuration et les journaux restent sur votre machine :

Chemin	Contenu
`~/.failproofai/policies-config.json`	Configuration globale des politiques
`~/.failproofai/hook-activity.jsonl`	Historique d’exécution des hooks
`~/.failproofai/hook.log`	Journal de débogage pour les erreurs de hooks personnalisés
`.failproofai/policies-config.json`	Configuration par projet (commitée)
`.failproofai/policies-config.local.json`	Remplacements personnels (ignorés par git)

Désinstallation

failproofai policies --uninstall

Supprime les entrées de hook de ~/.claude/settings.json. Les fichiers de configuration dans ~/.failproofai/ sont conservés.

Étapes suivantes

Configuration

Portées et format des fichiers de configuration

Politiques intégrées

Les 26 politiques avec leurs paramètres

Politiques personnalisées

Écrivez vos propres politiques en JavaScript

Moniteur d'agent

Surveillez les sessions et examinez l’activité des politiques

Démarrage

Concepts clés

CLI

Outils

Avancé

Prérequis

Installation

Démarrage rapide

Fonctionnement des politiques

Définir des politiques d’équipe avec les politiques par convention

Stockage des données

Désinstallation

Étapes suivantes

Configuration

Politiques intégrées

Politiques personnalisées

Moniteur d'agent

​Prérequis

​Installation

​Démarrage rapide

​Fonctionnement des politiques

​Définir des politiques d’équipe avec les politiques par convention

​Stockage des données

​Désinstallation

​Étapes suivantes

Configuration

Politiques intégrées

Politiques personnalisées

Moniteur d'agent

Prérequis

Installation

Démarrage rapide

Fonctionnement des politiques

Définir des politiques d’équipe avec les politiques par convention

Stockage des données

Désinstallation

Étapes suivantes