Vai al contenuto principale

​
Requisiti

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

​
Installazione

npm install -g failproofai

​
Inizio rapido

1

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
2

Verifica

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

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.
4

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.
1

Crea la directory delle politiche

mkdir -p .failproofai/policies
2

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

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:
PercorsoCosa contiene
~/.failproofai/policies-config.jsonConfigurazione della politica globale
~/.failproofai/hook-activity.jsonlCronologia dell’esecuzione degli hook
~/.failproofai/hook.logLog di debug per gli errori degli hook personalizzati
.failproofai/policies-config.jsonConfigurazione per progetto (sottoposta a commit)
.failproofai/policies-config.local.jsonOverride 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