Claude Code mods: wat ze zijn, en de mod die we in elke agent meeleveren

Op 1 oktober 2026 verscheen Claude Code 2.1.287 met een changelog van één regel: "Added Claude Mods". Vier dagen later begon AgentsRoom een van onze mods te laden in de Claude-agents die het laat draaien.

Dit artikel legt uit wat een mod is, wat hij kan dat de oudere uitbreidingspunten niet konden, hoe je er een schrijft, laadt en test, en wat we hebben geleerd door een mod mee te leveren in elke Claude-agent die AgentsRoom start. De feiten over Claude Code komen uit de documentatie en de changelog, gelezen op 9 november 2026, met Claude Code 2.1.318 geïnstalleerd.

Het korte antwoord. Een mod is een Claude Code plugin met een hooks module: een JavaScript- of TypeScript-bestand waarvan Claude Code de functies vanuit zijn eigen proces aanroept wanneer er een event plaatsvindt. Een functie kan het event doorlaten, het wijzigen of het beantwoorden in plaats van Claude Code. Zo tekent een mod een paneel, voegt hij een commando toe of houdt hij een shell-commando tegen voordat het draait.

Wat een mod is

Claude Code had al plugins: een map met een manifest in .claude-plugin/plugin.json die skills, subagents, settings-hooks en MCP-servers bundelt zodat ze als één geheel installeren. Een mod is nog iets wat een plugin kan bevatten. Wanneer het bestand hooks/hooks.json van de plugin onder de sleutel modules een codebestand noemt, laadt Claude Code dat bestand en roept het de functie register aan die het exporteert. De plugin heet dan een mod.

Binnen register koppelt elke aanroep van on(event, hook) een functie aan een event: tool.call voordat een tool draait, prompt.submit wanneer je een prompt verstuurt, session.start, command.run voor een slash-commando, ui.render wanneer Claude Code een deel van zijn scherm tekent, en meer. Elke hook krijgt drie dingen:

• $, de mods-API: alles wat een mod buiten zijn eigen code kan doen, zoals $.ui, $.command, $.fs, $.process of $.http.
• e, het event, als gewone data: bij een toolaanroep de naam van de tool en zijn argumenten.
• next, dat het event doorgeeft aan de andere mods en daarna aan het eigen gedrag van Claude Code, en het resultaat teruggeeft.

Wat de hook met next doet, bepaalt wat er gebeurt. Geef je next(e) terug, dan heb je alleen gekeken. Roep je next aan met een gewijzigde kopie van e, dan heb je het event herschreven. Geef je je eigen resultaat terug zonder next aan te roepen, dan heb je het beantwoord: de tool draait nooit, of Claude Code tekent zijn eigen versie nooit.

De documentatie noemt deze functies ook hooks. Het zijn niet de hooks die je in settings.json schrijft, die Claude Code nu settings-hooks noemt.

Mod, settings-hook, skill of MCP-server

De vier overlappen, en de mod is de zwaarste. Kies de lichtste die het werk doet.

Een plugin kan ze alle vier bevatten, dus een mod kan worden meegeleverd naast de skill en de MCP-server waarmee hij werkt.

De drie bestanden van een mod

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

plugin.json is het gebruikelijke manifest van een plugin: een naam, een versie, een beschrijving. hooks.json wijst naar de code, { "modules": ["./register.ts"] }, één pad, relatief ten opzichte van dat bestand. register.ts is de hooks module. Claude Code laadt .js en .ts rechtstreeks, zonder bundler en zonder buildstap, en de enige kale import die is toegestaan is claude-code, voor de types en een paar hulpfuncties.

De mod die we meeleveren: wie heeft dit bestand gewijzigd?

AgentsRoom laat meerdere code-agents op dezelfde repository draaien en toont in het tabblad Wijzigingen welke agent welk bestand heeft gewijzigd, zodat je het werk van elke agent apart kunt nakijken en committen. Bestanden die met de tools Edit en Write van Claude zijn geschreven, waren makkelijk: Claude Code meldt ze via een settings-hook. Bestanden die door een shell-commando zijn geschreven, niet. Een sed -i, een heredoc, een codemod of een rm gaat nooit via een bestandstool.

Vóór de mods gokten we. AgentsRoom las het sessietranscript van de agent om te weten wanneer elk Bash-commando begon en eindigde, en vergeleek daarna de wijzigingstijd van het bestand met die tijdvensters. Dat werkte meestal, en het faalde op drie manieren die we konden benoemen:

• een verwijderd bestand heeft geen wijzigingstijd meer, dus een verwijdering werd nooit toegewezen;
• een commando dat alleen leest, zoals grep, opende een tijdvenster waarin de agent van alles had kunnen schrijven;
• alles hing af van het formaat van het transcript, dat Claude Code vrij mag veranderen.

Een mod maakt het gokken overbodig. Onze mod agentsroom-changes haakt in op tool.call voor de twee shell-tools. Vlak voordat het commando draait, maakt hij een snapshot van de repository (git status plus de grootte en wijzigingstijd van elk gewijzigd pad). Vlak erna maakt hij een tweede. De paden die verschillen zijn wat dat commando heeft veranderd, verwijderingen inbegrepen, en de mod stuurt ze via een lokaal HTTP-endpoint naar de desktop-app van AgentsRoom. Een aanroep die Claude Code zelf als alleen-lezen markeert, claimt niets.

Hier is de hook, ingekort. Het volledige bestand telt 177 regels, de meeste voor de snapshot en zijn 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
  });
};

De desktop-app kopieert de mod naar zijn eigen map en start elke Claude-agent met claude --plugin-dir <that folder>, alleen als de geïnstalleerde Claude Code 2.1.287 of nieuwer is. We hebben hem uitgebracht in AgentsRoom 1.201.0, op 5 oktober 2026.

Wat we leerden bij het uitbrengen

Een mod mag de gebruiker nooit een toolaanroep kosten. Onze hook staat voor elk shell-commando dat Claude uitvoert. Als hij een fout gooit, of op het netwerk wacht, stopt het werk van Claude. Elke stap is beveiligd, elk bericht naar de desktop-app wordt verstuurd zonder op antwoord te wachten, en de enige wachttijd die we accepteren zijn twee git status snapshots, elk begrensd op 15 seconden. Een verloren bericht kost één toewijzing, nooit het commando.

Niets doen als je niet gevraagd bent. De mod leest een omgevingsvariabele die AgentsRoom voor zijn agents zet. Ontbreekt die, bijvoorbeeld omdat iemand de map naar zijn eigen setup heeft gekopieerd, dan gaat elke hook meteen door naar next(e).

Een map die met --plugin-dir is geladen, wordt in de gaten gehouden. Claude Code herlaadt de mod wanneer een bestand in die map verandert, en een herlaadactie voert register opnieuw uit. Dat bepaalde hoe we hem installeren: de desktop-app schrijft een bestand van de mod alleen als de inhoud is veranderd, want blind overschrijven bij elke start van een agent zou de mod herladen in elke Claude-console die al open staat.

Reken erop dat de API verschuift. De events en methodes kunnen tussen releases veranderen, en de documentatie zegt dat zelf. Wanneer een mod vanuit --plugin-dir wordt geladen, schrijft Claude Code de typedeclaraties van de draaiende versie naar .claude-plugin/types/; daartegen controleren wij de types, niet tegen een webpagina. En als een build onze mod niet meer laadt, gaat er niets kapot: de mod meldt zich nooit als klaar, en AgentsRoom valt terug op de oude methode via het transcript.

Schrijf je eigen mod

Je hebt twee ingangen.

Vraag het aan Claude. Beschrijf in een interactieve Claude Code sessie de mod die je wilt ("toon de huidige git-branch boven de prompt"). Claude gebruikt een ingebouwde skill, plugin-authoring, schrijft de mod in een map voor die sessie, en Claude Code vraagt je één keer of het de mods die Claude schrijft moet inschakelen. Zeg ja en de mod laadt aan het einde van de beurt, en herlaadt daarna na elke beurt die hem wijzigt.

Schrijf de drie bestanden zelf, en daarna:

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 toont een regel hooks: met de events die je module afhandelt en een regel calls: met elke methode van de mods-API die hij aanroept. Ontbreekt een event dat je wilde afhandelen, dan roept Claude Code die hook ook niet aan. De statische analyse heeft regels: schrijf elke aanroep voluit ($.ui.toast(...), nooit const ui = $.ui), geef eventnamen door als string-literals, en importeer alleen je eigen bestanden, via een relatief pad.

Om een mod te delen, behandel je hem als de plugin die hij is: stuur de map door, of zet hem in een marketplace (een repository met een .claude-plugin/marketplace.json) zodat anderen hem installeren met /plugin install <name>@<marketplace>.

Mods die je vandaag al kunt lezen

• Ingebouwd in Claude Code: /plugin, tabblad Installed, sectie Built-in. Daaronder het paneel /diff en de lader die AGENTS.md leest als projectinstructies, waarvan Anthropic de broncode publiceert in de map mods van de repository anthropics/claude-code, met hun tests. Ook ingebouwd, en uit tot je hem inschakelt: You should know, een zij-agent die aangeeft wat jij of Claude misschien over het hoofd hebben gezien.
• De voorbeelden van Anthropic, in de repository claude-code-playground: een voorspelling van het contextvenster, getekend boven de prompt, een bewaker die een riskant shell-commando tegenhoudt en laat zien wat het zou veranderen, en een commando /replay dat stap voor stap door de wijzigingen van de laatste beurt loopt.
• De onze, hierboven beschreven: een mod zonder enige interface, één enkele hook tool.call, een goede vorm om na te bootsen als je data nodig hebt in plaats van een paneel.

Voordat je de mod van iemand anders installeert

Een mod draait niet in een sandbox. Hij draait met jouw rechten: hij kan je bestanden lezen en schrijven, je omgevingsvariabelen en instellingen lezen (API-sleutels inbegrepen), programma's starten, netwerkverzoeken doen, elke prompt en elke toolaanroep zien, en een toolaanroep goedkeuren voordat het jou gevraagd wordt. Als je de sandbox van Claude Code hebt ingeschakeld, dekt die de Bash-commando's die Claude uitvoert, niet de processen die een mod start.

Lees dus voordat je installeert. Kloon de mod en voer claude plugin validate uit op de map: de regels hooks: en calls: vertellen je waar hij naar luistert en wat hij bereikt, zonder iets uit te voeren. Een mod die alleen een balk boven de prompt tekent, heeft geen reden om $.http of $.process aan te roepen. Om alle mods die je hebt geïnstalleerd te stoppen, start je één sessie met --safe-mode, of zet je "disableAllHooks": true in ~/.claude/settings.json.

Waar mods draaien

Een mod die tekent, zou moeten controleren waar hij draait en terugvallen op tekst waar niets getekend wordt.

Mods in AgentsRoom

Je installeert niets: vanaf Claude Code 2.1.287 start elke Claude-agent met de mod, en het tabblad Wijzigingen toont de bestanden die elk van zijn shell-commando's heeft aangemaakt, gewijzigd of verwijderd, naast de agent die het deed. Met een oudere Claude Code blijft AgentsRoom shell-schrijfacties via het transcript toewijzen, zoals voorheen.

Hetzelfde idee draait ook in andere CLI's waar dat kan: oh-my-pi krijgt een extensie met hetzelfde contract, en de andere CLI's blijven shell-schrijfacties toewijzen zoals ze dat al deden. Wil je verder gaan met wat Claude Code bij elke stap blootlegt, dan behandelt onze gids over Claude Code hooks de settings-hooks waar een mod naast staat.

Veelgestelde vragen

Wat is een mod in Claude Code?

Een mod is een Claude Code plugin met een hooks module: een JavaScript- of TypeScript-bestand waarvan Claude Code de functies vanuit zijn eigen proces aanroept wanneer er iets gebeurt, zoals een toolaanroep, een verstuurde prompt of een deel van het scherm dat getekend wordt. Elke functie kan het event doorlaten, het wijzigen of het zelf afhandelen. Daardoor kan een mod een paneel tekenen, een commando toevoegen of een riskant shell-commando tegenhouden.

Welke versie van Claude Code heb ik nodig voor mods?

Claude Code 2.1.287 of nieuwer in de terminal, uitgebracht op 1 oktober 2026, met in de changelog "Added Claude Mods". Het tabblad Code van de Claude Desktop app ondersteunt ze vanaf 2.1.286. In de VS Code extensie draaien de hooks, en wat een mod tekent vraagt extensie 2.1.299 of nieuwer. Voer claude --version uit om het te controleren.

Wat is het verschil tussen een mod en een Claude Code hook?

Een hook in settings.json voert een shell-commando, een HTTP-verzoek of een prompt uit wanneer een event afgaat, buiten Claude Code. De hooks van een mod zijn functies die binnen Claude Code draaien. Ze kunnen wat een settings-hook niet kan: in de interface tekenen, een slash-commando toevoegen dat draait zonder beurt van Claude, een toolaanroep herschrijven of beantwoorden zonder de tool uit te voeren, en state delen tussen hooks.

Zijn Claude Code mods veilig om te installeren?

Een mod draait niet in een sandbox. Hij draait met jouw rechten, kan je bestanden en omgevingsvariabelen lezen, programma's starten, netwerkverzoeken doen en een toolaanroep goedkeuren. Installeer alleen mods van auteurs die je vertrouwt, en voer eerst claude plugin validate uit op de map: dat toont de events waar de mod op inhaakt en de aanroepen die hij doet, zonder hem uit te voeren.

Waar vind ik voorbeelden van Claude Code mods?

Anthropic publiceert de broncode van enkele ingebouwde mods, zoals het paneel /diff en de lader van AGENTS.md, in de map mods van de repository anthropics/claude-code, en voorbeeldmods in de repository anthropics/claude-code-playground. De mod van AgentsRoom die dit artikel beschrijft is een vierde soort voorbeeld: een mod zonder interface, met alleen een hook tool.call.

Kan ik mods uitschakelen?

Ja. Schakel één mod uit in het tabblad Installed van /plugin, start één sessie met --safe-mode, of zet disableAllHooks op true in ~/.claude/settings.json om alle mods te stoppen die je hebt geïnstalleerd, samen met je settings-hooks. --safe-mode en disableAllHooks laten de ingebouwde mods draaien: die schakel je één voor één uit in /plugin.