> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Erste Schritte

> Installiere failproofai, aktiviere Richtlinien und lass deine Agenten zuverlässig arbeiten

## Voraussetzungen

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

***

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## Schnellstart

<Steps>
  <Step title="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.

    ```bash theme={null}
    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.

    ```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 hermes --scope user
    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
    ```
  </Step>

  <Step title="Überprüfen">
    ```bash theme={null}
    failproofai policies
    ```

    Zeigt alle Richtlinien, ihren Aktivierungsstatus und konfigurierte Parameter an.
  </Step>

  <Step title="Dashboard öffnen">
    ```bash theme={null}
    failproofai
    ```

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

  <Step title="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.
  </Step>
</Steps>

***

## So funktionieren Richtlinien

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

```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 erfährt den Grund
* **instruct** – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt

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

***

## 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.

<Steps>
  <Step title="Richtlinienverzeichnis erstellen">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="Richtliniendateien hinzufügen">
    Kopiere die Beispieldateien oder schreibe eigene:

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    Oder erstelle 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();
      },
    });
    ```
  </Step>

  <Step title="In Git einchecken">
    ```bash theme={null}
    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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## 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

```bash theme={null}
failproofai policies --uninstall
```

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

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Konfiguration" icon="gear" href="/de/configuration">
    Geltungsbereiche und Konfigurationsdateiformat
  </Card>

  <Card title="Integrierte Richtlinien" icon="shield" href="/de/built-in-policies">
    Alle 26 Richtlinien mit Parametern
  </Card>

  <Card title="Benutzerdefinierte Richtlinien" icon="code" href="/de/custom-policies">
    Schreibe eigene Richtlinien in JavaScript
  </Card>

  <Card title="Agenten-Monitor" icon="chart-line" href="/de/dashboard">
    Sitzungen überwachen und Richtlinienaktivitäten einsehen
  </Card>
</CardGroup>