Erste Schritte

Voraussetzungen

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

Installation

npm install -g failproofai

bun add -g failproofai

Schnellstart

Richtlinien aktivieren

Richtlinien sind Regeln, die vor und nach jedem Werkzeugaufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, den Abfluss von Geheimnissen und andere Fehlerquellen, bevor Schaden entsteht.

failproofai policies --install

Damit werden Hook-Einträge in die installierten Agent-CLIs geschrieben (Claude Code’s ~/.claude/settings.json, OpenAI Codex’s ~/.codex/hooks.json, GitHub Copilot CLI’s ~/.copilot/hooks/failproofai.json, Cursor Agent’s ~/.cursor/hooks.json, OpenCode’s generierter Plugin-Shim unter ~/.config/opencode/plugins/failproofai.mjs sowie ein Registrierungseintrag im plugin-Array von ~/.config/opencode/opencode.json, Pi’s ~/.pi/agent/settings.json oder Gemini CLI’s ~/.gemini/settings.json). Sind mehrere vorhanden, wird eine Auswahl angezeigt; übergeben Sie --cli claude codex copilot cursor opencode pi gemini (beliebige Teilmenge), um die Auswahl zu überspringen.Die Unterstützung für GitHub Copilot CLI, Cursor Agent, OpenCode, Pi und Gemini CLI befindet sich im Beta-Stadium – Installation mit --cli copilot, --cli cursor, --cli opencode, --cli pi oder --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

Überprüfen

failproofai policies

Zeigt alle Richtlinien, ob sie aktiviert sind und welche Parameter konfiguriert wurden.

Dashboard öffnen

failproofai

Öffnet ein lokales Dashboard unter http://localhost:8020, in dem Sie Sitzungen durchsuchen, Werkzeugaufrufe untersuchen und Richtlinien verwalten können.

Agenten starten

Starten Sie Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lassen Sie ihn unbeaufsichtigt laufen und überprüfen Sie anschließend im Dashboard, was passiert ist.

So funktionieren Richtlinien

Jedes Mal, wenn ein Agent ein Werkzeug aufruft, startet Claude Code failproofai als Unterprozess:

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 erhält eine Begründung
instruct – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt

Richtlinien werden in Ihrem lokalen Prozess ausgeführt. Es werden keine Daten an einen externen Dienst übertragen.

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Der schnellste Weg, teamweite Qualitätsstandards einzuführen, ist die .failproofai/policies/-Konvention. Legen Sie Richtliniendateien in dieses Verzeichnis, und sie werden automatisch geladen – ohne Flags, ohne Konfigurationsänderungen, ohne Installationsbefehle.

Richtlinienverzeichnis erstellen

mkdir -p .failproofai/policies

Richtliniendateien hinzufügen

Kopieren Sie die Starter-Beispiele oder schreiben Sie eigene:

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

Oder erstellen Sie 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"

Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Es ist keine individuelle Einrichtung pro Entwickler erforderlich.

Checken Sie .failproofai/policies/ in Ihr Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn Ihr Team neue Fehlerquellen entdeckt, fügen Sie Richtlinien hinzu und pushen Sie – alle erhalten das Update beim nächsten git pull. Mit der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert.

Datenspeicherung

Alle Konfigurationen und Protokolle verbleiben auf Ihrem 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`	Projektspezifische 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

Eigene Richtlinien in JavaScript schreiben

Agentenmonitor

Sitzungen überwachen und Richtlinienaktivitäten einsehen

Kernkonzepte

CLI

Werkzeuge

Fortgeschritten

Erste Schritte

Voraussetzungen

Installation

Schnellstart

So funktionieren Richtlinien

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Datenspeicherung

Deinstallation

Nächste Schritte

Konfiguration

Integrierte Richtlinien

Benutzerdefinierte Richtlinien

Agentenmonitor

​Voraussetzungen

​Installation

​Schnellstart

​So funktionieren Richtlinien

​Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

​Datenspeicherung

​Deinstallation

​Nächste Schritte

Konfiguration

Integrierte Richtlinien

Benutzerdefinierte Richtlinien

Agentenmonitor

Voraussetzungen

Installation

Schnellstart

So funktionieren Richtlinien

Team-Richtlinien mit konventionsbasierten Richtlinien einrichten

Datenspeicherung

Deinstallation

Nächste Schritte