Mody Claude Code: czym są i mod, który dostarczamy w każdym agencie

1 października 2026 ukazał się Claude Code 2.1.287 z jednolinijkowym wpisem w changelogu: "Added Claude Mods". Cztery dni później AgentsRoom zaczął ładować jeden z naszych modów do agentów Claude, które uruchamia.

Ten artykuł wyjaśnia, czym jest mod, co potrafi, a czego nie potrafiły starsze punkty rozszerzeń, jak go napisać, załadować i przetestować, oraz czego nauczyliśmy się, dostarczając mod w każdym agencie Claude, którego startuje AgentsRoom. Fakty o Claude Code pochodzą z jego dokumentacji i changelogu, przeczytanych 9 listopada 2026, przy zainstalowanym Claude Code 2.1.318.

Krótka odpowiedź. Mod to plugin Claude Code z hooks module: plikiem JavaScript lub TypeScript, którego funkcje Claude Code wywołuje z wnętrza własnego procesu, gdy zachodzi zdarzenie. Funkcja może przepuścić zdarzenie, zmienić je albo odpowiedzieć na nie zamiast Claude Code. Tak mod rysuje panel, dodaje polecenie albo zatrzymuje polecenie powłoki, zanim się wykona.

Czym jest mod

Claude Code miał już pluginy: folder z manifestem w .claude-plugin/plugin.json, który pakuje skille, subagenty, hooki ustawień i serwery MCP, żeby instalowały się jako jedna całość. Mod to kolejna rzecz, którą plugin może zawierać. Gdy plik hooks/hooks.json pluginu wskazuje plik z kodem pod kluczem modules, Claude Code ładuje ten plik i wywołuje funkcję register, którą on eksportuje. Taki plugin nazywa się wtedy modem.

Wewnątrz register każde wywołanie on(event, hook) podpina funkcję pod zdarzenie: tool.call przed uruchomieniem narzędzia, prompt.submit gdy wysyłasz prompt, session.start, command.run dla polecenia slash, ui.render gdy Claude Code rysuje fragment swojego ekranu, i inne. Każdy hook dostaje trzy rzeczy:

• $, API modów: wszystko, co mod może zrobić poza własnym kodem, na przykład $.ui, $.command, $.fs, $.process albo $.http.
• e, zdarzenie, jako zwykłe dane: dla wywołania narzędzia nazwa narzędzia i jego argumenty.
• next, które przekazuje zdarzenie pozostałym modom, a potem własnemu zachowaniu Claude Code, i zwraca wynik.

To, co hook zrobi z next, decyduje o dalszym przebiegu. Zwróć next(e), a tylko obserwowałeś. Wywołaj next ze zmienioną kopią e, a przepisałeś zdarzenie. Zwróć własny wynik bez wywołania next, a odpowiedziałeś na nie: narzędzie nigdy się nie uruchomi albo Claude Code nigdy nie narysuje swojej wersji.

Dokumentacja również nazywa te funkcje hookami. To nie są hooki, które piszesz w settings.json i które Claude Code nazywa teraz settings hooks, czyli hookami ustawień.

Mod, hook ustawień, skill czy serwer MCP

Te cztery się pokrywają, a mod jest z nich najcięższy. Wybierz najlżejszy, który wykona zadanie.

Plugin może zawierać wszystkie cztery, więc mod może być dostarczany obok skilla i serwera MCP, z którymi współpracuje.

Trzy pliki moda

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

plugin.json to zwykły manifest pluginu: nazwa, wersja, opis. hooks.json wskazuje kod, { "modules": ["./register.ts"] }, jedna ścieżka, względna wobec tego pliku. register.ts to hooks module. Claude Code ładuje .js i .ts bezpośrednio, bez bundlera i bez kroku budowania, a jedyny dozwolony goły import to claude-code, dla typów i kilku pomocniczych funkcji.

Mod, który dostarczamy: kto zmienił ten plik?

AgentsRoom uruchamia kilku agentów kodujących na tym samym repozytorium i pokazuje w zakładce Zmiany, który agent zmienił który plik, żebyś mógł przejrzeć i zacommitować pracę każdego agenta osobno. Pliki zapisane narzędziami Edit i Write Claude były łatwe: Claude Code zgłasza je przez hook ustawień. Pliki zapisane przez polecenie powłoki już nie. sed -i, heredoc, codemod albo rm nigdy nie przechodzą przez narzędzie plikowe.

Przed modami zgadywaliśmy. AgentsRoom czytał transkrypt sesji agenta, żeby wiedzieć, kiedy każde polecenie Bash się zaczęło i skończyło, a potem porównywał czas modyfikacji pliku z tymi przedziałami. Działało to przez większość czasu i zawodziło na trzy sposoby, które umieliśmy nazwać:

• usunięty plik nie ma czasu modyfikacji, więc usunięcie nigdy nie było przypisywane;
• polecenie tylko do odczytu, takie jak grep, otwierało przedział, w którym agent mógł zapisać cokolwiek;
• wszystko zależało od formatu transkryptu, który Claude Code może dowolnie zmienić.

Mod usuwa zgadywanie. Nasz mod agentsroom-changes podpina się pod tool.call dla dwóch narzędzi powłoki. Tuż przed uruchomieniem polecenia robi snapshot repozytorium (git status plus rozmiar i czas modyfikacji każdej zmienionej ścieżki). Tuż po nim robi drugi. Ścieżki, które się różnią, to to, co zmieniło to polecenie, łącznie z usunięciami, a mod wysyła je do aplikacji desktopowej AgentsRoom przez lokalny endpoint HTTP. Wywołanie, które Claude Code sam oznacza jako tylko do odczytu, niczego sobie nie przypisuje.

Oto hook, skrócony. Cały plik ma 177 linii, w większości na snapshot i jego limity.

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
  });
};

Aplikacja desktopowa kopiuje mod do własnego folderu i uruchamia każdego agenta Claude poleceniem claude --plugin-dir <that folder>, tylko gdy zainstalowany Claude Code jest w wersji 2.1.287 lub nowszej. Wydaliśmy go w AgentsRoom 1.201.0, 5 października 2026.

Czego nauczyliśmy się, wydając go

Mod nigdy nie może kosztować użytkownika wywołania narzędzia. Nasz hook stoi przed każdym poleceniem powłoki, które uruchamia Claude. Jeśli rzuci wyjątek albo czeka na sieć, praca Claude staje. Każdy krok jest zabezpieczony, każde zgłoszenie do aplikacji desktopowej jest wysyłane bez czekania na odpowiedź, a jedyne oczekiwanie, które akceptujemy, to dwa snapshoty git status, każdy ograniczony do 15 sekund. Zgubione zgłoszenie kosztuje jedno przypisanie, nigdy polecenie.

Nie rób nic, gdy nikt cię nie potrzebuje. Mod czyta zmienną środowiskową, którą AgentsRoom ustawia swoim agentom. Gdy jej brakuje, na przykład dlatego, że ktoś skopiował folder do własnej konfiguracji, każdy hook przechodzi od razu do next(e).

Folder załadowany przez --plugin-dir jest obserwowany. Claude Code przeładowuje mod, gdy zmieni się plik w tym folderze, a przeładowanie ponownie uruchamia register. To zdecydowało o sposobie instalacji: aplikacja desktopowa zapisuje plik moda tylko wtedy, gdy jego treść się zmieniła, bo ślepe nadpisywanie przy każdym starcie agenta przeładowałoby mod w każdej już otwartej konsoli Claude.

Zakładaj, że API będzie się zmieniać. Zdarzenia i metody mogą się zmieniać między wydaniami, i dokumentacja sama to mówi. Gdy mod jest ładowany z --plugin-dir, Claude Code zapisuje deklaracje typów działającej wersji do .claude-plugin/types/; to z nimi sprawdzamy typy, a nie ze stroną internetową. A jeśli jakaś wersja przestanie ładować nasz mod, nic się nie psuje: mod nigdy nie zgłasza gotowości, a AgentsRoom wraca do starej metody opartej na transkrypcie.

Napisz własny

Masz dwie drogi.

Poproś Claude. W interaktywnej sesji Claude Code opisz mod, którego chcesz ("pokaż bieżącą gałąź git nad promptem"). Claude korzysta z wbudowanego skilla plugin-authoring, zapisuje mod w folderze przeznaczonym dla tej sesji, a Claude Code raz pyta cię, czy włączyć mody pisane przez Claude. Odpowiedz tak, a mod załaduje się na koniec tury, a potem będzie przeładowywany po każdej turze, która go zmienia.

Napisz trzy pliki sam, a potem:

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 wypisuje linię hooks: ze zdarzeniami, które obsługuje twój moduł, i linię calls: z każdą metodą API modów, którą wywołuje. Jeśli brakuje zdarzenia, które chciałeś obsłużyć, Claude Code też nie wywoła tego hooka. Analiza statyczna ma swoje zasady: pisz każde wywołanie w całości ($.ui.toast(...), nigdy const ui = $.ui), przekazuj nazwy zdarzeń jako literały tekstowe i importuj tylko własne pliki, po ścieżce względnej.

Żeby udostępnić mod, traktuj go jak plugin, którym jest: wyślij folder albo dodaj go do marketplace'u (repozytorium z plikiem .claude-plugin/marketplace.json), żeby inni instalowali go przez /plugin install <name>@<marketplace>.

Mody, które możesz przeczytać już dziś

• Wbudowane w Claude Code: /plugin, zakładka Installed, sekcja Built-in. Wśród nich panel /diff i loader, który czyta AGENTS.md jako instrukcje projektu; ich kod źródłowy Anthropic publikuje w folderze mods repozytorium anthropics/claude-code, razem z testami. Również wbudowany i wyłączony, dopóki go nie włączysz: You should know, poboczny agent, który sygnalizuje, co ty albo Claude mogliście przeoczyć.
• Przykłady Anthropic, w repozytorium claude-code-playground: prognoza okna kontekstu rysowana nad promptem, strażnik, który wstrzymuje ryzykowne polecenie powłoki i pokazuje, co by zmieniło, oraz polecenie /replay, które krok po kroku przechodzi przez zmiany z ostatniej tury.
• Nasz, opisany wyżej: mod bez żadnego interfejsu, jeden hook tool.call, dobry wzór do skopiowania, jeśli potrzebujesz danych, a nie panelu.

Zanim zainstalujesz cudzy mod

Mod nie działa w piaskownicy. Działa z twoimi uprawnieniami: może czytać i zapisywać twoje pliki, czytać twoje zmienne środowiskowe i ustawienia (łącznie z kluczami API), uruchamiać programy, wysyłać żądania sieciowe, widzieć każdy prompt i każde wywołanie narzędzia oraz zatwierdzić wywołanie narzędzia, zanim ktoś zapyta ciebie. Jeśli włączyłeś piaskownicę Claude Code, obejmuje ona polecenia Bash uruchamiane przez Claude, a nie procesy, które startuje mod.

Więc czytaj, zanim zainstalujesz. Sklonuj mod i uruchom claude plugin validate na folderze: linie hooks: i calls: mówią, czego mod nasłuchuje i do czego sięga, bez uruchamiania czegokolwiek. Mod, który tylko rysuje pasek nad promptem, nie ma powodu wywoływać $.http ani $.process. Żeby zatrzymać wszystkie zainstalowane przez siebie mody, uruchom jedną sesję z --safe-mode albo ustaw "disableAllHooks": true w ~/.claude/settings.json.

Gdzie działają mody

Mod, który rysuje, powinien sprawdzać, gdzie działa, i tam, gdzie nic się nie rysuje, przechodzić na tekst.

W AgentsRoom

Nic nie instalujesz: od Claude Code 2.1.287 każdy agent Claude startuje z modem, a zakładka Zmiany pokazuje pliki, które każde z jego poleceń powłoki utworzyło, zmieniło albo usunęło, obok agenta, który to zrobił. Ze starszym Claude Code AgentsRoom nadal przypisuje zapisy z powłoki na podstawie transkryptu, jak wcześniej.

Ta sama idea działa w innych CLI, tam gdzie to możliwe: oh-my-pi dostaje rozszerzenie o tym samym kontrakcie, a pozostałe CLI przypisują zapisy z powłoki tak jak dotąd. Jeśli chcesz pójść dalej w tym, co Claude Code udostępnia na każdym etapie, nasz przewodnik po hookach Claude Code omawia hooki ustawień, obok których działa mod.

Najczęściej zadawane pytania

Czym jest mod w Claude Code?

Mod to plugin Claude Code zawierający hooks module: plik JavaScript lub TypeScript, którego funkcje Claude Code wywołuje z wnętrza własnego procesu, gdy coś się dzieje, na przykład wywołanie narzędzia, wysłany prompt albo rysowanie fragmentu ekranu. Każda funkcja może przepuścić zdarzenie, zmienić je albo obsłużyć je sama. Dzięki temu mod może narysować panel, dodać polecenie albo wstrzymać ryzykowne polecenie powłoki.

Jakiej wersji Claude Code potrzebuję do modów?

Claude Code 2.1.287 lub nowszego w terminalu, wydanego 1 października 2026, którego changelog mówi "Added Claude Mods". Zakładka Code w aplikacji Claude Desktop obsługuje je od 2.1.286. W rozszerzeniu VS Code hooki działają, a to, co rysuje mod, wymaga rozszerzenia 2.1.299 lub nowszego. Uruchom claude --version, żeby sprawdzić.

Czym różni się mod od hooka Claude Code?

Hook zapisany w settings.json uruchamia polecenie powłoki, żądanie HTTP albo prompt, gdy zachodzi zdarzenie, poza Claude Code. Hooki moda to funkcje, które działają wewnątrz Claude Code. Potrafią to, czego hook ustawień nie potrafi: rysować w interfejsie, dodać polecenie slash działające bez tury Claude, przepisać wywołanie narzędzia albo odpowiedzieć na nie bez uruchamiania narzędzia oraz współdzielić stan między hookami.

Czy instalowanie modów Claude Code jest bezpieczne?

Mod nie działa w piaskownicy. Działa z twoimi uprawnieniami, może czytać twoje pliki i zmienne środowiskowe, uruchamiać programy, wysyłać żądania sieciowe i zatwierdzić wywołanie narzędzia. Instaluj mody tylko od autorów, którym ufasz, i najpierw uruchom claude plugin validate na folderze: wypisuje zdarzenia, pod które podpina się mod, i wywołania, które wykonuje, bez uruchamiania go.

Gdzie znaleźć przykłady modów Claude Code?

Anthropic publikuje kod źródłowy niektórych wbudowanych modów, takich jak panel /diff i loader AGENTS.md, w folderze mods repozytorium anthropics/claude-code, a przykładowe mody w repozytorium anthropics/claude-code-playground. Mod AgentsRoom opisany w tym artykule to czwarty rodzaj przykładu: mod bez interfejsu, z jednym tylko hookiem tool.call.

Czy mogę wyłączyć mody?

Tak. Wyłącz pojedynczy mod w zakładce Installed w /plugin, uruchom jedną sesję z --safe-mode albo ustaw disableAllHooks na true w ~/.claude/settings.json, żeby zatrzymać wszystkie zainstalowane przez siebie mody, razem z hookami ustawień. --safe-mode i disableAllHooks zostawiają wbudowane mody włączone: te wyłącza się pojedynczo w /plugin.