Getting started

title: Guida introduttiva description: “Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile” icon: rocket

Requisiti

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

Installazione

npm install -g failproofai

bun add -g failproofai

Avvio rapido

Abilita le policy

Le policy sono regole che vengono eseguite prima e dopo ogni chiamata di strumento dell’agent. Catturano comandi distruttivi, fughe di segreti e altri modi di fallimento prima che causino danni.

failproofai policies --install

Questo scrive voci di hook nei tuoi agent CLI installati (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, o il file ~/.hermes/config.yaml di Hermes). Quando è presente più di uno, ti verrà chiesto; passa --cli claude codex copilot cursor opencode pi hermes (qualsiasi sottoinsieme) per saltare la richiesta.Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode e Pi è in beta — installa con --cli copilot, --cli cursor, --cli opencode o --cli pi. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con ambito utente con --cli hermes ed è anche una fonte di audit offline.

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

Verifica

failproofai policies

Mostra ogni policy, se è abilitata e eventuali parametri configurati.

Avvia la dashboard

failproofai

Apre una dashboard locale su http://localhost:8020 dove puoi sfogliare le sessioni, ispezionare le chiamate di strumento e gestire le policy.

Esegui il tuo agent

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

Come funzionano le policy

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

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

Ogni policy restituisce una di tre decisioni:

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

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

Configura policy di team con policy basate su convenzione

Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione .failproofai/policies/. Inserisci file di policy in questa directory e vengono caricati automaticamente — nessun flag, nessun cambio di configurazione, nessun comando di installazione.

Crea la directory delle policy

mkdir -p .failproofai/policies

Aggiungi file di policy

Copia gli esempi iniziali 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();
  },
});

Fai il commit su git

git add .failproofai/policies/
git commit -m "Aggiungi policy di qualità del team"

Ogni membro del team che ha failproofai installato raccoglie automaticamente queste policy. 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 nuovi modi di fallimento, aggiungi policy e fai il push — ognuno riceve l’aggiornamento al prossimo git pull. Nel tempo queste policy diventano uno standard di qualità vivente che continua a migliorare.

Archiviazione dei dati

Tutta la configurazione e i log rimangono sulla tua macchina:

Percorso	Cosa archivia
`~/.failproofai/policies-config.json`	Configurazione globale delle policy
`~/.failproofai/hook-activity.jsonl`	Cronologia dell’esecuzione degli hook
`~/.failproofai/hook.log`	Log di debug per errori degli hook personalizzati
`.failproofai/policies-config.json`	Configurazione per progetto (committed)
`.failproofai/policies-config.local.json`	Personalizzazioni personali (gitignored)

Disinstallazione

failproofai policies --uninstall

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

Passaggi successivi

Configurazione

Ambiti e formato del file di configurazione

Policy integrate

Tutte le 26 policy con parametri

Policy personalizzate

Scrivi le tue policy in JavaScript

Monitor agent

Monitora le sessioni e rivedi l’attività delle policy

Per iniziare

Concetti chiave

CLI

Strumenti

Avanzato

Esempi

title: Guida introduttiva description: “Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile” icon: rocket

Requisiti

Installazione

Avvio rapido

Come funzionano le policy

Configura policy di team con policy basate su convenzione

Archiviazione dei dati

Disinstallazione

Passaggi successivi

Configurazione

Policy integrate

Policy personalizzate

Monitor agent

​title: Guida introduttiva description: “Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile” icon: rocket

​Requisiti

​Installazione

​Avvio rapido

​Come funzionano le policy

​Configura policy di team con policy basate su convenzione

​Archiviazione dei dati

​Disinstallazione

​Passaggi successivi

Configurazione

Policy integrate

Policy personalizzate

Monitor agent

title: Guida introduttiva description: “Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile” icon: rocket

Requisiti

Installazione

Avvio rapido

Come funzionano le policy

Configura policy di team con policy basate su convenzione

Archiviazione dei dati

Disinstallazione

Passaggi successivi