Per iniziare

Requisiti

Node.js >= 20.9.0
Bun >= 1.3.0 (facoltativo - necessario solo per compilare dal codice sorgente)

Installazione

npm install -g failproofai

bun add -g failproofai

Inizio rapido

Abilita le politiche

Le politiche sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell’agente. Intercettano i comandi distruttivi, la fuga di segreti e altre modalità di guasto prima che causino danni.

failproofai policies --install

Questo scrive voci di hook nelle CLI dell’agente installate (il file ~/.claude/settings.json di Claude Code, il file ~/.codex/hooks.json di OpenAI Codex, il file ~/.copilot/hooks/failproofai.json di GitHub Copilot CLI, il file ~/.cursor/hooks.json di Cursor Agent, lo shim del plugin generato di OpenCode in ~/.config/opencode/plugins/failproofai.mjs più una voce di registrazione nell’array plugin di ~/.config/opencode/opencode.json, il file ~/.pi/agent/settings.json di Pi, oppure il file ~/.gemini/settings.json di Gemini CLI). Quando è presente più di uno, ti verrà chiesto di scegliere; passa --cli claude codex copilot cursor opencode pi gemini (qualsiasi sottoinsieme) per saltare la richiesta.Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI è in fase beta — installa con --cli copilot, --cli cursor, --cli opencode, --cli pi, oppure --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

Verifica

failproofai policies

Mostra ogni politica, se è abilitata e tutti i parametri configurati.

Avvia il dashboard

failproofai

Apre un dashboard locale all’indirizzo http://localhost:8020 dove puoi sfogliare le sessioni, ispezionare le chiamate agli strumenti e gestire le politiche.

Esegui il tuo agente

Avvia Claude Code come di solito. Se l’agente prova a fare qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nel dashboard.

Come funzionano le politiche

Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come sottoprocesso:

Claude Code  →  failproofai --hook PreToolUse  →  legge JSON da stdin
                                                 valuta le politiche
                                                 scrive la decisione su stdout

Ogni politica restituisce una di tre decisioni:

allow - l’agente procede normalmente
deny - l’azione viene bloccata, all’agente viene spiegato il motivo
instruct - contesto aggiuntivo viene aggiunto al prompt dell’agente

Le politiche vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto.

Configura politiche di team con politiche basate su convenzione

Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione .failproofai/policies/. Inserisci i file delle politiche in questa directory e verranno caricati automaticamente — senza flag, senza modifiche di configurazione, senza comandi di installazione.

Crea la directory delle politiche

mkdir -p .failproofai/policies

Aggiungi file di politiche

Copia gli esempi di avvio o scrivi i tuoi:

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

O creane uno nuovo:

// .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("Esegui i test prima di fare il commit.");
    }
    return allow();
  },
});

Esegui il commit su git

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

Ogni membro del team che ha failproofai installato raccoglie automaticamente queste politiche. Nessuna configurazione per sviluppatore necessaria.

Fai il commit di .failproofai/policies/ nel tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuove modalità di guasto, aggiungi politiche e fai il push — tutti riceveranno l’aggiornamento al prossimo git pull. Nel tempo, queste politiche diventano uno standard di qualità che migliora continuamente.

Archiviazione dei dati

Tutti i file di configurazione e i log rimangono sulla tua macchina:

Percorso	Cosa contiene
`~/.failproofai/policies-config.json`	Configurazione della politica globale
`~/.failproofai/hook-activity.jsonl`	Cronologia dell’esecuzione degli hook
`~/.failproofai/hook.log`	Log di debug per gli errori degli hook personalizzati
`.failproofai/policies-config.json`	Configurazione per progetto (sottoposta a commit)
`.failproofai/policies-config.local.json`	Override personali (ignorato da git)

Disinstallazione

failproofai policies --uninstall

Rimuove le voci di hook da ~/.claude/settings.json. I file di configurazione in ~/.failproofai/ vengono mantenuti.

Passaggi successivi

Configurazione

Ambiti e formato del file di configurazione

Politiche integrate

Tutte le 26 politiche con parametri

Politiche personalizzate

Scrivi le tue politiche in JavaScript

Monitoraggio agenti

Monitora le sessioni e rivedi l’attività delle politiche

Concetti chiave

CLI

Strumenti

Avanzato

Per iniziare

Requisiti

Installazione

Inizio rapido

Come funzionano le politiche

Configura politiche di team con politiche basate su convenzione

Archiviazione dei dati

Disinstallazione

Passaggi successivi

Configurazione

Politiche integrate

Politiche personalizzate

Monitoraggio agenti

​Requisiti

​Installazione

​Inizio rapido

​Come funzionano le politiche

​Configura politiche di team con politiche basate su convenzione

​Archiviazione dei dati

​Disinstallazione

​Passaggi successivi

Configurazione

Politiche integrate

Politiche personalizzate

Monitoraggio agenti

Requisiti

Installazione

Inizio rapido

Come funzionano le politiche

Configura politiche di team con politiche basate su convenzione

Archiviazione dei dati

Disinstallazione

Passaggi successivi