Erste Schritte

Voraussetzungen

Node.js >= 20.9.0
Bun >= 1.3.0 (optional – nur zum Kompilieren aus dem Quellcode erforderlich)

Installation

npm install -g failproofai

bun add -g failproofai

Schnellstart

Richtlinien aktivieren

Richtlinien sind Regeln, die vor und nach jedem Agenten-Tool-Aufruf ausgeführt werden. Sie erkennen destruktive Befehle, den Abfluss von Geheimnissen und andere Fehlerquellen, bevor sie Schaden anrichten können.

failproofai policies --install

Damit werden Hook-Einträge in die installierten Agenten-CLIs geschrieben (Claude Codes ~/.claude/settings.json, OpenAI Codex’ ~/.codex/hooks.json, GitHub Copilot CLIs ~/.copilot/hooks/failproofai.json, Cursor Agents ~/.cursor/hooks.json, OpenCodes generiertem Plugin-Shim unter ~/.config/opencode/plugins/failproofai.mjs sowie einem Registrierungseintrag im plugin-Array von ~/.config/opencode/opencode.json, Pis ~/.pi/agent/settings.json oder Hermes’ ~/.hermes/config.yaml). Sind mehrere installiert, wirst du zur Auswahl aufgefordert; übergib --cli claude codex copilot cursor opencode pi hermes (beliebige Teilmenge), um die Abfrage zu überspringen.Unterstützung für GitHub Copilot CLI, Cursor Agent, OpenCode und Pi ist Beta – Installation mit --cli copilot, --cli cursor, --cli opencode oder --cli pi. Hermes (hermes-agent, ein Slack/Telegram-Gateway) wird im Benutzerbereich mit --cli hermes installiert und ist ebenfalls eine Offline-Auditquelle.

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

Überprüfen

failproofai policies

Zeigt alle Richtlinien, ihren Aktivierungsstatus und konfigurierte Parameter an.

Dashboard öffnen

failproofai

Öffnet ein lokales Dashboard unter http://localhost:8020, in dem du Sitzungen durchsuchen, Tool-Aufrufe einsehen und Richtlinien verwalten kannst.

Agenten starten

Starte Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und prüfe anschließend im Dashboard, was passiert ist.

So funktionieren Richtlinien

Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Subprozess auf:

Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout

Jede Richtlinie gibt eine von drei Entscheidungen zurück:

allow – der Agent fährt normal fort
deny – die Aktion wird blockiert, der Agent erfährt den Grund
instruct – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt

Richtlinien laufen in deinem lokalen Prozess. Es werden keine Daten an einen externen Dienst gesendet.

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Der schnellste Weg, einheitliche Qualitätsstandards im Team einzuführen, ist die .failproofai/policies/-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – keine Flags, keine Konfigurationsänderungen, keine Installationsbefehle.

Richtlinienverzeichnis erstellen

mkdir -p .failproofai/policies

Richtliniendateien hinzufügen

Kopiere die Beispieldateien oder schreibe eigene:

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

Oder erstelle eine neue:

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

In Git einchecken

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

Alle Teammitglieder, die failproofai installiert haben, erhalten diese Richtlinien automatisch. Kein individuelles Setup erforderlich.

Checke .failproofai/policies/ in dein Repository ein, damit das gesamte Team dieselben Standards verwendet. Wenn neue Fehlerquellen entdeckt werden, füge Richtlinien hinzu und pushe sie – alle erhalten das Update beim nächsten git pull. Im Laufe der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert.

Datenspeicherung

Alle Konfigurationen und Protokolle verbleiben auf deinem Rechner:

Pfad	Inhalt
`~/.failproofai/policies-config.json`	Globale Richtlinienkonfiguration
`~/.failproofai/hook-activity.jsonl`	Hook-Ausführungsverlauf
`~/.failproofai/hook.log`	Debug-Protokoll für benutzerdefinierte Hook-Fehler
`.failproofai/policies-config.json`	Projektbezogene Konfiguration (eingecheckt)
`.failproofai/policies-config.local.json`	Persönliche Überschreibungen (per gitignore ausgeschlossen)

Deinstallation

failproofai policies --uninstall

Entfernt Hook-Einträge aus ~/.claude/settings.json. Konfigurationsdateien in ~/.failproofai/ bleiben erhalten.

Nächste Schritte

Konfiguration

Geltungsbereiche und Konfigurationsdateiformat

Integrierte Richtlinien

Alle 26 Richtlinien mit Parametern

Benutzerdefinierte Richtlinien

Schreibe eigene Richtlinien in JavaScript

Agenten-Monitor

Sitzungen überwachen und Richtlinienaktivitäten einsehen

Kernkonzepte

CLI

Werkzeuge

Fortgeschritten

Beispiele

Erste Schritte

Voraussetzungen

Installation

Schnellstart

So funktionieren Richtlinien

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Datenspeicherung

Deinstallation

Nächste Schritte

Konfiguration

Integrierte Richtlinien

Benutzerdefinierte Richtlinien

Agenten-Monitor

​Voraussetzungen

​Installation

​Schnellstart

​So funktionieren Richtlinien

​Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

​Datenspeicherung

​Deinstallation

​Nächste Schritte

Konfiguration

Integrierte Richtlinien

Benutzerdefinierte Richtlinien

Agenten-Monitor

Voraussetzungen

Installation

Schnellstart

So funktionieren Richtlinien

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Datenspeicherung

Deinstallation

Nächste Schritte