> ## 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.
# Erste Schritte
> failproofai installieren, Richtlinien aktivieren und Agenten zuverlässig ausführen
## Voraussetzungen
* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (optional – nur beim Erstellen aus dem Quellcode erforderlich)
***
## Installation
```bash npm theme={null}
npm install -g failproofai
```
```bash bun theme={null}
bun add -g failproofai
```
***
## Schnellstart
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.
```bash theme={null}
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`.
```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
```
Zeigt alle Richtlinien, ob sie aktiviert sind und welche Parameter konfiguriert wurden.
```bash theme={null}
failproofai
```
Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem Sie Sitzungen durchsuchen, Werkzeugaufrufe untersuchen und Richtlinien verwalten können.
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:
```text theme={null}
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.
```bash theme={null}
mkdir -p .failproofai/policies
```
Kopieren Sie die Starter-Beispiele oder schreiben Sie eigene:
```bash theme={null}
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
```
Oder erstellen Sie eine neue:
```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("Run tests before committing.");
}
return allow();
},
});
```
```bash theme={null}
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
```bash theme={null}
failproofai policies --uninstall
```
Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in `~/.failproofai/` bleiben erhalten.
***
## Nächste Schritte
Geltungsbereiche und Konfigurationsdateiformat
Alle 26 Richtlinien mit Parametern
Eigene Richtlinien in JavaScript schreiben
Sitzungen überwachen und Richtlinienaktivitäten einsehen