Claude Code Mods: was sie sind, und die Mod, die wir in jedem Agenten mitliefern

Am 1. Oktober 2026 erschien Claude Code 2.1.287 mit einem einzeiligen Changelog-Eintrag: "Added Claude Mods". Vier Tage später begann AgentsRoom, eine unserer Mods in die Claude-Agenten zu laden, die es ausführt.

Dieser Artikel erklärt, was eine Mod ist, was sie kann, das die älteren Erweiterungspunkte nicht konnten, wie du eine schreibst, lädst und testest, und was wir gelernt haben, als wir eine Mod in jeden Claude-Agenten eingebaut haben, den AgentsRoom startet. Die Angaben zu Claude Code stammen aus seiner Dokumentation und seinem Changelog, gelesen am 9. November 2026, mit installiertem Claude Code 2.1.318.

Die kurze Antwort. Eine Mod ist ein Claude Code Plugin mit einem hooks module: einer JavaScript- oder TypeScript-Datei, deren Funktionen Claude Code aus seinem eigenen Prozess heraus aufruft, wenn ein Event eintritt. Eine Funktion kann das Event durchlassen, es ändern oder es anstelle von Claude Code beantworten. So zeichnet eine Mod ein Panel, fügt einen Befehl hinzu oder stoppt einen Shell-Befehl, bevor er läuft.

Was eine Mod ist

Claude Code hatte schon Plugins: einen Ordner mit einem Manifest unter .claude-plugin/plugin.json, der Skills, Subagenten, Settings-Hooks und MCP-Server bündelt, damit sie sich als eine Einheit installieren. Eine Mod ist ein weiteres Element, das ein Plugin enthalten kann. Wenn die Datei hooks/hooks.json des Plugins unter ihrem Schlüssel modules eine Code-Datei nennt, lädt Claude Code diese Datei und ruft die Funktion register auf, die sie exportiert. Das Plugin heißt dann Mod.

Innerhalb von register hängt jeder Aufruf von on(event, hook) eine Funktion an ein Event: tool.call bevor ein Tool läuft, prompt.submit wenn du einen Prompt abschickst, session.start, command.run für einen Slash-Befehl, ui.render wenn Claude Code einen Teil seines Bildschirms zeichnet, und weitere. Jeder Hook bekommt drei Dinge:

• $, die Mods-API: alles, was eine Mod außerhalb ihres eigenen Codes tun kann, etwa $.ui, $.command, $.fs, $.process oder $.http.
• e, das Event, als einfache Daten: bei einem Tool-Aufruf der Name des Tools und seine Argumente.
• next, das das Event an die anderen Mods und dann an das eigene Verhalten von Claude Code weitergibt und das Ergebnis zurückliefert.

Was der Hook mit next macht, entscheidet, was passiert. Gibst du next(e) zurück, hast du nur beobachtet. Rufst du next mit einer geänderten Kopie von e auf, hast du das Event umgeschrieben. Gibst du dein eigenes Ergebnis zurück, ohne next aufzurufen, hast du es beantwortet: Das Tool läuft nie, oder Claude Code zeichnet seine eigene Version nie.

Die Dokumentation nennt diese Funktionen ebenfalls Hooks. Es sind nicht die Hooks, die du in settings.json schreibst und die Claude Code inzwischen Settings-Hooks nennt.

Mod, Settings-Hook, Skill oder MCP-Server

Die vier überschneiden sich, und die Mod ist die schwerste davon. Nimm die leichteste, die die Aufgabe erledigt.

Ein Plugin kann alle vier enthalten, eine Mod kann also zusammen mit dem Skill und dem MCP-Server ausgeliefert werden, mit denen sie arbeitet.

Die drei Dateien einer Mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json ist das übliche Plugin-Manifest: ein Name, eine Version, eine Beschreibung. hooks.json zeigt auf den Code, { "modules": ["./register.ts"] }, ein einziger Pfad, relativ zu dieser Datei. register.ts ist das hooks module. Claude Code lädt .js und .ts direkt, ohne Bundler und ohne Build-Schritt, und der einzige erlaubte nackte Import ist claude-code, für die Typen und ein paar Hilfsfunktionen.

Die Mod, die wir mitliefern: Wer hat diese Datei geändert?

AgentsRoom führt mehrere Coding-Agenten auf demselben Repository aus und zeigt im Tab Änderungen, welcher Agent welche Datei geändert hat, damit du die Arbeit jedes Agenten einzeln prüfen und committen kannst. Dateien, die mit Claudes Tools Edit und Write geschrieben wurden, waren einfach: Claude Code meldet sie über einen Settings-Hook. Dateien, die ein Shell-Befehl geschrieben hat, nicht. Ein sed -i, ein Heredoc, ein Codemod oder ein rm geht nie über ein Datei-Tool.

Vor den Mods haben wir geraten. AgentsRoom las das Session-Transkript des Agenten, um zu erfahren, wann jeder Bash-Befehl begann und endete, und verglich dann den Änderungszeitpunkt der Datei mit diesen Zeitfenstern. Das klappte meistens und scheiterte auf drei Arten, die wir benennen konnten:

• eine gelöschte Datei hat keinen Änderungszeitpunkt mehr, eine Löschung wurde also nie zugeordnet;
• ein reiner Lesebefehl wie grep öffnete ein Zeitfenster, in dem der Agent alles Mögliche hätte schreiben können;
• alles hing vom Format des Transkripts ab, das Claude Code jederzeit ändern darf.

Eine Mod macht das Raten überflüssig. Unsere Mod agentsroom-changes hängt sich für die beiden Shell-Tools in tool.call ein. Direkt bevor der Befehl läuft, macht sie einen Snapshot des Repositorys (git status plus Größe und Änderungszeitpunkt jedes geänderten Pfads). Direkt danach macht sie einen zweiten. Die Pfade, die sich unterscheiden, sind das, was dieser Befehl geändert hat, Löschungen eingeschlossen, und die Mod schickt sie über einen lokalen HTTP-Endpunkt an die AgentsRoom Desktop-App. Ein Aufruf, den Claude Code selbst als reinen Lesezugriff kennzeichnet, beansprucht nichts.

Hier ist der Hook, gekürzt. Die vollständige Datei hat 177 Zeilen, die meisten davon für den Snapshot und seine Grenzen.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

Die Desktop-App kopiert die Mod in ihren eigenen Ordner und startet jeden Claude-Agenten mit claude --plugin-dir <that folder>, aber nur, wenn das installierte Claude Code 2.1.287 oder neuer ist. Wir haben sie am 5. Oktober 2026 mit AgentsRoom 1.201.0 ausgeliefert.

Was wir beim Ausliefern gelernt haben

Eine Mod darf den Nutzer nie einen Tool-Aufruf kosten. Unser Hook sitzt vor jedem Shell-Befehl, den Claude ausführt. Wirft er einen Fehler oder wartet er auf das Netzwerk, bleibt Claudes Arbeit stehen. Jeder Schritt ist abgesichert, jede Nachricht an die Desktop-App wird abgeschickt, ohne auf eine Antwort zu warten, und die einzige Wartezeit, die wir akzeptieren, sind zwei git status Snapshots, jeder auf 15 Sekunden begrenzt. Eine verlorene Nachricht kostet eine Zuordnung, nie den Befehl.

Nichts tun, wenn man nicht gebraucht wird. Die Mod liest eine Umgebungsvariable, die AgentsRoom für seine Agenten setzt. Fehlt sie, etwa weil jemand den Ordner in sein eigenes Setup kopiert hat, geht jeder Hook direkt zu next(e).

Ein mit --plugin-dir geladener Ordner wird überwacht. Claude Code lädt die Mod neu, wenn sich eine Datei in diesem Ordner ändert, und ein Neuladen führt register erneut aus. Das hat bestimmt, wie wir sie installieren: Die Desktop-App schreibt eine Datei der Mod nur, wenn sich ihr Inhalt geändert hat, denn ein blindes Überschreiben bei jedem Agentenstart würde die Mod in jeder bereits offenen Claude-Konsole neu laden.

Damit rechnen, dass sich die API bewegt. Events und Methoden können sich von Version zu Version ändern, und die Dokumentation sagt das selbst. Wenn eine Mod über --plugin-dir geladen wird, schreibt Claude Code die Typdeklarationen der laufenden Version nach .claude-plugin/types/; gegen diese prüfen wir unsere Typen, nicht gegen eine Webseite. Und wenn eine Version unsere Mod nicht mehr lädt, geht nichts kaputt: Die Mod meldet sich nie als bereit, und AgentsRoom fällt auf die alte Methode über das Transkript zurück.

Schreib deine eigene

Du hast zwei Wege hinein.

Claude fragen. Beschreibe in einer interaktiven Claude Code Session die Mod, die du willst ("zeig den aktuellen Git-Branch über dem Prompt an"). Claude nutzt einen eingebauten Skill, plugin-authoring, schreibt die Mod in einen Ordner nur für diese Session, und Claude Code fragt dich einmal, ob es die Mods einschalten soll, die Claude schreibt. Sag ja, und die Mod wird am Ende der Runde geladen und danach nach jeder Runde neu geladen, die sie ändert.

Die drei Dateien selbst schreiben, dann:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate gibt eine Zeile hooks: mit den Events aus, die dein Modul behandelt, und eine Zeile calls: mit jeder Methode der Mods-API, die es aufruft. Fehlt ein Event, das du behandeln wolltest, ruft Claude Code diesen Hook auch nicht auf. Die statische Analyse hat Regeln: Schreib jeden Aufruf voll aus ($.ui.toast(...), nie const ui = $.ui), übergib Event-Namen als String-Literale und importiere nur deine eigenen Dateien, über relative Pfade.

Um eine Mod zu teilen, behandle sie als das Plugin, das sie ist: Schick den Ordner weiter oder trag ihn in einen Marketplace ein (ein Repository mit einer .claude-plugin/marketplace.json), damit andere ihn mit /plugin install <name>@<marketplace> installieren.

Mods, die du heute schon lesen kannst

• In Claude Code eingebaut: /plugin, Tab Installed, Abschnitt Built-in. Darunter das Panel /diff und der Lader, der AGENTS.md als Projektanweisungen liest; deren Quellcode veröffentlicht Anthropic im Ordner mods des Repositorys anthropics/claude-code, samt ihren Tests. Ebenfalls eingebaut und ausgeschaltet, bis du es aktivierst: You should know, ein Nebenagent, der anzeigt, was dir oder Claude entgangen sein könnte.
• Die Beispiele von Anthropic, im Repository claude-code-playground: eine Prognose des Kontextfensters, über dem Prompt gezeichnet, eine Sperre, die einen riskanten Shell-Befehl zurückhält und zeigt, was er ändern würde, und ein Befehl /replay, der Schritt für Schritt durch die Änderungen der letzten Runde geht.
• Unsere, oben beschrieben: eine Mod ganz ohne Oberfläche, ein einziger Hook tool.call, eine gute Vorlage, wenn du Daten brauchst statt eines Panels.

Bevor du die Mod von jemand anderem installierst

Eine Mod läuft nicht in einer Sandbox. Sie läuft mit deinen Rechten: Sie kann deine Dateien lesen und schreiben, deine Umgebungsvariablen und Einstellungen lesen (API-Schlüssel eingeschlossen), Programme starten, Netzwerkanfragen stellen, jeden Prompt und jeden Tool-Aufruf sehen und einen Tool-Aufruf genehmigen, bevor du gefragt wirst. Wenn du die Sandbox von Claude Code eingeschaltet hast, deckt sie die Bash-Befehle ab, die Claude ausführt, nicht die Prozesse, die eine Mod startet.

Also lies, bevor du installierst. Klone die Mod und führe claude plugin validate auf dem Ordner aus: Die Zeilen hooks: und calls: sagen dir, worauf sie hört und was sie erreicht, ohne etwas auszuführen. Eine Mod, die nur eine Leiste über dem Prompt zeichnet, hat keinen Grund, $.http oder $.process aufzurufen. Um alle Mods zu stoppen, die du installiert hast, starte eine Session mit --safe-mode oder setze "disableAllHooks": true in ~/.claude/settings.json.

Wo Mods laufen

Eine Mod, die zeichnet, sollte prüfen, wo sie läuft, und dort, wo nichts gezeichnet wird, auf Text zurückfallen.

Mods in AgentsRoom

Du installierst nichts: Ab Claude Code 2.1.287 startet jeder Claude-Agent mit der Mod, und der Tab Änderungen zeigt die Dateien, die jeder seiner Shell-Befehle erstellt, geändert oder gelöscht hat, neben dem Agenten, der es getan hat. Mit einem älteren Claude Code ordnet AgentsRoom Schreibvorgänge der Shell weiterhin über das Transkript zu, wie bisher.

Dieselbe Idee läuft auch in anderen CLIs, wo es geht: oh-my-pi bekommt eine Erweiterung mit demselben Vertrag, und die anderen CLIs ordnen Schreibvorgänge der Shell weiter so zu wie bisher. Wenn du tiefer einsteigen willst in das, was Claude Code bei jedem Schritt offenlegt, behandelt unser Leitfaden zu Claude Code Hooks die Settings-Hooks, neben denen eine Mod sitzt.

Häufig gestellte Fragen

Was ist eine Mod in Claude Code?

Eine Mod ist ein Claude Code Plugin mit einem hooks module: einer JavaScript- oder TypeScript-Datei, deren Funktionen Claude Code aus seinem eigenen Prozess heraus aufruft, wenn etwas passiert, etwa ein Tool-Aufruf, ein abgeschickter Prompt oder ein Teil des Bildschirms, der gezeichnet wird. Jede Funktion kann das Event durchlassen, es ändern oder es selbst behandeln. Damit kann eine Mod ein Panel zeichnen, einen Befehl hinzufügen oder einen riskanten Shell-Befehl zurückhalten.

Welche Claude Code Version brauche ich für Mods?

Claude Code 2.1.287 oder neuer im Terminal, erschienen am 1. Oktober 2026, mit dem Changelog-Eintrag "Added Claude Mods". Der Tab Code der Claude Desktop App unterstützt sie ab 2.1.286. In der VS Code Erweiterung laufen die Hooks, und was eine Mod zeichnet, braucht die Erweiterung 2.1.299 oder neuer. Führe claude --version aus, um es zu prüfen.

Was ist der Unterschied zwischen einer Mod und einem Claude Code Hook?

Ein Hook in settings.json führt einen Shell-Befehl, eine HTTP-Anfrage oder einen Prompt aus, wenn ein Event eintritt, und zwar außerhalb von Claude Code. Die Hooks einer Mod sind Funktionen, die in Claude Code laufen. Sie können, was ein Settings-Hook nicht kann: in der Oberfläche zeichnen, einen Slash-Befehl hinzufügen, der ohne Claude-Runde läuft, einen Tool-Aufruf umschreiben oder beantworten, ohne das Tool auszuführen, und Zustand zwischen Hooks teilen.

Ist es sicher, Claude Code Mods zu installieren?

Eine Mod läuft nicht in einer Sandbox. Sie läuft mit deinen Rechten, kann deine Dateien und Umgebungsvariablen lesen, Programme starten, Netzwerkanfragen stellen und einen Tool-Aufruf genehmigen. Installiere Mods nur von Autoren, denen du vertraust, und führe vorher claude plugin validate auf dem Ordner aus: Es listet die Events, in die sich die Mod einhängt, und die Aufrufe, die sie macht, ohne sie auszuführen.

Wo finde ich Beispiele für Claude Code Mods?

Anthropic veröffentlicht den Quellcode einiger eingebauter Mods, etwa des Panels /diff und des Laders für AGENTS.md, im Ordner mods des Repositorys anthropics/claude-code, und Beispiel-Mods im Repository anthropics/claude-code-playground. Die Mod von AgentsRoom, die dieser Artikel beschreibt, ist eine vierte Art von Beispiel: eine Mod ohne Oberfläche, nur mit einem Hook tool.call.

Kann ich Mods abschalten?

Ja. Deaktiviere eine einzelne Mod im Tab Installed von /plugin, starte eine einzelne Session mit --safe-mode, oder setze disableAllHooks in ~/.claude/settings.json auf true, um alle Mods zu stoppen, die du installiert hast, zusammen mit deinen Settings-Hooks. --safe-mode und disableAllHooks lassen die eingebauten Mods weiterlaufen: Die schaltest du einzeln in /plugin ab.