Démarrage

Prérequis

Node.js >= 20.9.0
Bun >= 1.3.0 (optionnel - nécessaire uniquement pour la compilation 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’agent. Elles interceptent les commandes destructrices, les fuites de secrets et d’autres modes d’échec avant qu’ils ne causent des dommages.

failproofai policies --install

Cette commande inscrit des entrées de hook dans vos CLIs d’agent 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 à ~/.config/opencode/plugins/failproofai.mjs ainsi qu’une entrée d’enregistrement dans le tableau plugin de ~/.config/opencode/opencode.json, le ~/.pi/agent/settings.json de Pi, ou le ~/.hermes/config.yaml de Hermes). Si plusieurs sont présents, une invite s’affichera ; passez --cli claude codex copilot cursor opencode pi hermes (tout sous-ensemble) pour ignorer l’invite.La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode et Pi est en bêta — installez avec --cli copilot, --cli cursor, --cli opencode ou --cli pi. Hermes (hermes-agent, une passerelle Slack/Telegram) s’installe en portée utilisateur avec --cli hermes et constitue également une source d’audit hors ligne.

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

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.

Exécuter 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 consultez 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 en tant que 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é à l’invite de l’agent

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

Configurer les politiques d’équipe avec les politiques basées sur les conventions

La manière la plus rapide d’établir des standards de qualité au sein de votre équipe est la convention .failproofai/policies/. Déposez des fichiers de politique dans ce répertoire et ils sont chargés automatiquement — sans indicateurs, sans modifications de configuration, sans commandes d’installation.

Créer le répertoire des politiques

mkdir -p .failproofai/policies

Ajouter des fichiers de politique

Copiez les exemples de démarrage ou rédigez 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 ayant failproofai installé récupère ces politiques automatiquement. Aucune configuration par développeur n’est nécessaire.

Validez .failproofai/policies/ dans votre dépôt afin que toute l’équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes d’échec, ajoutez des politiques et poussez — 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 (validée dans git)
`.failproofai/policies-config.local.json`	Substitutions personnelles (ignorées 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

Concepts clés

CLI

Outils

Avancé

Exemples

Démarrage

Prérequis

Installation

Démarrage rapide

Fonctionnement des politiques

Configurer les politiques d’équipe avec les politiques basées sur les conventions

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

​Configurer les politiques d’équipe avec les politiques basées sur les conventions

​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

Configurer les politiques d’équipe avec les politiques basées sur les conventions

Stockage des données

Désinstallation

Étapes suivantes