Claude Code settings.json: die Datei, die konfiguriert, was dein Agent tut

settings.json ist keine Einstellungsdatei. Hier wird das Verhalten deines Agenten konfiguriert. Themes und Modellauswahl liegen auch dort, aber das ist der langweilige Teil. Wirklich wichtig ist der eine Block, der ändert, was der Agent tut, nicht wie er aussieht. Das hier ist die Kurzfassung der Datei, auf die es ankommt.

Wo die Datei Claude Code settings.json liegt

An drei Orten, und die Rangfolge ist der ganze Punkt. .claude/settings.local.json in deinem Projekt (gitignored, nur für dich auf diesem Rechner) gewinnt zuerst. Danach kommt die im Repo committete .claude/settings.json, die sich das Team teilt. Zuletzt ~/.claude/settings.json, dein globaler Standard überall. Die spezifischere Datei überschreibt die allgemeineren, Key für Key.

Diese Aufteilung folgt derselben Disziplin wie bei einer CLAUDE.md-Datei. Persönliches bleibt lokal, Gemeinsames wird committet, und die maschinenspezifischen Teile landen nie in Git. Wenn die Rangfolge stimmt, kämpfst du nicht mehr gegen deine eigene Konfiguration.

Der einzige Block, der das Verhalten ändert, ist hooks

Jeder andere Key in settings.json regelt Optik oder Zugriff: Theme, Modell, Berechtigungen, Statuszeile. Der hooks-Block ist anders. Er verknüpft ein Lifecycle-Event mit einem Shell-Befehl, den Claude Code in genau diesem Moment automatisch ausführt. Das ist der einzige Teil der Datei, der den Agenten zum Handeln bringt, also der einzige Teil, der ein genaues Studium verdient. Wie das im Detail funktioniert, steht unter wie Hooks funktionieren.

Ein Hook-Eintrag hat genau eine Form. Unser Installer schreibt ihn so, und du solltest das auch tun:

{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "node safety-guard.mjs" }] }

Der matcher entscheidet, welche Tool-Aufrufe den Hook auslösen. Lässt du ihn weg, feuert das Event bedingungslos. Der command ist einfach ein Shell-String, ein Hook kann also jedes Skript in jeder Sprache sein. Mehr Vertrag gibt es nicht.

Was kitstarter in die settings.json einbaut, Event für Event

Der Installer von kitstarter generiert den gesamten hooks-Block für dich, einen Eintrag pro Lifecycle-Event. Hier ist die echte Event-zu-Skript-Tabelle, die er schreibt, direkt aus dem Wiring-Code. Nichts erfunden, genau das wird ausgeliefert.

Lies die Matcher genau, denn dort steckt das Design. Safety-guard hört nur auf Bash und bremst deshalb nie eine Bearbeitung aus. Clarity hört auf alle vier Edit-Tools plus das Absenden des Prompts, denn ein Build kann von jedem davon ausgehen. Slop-check hört auf Edit|Write, denn genau dann ändert sich eine Datei auf der Festplatte.

Was ein verdrahteter Hook tatsächlich tut

Jedes Skript ist klein und arbeitet nach dem Prinzip „fail open“: Bei einem Fehler verstummt es, statt deine Arbeit zu blockieren. safety-guard.mjs liest den anstehenden Bash-Befehl und gleicht ihn mit einer Liste destruktiver Muster ab: rekursives Löschen eines Root- oder Home-Pfads, Force-Push, Hard-Reset, das Droppen einer Tabelle. Es warnt, es blockiert nie. Ein Kit, das deine Befehle hart blockiert, wird deinstalliert.

slop-check.mjs feuert nach einer Bearbeitung an einer UI-Datei. Es lässt den Slop-Detektor über genau diese eine Datei laufen und reicht gefundene Anzeichen als Kontext weiter, den der Agent beheben muss, bevor er weitermacht. Beide Hooks werden von nichts weiter ausgelöst als von einem Eintrag im hooks-Block. Das ist die Hebelwirkung, die dir diese Datei gibt.

Hilft es wirklich, die settings.json so zu verdrahten?

Ja, bei den Dingen, auf die es ankommt, und wir haben ehrlich gemessen. In unserem Cleanroom-Benchmark gegen das nackte Claude Code fragte das Kit bei 5 von 5 Aufgaben nach, bevor es baute, gegenüber 2 von 5 ohne Kit. Es lieferte rund 40% weniger Code für dasselbe Ergebnis und drückte die Slop-Anzeichen bei einer Debugging-Spirale von 5 auf 0, wo ohne Kit fünf stehen blieben.

Die Verluste sind real und wir verstecken sie nicht, das ist Hausregel. Bei einer ohnehin einfachen Todo-App war das Kit etwa doppelt so langsam und rund 75% teurer bei fast identischem Ergebnis, und über die ganze Suite hinweg kostet der Hook-Kontext im Schnitt etwa 25% mehr, bezahlt aus deinem bestehenden Abo. Hooks sind nicht gratis. Bei vagen Prompts zahlen sie sich durch vermiedene Nacharbeit aus, bei ohnehin klaren sind sie Overhead.

Schreib deine eigenen, oder starte mit welchen, die funktionieren

Der Mechanismus ist simpel: Event wählen, Skript schreiben, einen Eintrag hinzufügen. Schwierig ist das Urteil: auf welche Matcher du hörst, wann du warnst statt zu blockieren, wie du „fail open“ sicherstellst, damit ein Hook nie eine Session aufhängt. Genau das ist kitstarter: eine abgestimmte settings.json und die Skripte dahinter, für dich generiert und sofort einsatzbereit. Bau dir mit der Tabelle oben deine eigenen, oder installiere welche, die ihre Kosten schon einspielen.