Hooks · DeutschlandGPT

Hooks sind Befehle, die die Desktop-App bei bestimmten Ereignissen eines Agent-Laufs in Code und Cowork auf Ihrem Rechner ausführt. Ein Hook kann zum Beispiel nach dem Bearbeiten einer Datei einen Formatierer starten oder vor einem Befehl prüfen, ob er laufen darf, und ihn verhindern.

Sie sehen und verwalten Hooks unter Einstellungen → Desktop-App → Hooks.

Hooks führen Befehle mit Ihren Rechten auf diesem Gerät aus. Geben Sie nur Befehle frei, die Sie verstehen.

Wo Hooks stehen

Hooks stehen im Abschnitt hooks derselben Dateien, die auch die Berechtigungsregeln tragen:

Datei	Gilt für
`.deutschlandgpt/settings.json`	das Projekt. Die Datei gehört ins Repository
`.deutschlandgpt/settings.local.json`	das Projekt, aber nur für Sie. Sie bleibt auf Ihrem Rechner
`~/.deutschlandgpt/settings.json`	Ihre eigenen Einstellungen, in allen Ordnern

Aufbau

Unter jedem Ereignis steht eine Liste von Einträgen, jeder mit einem matcher und den Befehlen, die laufen sollen. Dieses Beispiel formatiert jede Datei, die der Agent bearbeitet oder anlegt:

JSON

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.file_path | xargs npx prettier --write",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

matcher wählt die Werkzeuge aus. Leer oder * passt auf alle. Neben den Namen der App funktionieren auch die Kurznamen Bash, Edit, Write und Read. Werkzeuge von MCP-Servern beginnen mit mcp__.

Ein Befehl kann diese Felder zusätzlich tragen:

if: Der Befehl läuft nur, wenn der Aufruf auf diese Regel passt. Sie schreiben sie wie in den Berechtigungen, etwa runCommand(git *).
async: Mit true läuft der Befehl nebenher, und der Agent wartet nicht auf ihn.
onFailure: Mit "block" zählt ein fehlgeschlagener Befehl wie eine Blockade.

Wie ein Befehl läuft

Der Befehl bekommt die Daten des Ereignisses als JSON auf der Standardeingabe und läuft im Projektordner. Nach 60 Sekunden bricht die App ihn ab. Mit timeout setzen Sie ein anderes Zeitlimit, höchstens 600 Sekunden.

Was danach passiert, hängt vom Exit-Code ab:

Exit-Code	Folge
`0`	Der Lauf geht weiter. Gibt der Befehl JSON aus, wertet die App es aus
`2`	Der Hook blockiert. Die Fehlerausgabe (stderr) geht an das Modell
andere	Der Lauf geht weiter. Der Fehler erscheint nur in der Anzeige

Erlaubt ein Hook eine Aktion, wirkt das wie eine Erlauben-Regel: Die App fragt dafür nicht mehr nach. Verbote, Regeln mit Rückfrage, gefährliche Befehle, der Plan-Modus und Pfade außerhalb des geteilten Ordners führen trotzdem zu einer Rückfrage oder einer Sperre.

Ereignisse

Ereignis	Wann der Hook läuft
`PreToolUse`	bevor ein Werkzeug läuft. Hier kann ein Hook den Aufruf verhindern
`PostToolUse`	nachdem ein Werkzeug erfolgreich gelaufen ist
`PostToolUseFailure`	nachdem ein Werkzeug fehlgeschlagen ist
`PermissionRequest`	wenn die App um eine Freigabe bitten würde
`UserPromptSubmit`	wenn Sie eine Nachricht abschicken
`SessionStart`	wenn ein Dialog beginnt
`Stop`	wenn der Agent seinen Turn beenden will. Ein Stop-Hook hält das höchstens 8-mal hintereinander auf
`SubagentStop`	wenn ein Unteragent fertig ist
`PreCompact`	vor dem Verdichten mit `/compact`. Die automatische Verdichtung löst ihn nicht aus

Freigabe

Hooks aus Projektdateien laufen erst, wenn Sie sie freigegeben haben. Das geschieht pro Datei unter Einstellungen → Desktop-App → Hooks. Ändert sich der Abschnitt hooks einer Datei, etwa nach einem git pull oder weil der Agent die Datei bearbeitet hat, wartet sie erneut auf Ihre Freigabe. Ihre eigenen Einstellungen in ~/.deutschlandgpt/settings.json bestätigen Sie einmal, wenn sie außerhalb der App geändert wurden.

Projekt-Hooks und lokale Hooks laufen außerdem nur in einem Ordner, dem Sie ausdrücklich vertrauen. Das gilt genauso für die Berechtigungsregeln aus diesen Dateien. Ihr Vertrauen setzen Sie im Dateibaum: Rechtsklick auf den Ordner und Diesem Ordner vertrauen wählen.

Die Seite Hooks zeigt für jede Datei Ereignis, Matcher und Befehl wörtlich und dazu ihren Status: freigegeben, wartet auf Freigabe oder gesperrt. Darunter stehen die letzten Läufe mit Exit-Code und Dauer. Mit Freigabe zurückziehen stoppen Sie die Hooks einer Datei wieder. Warten Hooks auf Freigabe, zeigt die App das auch als Hinweis über dem Eingabefeld.

Diagnosen nach Änderungen

Mit Diagnosen nach Änderungen auf der Seite Hooks richten Sie pro geteiltem Ordner eine Typprüfung ein, die nach jeder Dateiänderung des Agenten auf Ihrem Rechner läuft. Liegt im Ordner eine tsconfig.json, ist das npx --no-install tsc --noEmit -p ., bei einer Cargo.toml cargo check --quiet --message-format short, bei beiden Dateien beides. Vor dem Einrichten zeigt die App die Befehle wörtlich. Mit Einrichten trägt sie einen PostToolUse-Hook in .deutschlandgpt/settings.local.json ein, der nur auf diesem Rechner bleibt, und gibt ihn zugleich frei. Findet die Prüfung Fehler, sieht der Agent die ersten 40 Zeilen im Ergebnis seiner Änderung und kann sie gleich beheben. Ohne Fehler bekommt er nichts zu sehen. Wie jeder lokale Hook läuft auch dieser nur in einem Ordner, dem Sie vertrauen.

Regeln Ihrer Organisation

Die Verwaltung Ihrer Organisation kann Hooks aus Projektordnern und Plugins mit eigenen Befehlen abschalten. Dann laufen auch Hooks nicht mehr, die Sie bereits freigegeben haben, und die Seite Hooks zeigt sie als gesperrt. In Organisationen mit Berufsgeheimnis (§ 203 StGB) sind Hooks aus Projektordnern anfangs ausgeschaltet.