> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Per iniziare
> Installa failproofai, abilita le politiche e lascia che i tuoi agenti funzionino in modo affidabile
## Requisiti
* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (facoltativo - necessario solo per compilare dal codice sorgente)
***
## Installazione
```bash npm theme={null}
npm install -g failproofai
```
```bash bun theme={null}
bun add -g failproofai
```
***
## Inizio rapido
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.
```bash theme={null}
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`.
```bash theme={null}
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
```
```bash theme={null}
failproofai policies
```
Mostra ogni politica, se è abilitata e tutti i parametri configurati.
```bash theme={null}
failproofai
```
Apre un dashboard locale all'indirizzo `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate agli strumenti e gestire le politiche.
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:
```text theme={null}
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.
```bash theme={null}
mkdir -p .failproofai/policies
```
Copia gli esempi di avvio o scrivi i tuoi:
```bash theme={null}
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
```
O creane uno nuovo:
```js theme={null}
// .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();
},
});
```
```bash theme={null}
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
```bash theme={null}
failproofai policies --uninstall
```
Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono mantenuti.
***
## Passaggi successivi
Ambiti e formato del file di configurazione
Tutte le 26 politiche con parametri
Scrivi le tue politiche in JavaScript
Monitora le sessioni e rivedi l'attività delle politiche