Anthropic wprowadza mods do Claude Code i Claude Desktop: co zmieniają wtyczki JS i TS?

Anthropic wprowadził mods - wtyczki napisane w JavaScript i TypeScript, które działają bezpośrednio wewnątrz procesu Claude Code oraz Claude Desktop. Zamiast ograniczać się do prostych skryptów powłoki czy zewnętrznych integracji, zyskujesz narzędzie do modyfikowania interfejsu terminala, przechwytywania wywołań narzędzi (tool calls) i dodawania własnych komend bez angażowania kolejnych zapytań do modelu.

Claude Code przestał być sztywno zaprogramowanym środowiskiem CLI. Jeśli na co dzień pracujesz z agentami w terminalu - przy refaktoryzacji kodu, budowie scraperów czy automatyzacji skryptów SEO - nowa architektura pozwala dostosować narzędzie dokładnie pod Twój workflow.

Czym są mods i czym różnią się od settings hooks oraz MCP?

Do tej pory Claude Code oferował dwa główne sposoby rozszerzania możliwości: serwery MCP (Model Context Protocol) oraz hooki konfigurowane w plikach ustawień (settings hooks). Obie metody mają tę samą cechę techniczną - działają na zewnątrz procesu głównego agenta. Settings hook odpala zewnętrzny proces powłoki Bash lub zapytanie HTTP w reakcji na zdarzenie. Serwer MCP udostępnia zestaw zewnętrznych narzędzi przez protokół JSON-RPC.

Mod działa inaczej: to kod w JS lub TS wykonywany wewnątrz środowiska wykonawczego Claude Code. Dzięki temu ma bezpośredni dostęp do stanu aplikacji i obiektów sesji.

W praktyce mod potrafi wyrenderować dynamiczny pasek stanu nad wierszem wprowadzania komend, dodać panel podglądu subagentów, zmienić wygląd domyślnego wskaźnika ładowania (spinner) albo całkowicie zablokować niebezpieczną komendę systemową, zanim trafi do powłoki.

Wymagania systemowe i instalacja modów krok po kroku

Obsługa wtyczek wymaga aktualnych wydań narzędzi od Anthropic. Zanim przejdziesz do instalacji, sprawdź wersje swoich aplikacji:

• Claude Code CLI: wymagana wersja to minimum v2.1.287.
• Claude Desktop: wymagana wersja to minimum v2.1.286 (mody działają lokalnie w dedykowanej zakładce Code).

Wersję w terminalu sprawdzisz poleceniem claude --version. Jeśli wersja jest niższa, wykonaj standardową aktualizację pakietu npm. W aplikacji Desktop wpisz polecenie /status w sesji zakładki Code i sprawdź numer kompilacji.

Instalacja moda odbywa się za pośrednictwem systemu wtyczek. Możesz to zrobić na dwa sposoby:

1. Z poziomu aktywnej sesji Claude Code:

/plugin install nazwa-moda@nazwa-marketplace

1. Bezpośrednio z poziomu powłoki systemowej:

claude plugin install nazwa-moda@nazwa-marketplace

Po @ podajesz nazwę marketplace'u, z którego pochodzi mod, np. openrouter-balance@krysmalskipl. Marketplace trzeba najpierw dodać poleceniem claude plugin marketplace add, co pokazuję niżej.

Pamiętaj o jednej zasadzie: jeśli instalujesz lub aktualizujesz plugin w terminalu obok otwartej sesji, musisz wpisać w sesji komendę /reload-plugins. Bez tego nowy kod załaduje się dopiero przy ponownym uruchomieniu narzędzia.

Zachowanie modów różni się w zależności od środowiska. W pełnym trybie interaktywnym CLI oraz w Claude Desktop masz dostęp do rysowania UI i pełnych przechwytów zdarzeń. Z kolei w trybie wsadowym (claude -p), rozszerzeniu do VS Code oraz w sesjach chmurowych niektóre elementy graficzne są pomijane, co szczegółowo opisuje oficjalna dokumentacja Claude Code dotycząca wtyczek.

Ekosystem społeczności: repozytorium claude-code-mods

Nie musisz pisać wszystkich rozszerzeń od podstaw. Gotowe mody instalujesz z marketplace'ów, czyli repozytoriów na GitHubie z listą wtyczek. Każdy mod instalujesz osobno, tylko te, których potrzebujesz.

Zacznij od mojego repozytorium krysmalskipl/claude-code-mods. Rejestrujesz je raz jako marketplace, a potem instalujesz wybrane mody:

claude plugin marketplace add krysmalskipl/claude-code-mods

# OpenRouter balance and today's spend above the prompt
claude plugin install openrouter-balance@krysmalskipl

Będę tam dodawał kolejne mody, przede wszystkim pod pracę SEO. Jak powstał openrouter-balance i jak zbudować podobny samodzielnie, pokazuję w dalszej części artykułu.

Więcej gotowych wtyczek znajdziesz w społecznościowym katalogu hamzafer/claude-code-mods. Dodajesz go tak samo:

claude plugin marketplace add hamzafer/claude-code-mods

Następnie instalujesz wybrane narzędzia:

# Context window usage as a bar, split by category
claude plugin install context-bar@claude-code-mods

# Prompt cache countdown and hit rate
claude plugin install cache-clock@claude-code-mods

# One live line per running subagent
claude plugin install agent-radar@claude-code-mods

# Markdown files Claude edits, rendered like GitHub
claude plugin install md-preview@claude-code-mods

Możesz także zainstalować cały podstawowy pakiet produktywności jednym poleceniem powłoki:

for m in context-bar token-weather usage-meter where-am-i next-steps agent-radar review-watch blast-radius mission-control; do
  claude plugin install "$m@claude-code-mods"
done

Przegląd najciekawszych wtyczek w praktyce

W połączeniu z oficjalnymi przykładami od Anthropic z repozytorium claude-code-playground deweloperzy zyskują potężny zestaw ułatwień:

• context-bar & token-weather: context-bar rysuje nad promptem poziomy pasek z dokładnym podziałem tokenów (system prompt, narzędzia MCP, pliki pamięci, wiadomości, bufor kompresji). Z kolei token-weather prognozuje stan okna i odlicza czas do wygaśnięcia prompt cache.
• cache-clock: integruje się bezpośrednio z paskiem stanu CLI, pokazując w czasie rzeczywistym procent zapytań obsłużonych z cache (hit rate) oraz ile tokenów trzeba będzie zapisać do cache ponownie, gdy wygaśnie.
• blast-radius: strażnik komend terminala. Kiedy agent planuje wykonać polecenie o wysokim ryzyku (np. rm -rf, git push --force czy czyszczenie tabel bazy), mod przechwytuje operację, wyświetla podgląd zmienianych plików i wymusza manualne zatwierdzenie.
• mission-control: w terminalach obsługujących renderowanie grafiki (Ghostty, kitty, iTerm2) wyświetla interaktywną mapę plików edytowanych przez subagenty z podświetleniem statusu (odczyt, zapis, gotowe).
• replay-theater: dodaje komendę /replay, umożliwiającą prześledzenie diffów i operacji na plikach krok po kroku po zakończonej turze zapytań.

Jak wygląda anatomia prostego moda?

Mod to moduł TypeScript, który eksportuje funkcję register. Dostaje ona on - funkcję do podpinania się pod zdarzenia sesji (start sesji, wywołanie narzędzia, wysłanie prompta, rysowanie interfejsu). Każdy hook dostaje trzy argumenty: $ (interfejs silnika Claude Code), e (dane zdarzenia) i next (przekazanie zdarzenia dalej). Poniższy przykład w kilku linijkach blokuje agentowi edycję plików .env:

// hooks/register.ts - a guard for .env files
import type { Register } from 'claude-code'

const PROTECTED = /(^|\/)\.env(\.|$)/

export const register: Register = on => {
  on('tool.call', { tool: 'Edit' }, ($, e, next) =>
    PROTECTED.test(e.file_path)
      ? { deny: `Edycja ${e.file_path} jest zablokowana przez env-guard.` }
      : next(e),
  )
}

Hook zwraca { deny } i wywołanie narzędzia w ogóle nie dochodzi do skutku, a Claude dostaje powód odmowy. Jeśli plik nie jest chroniony, next(e) przepuszcza zdarzenie dalej. Wszystko dzieje się lokalnie, bez dodatkowego zapytania do modelu i bez zużywania tokenów.

Jak zbudować własny mod: saldo OpenRouter nad promptem?

Przegląd gotowych wtyczek to jedno, ale najwięcej uczy napisanie własnej. Na co dzień korzystam z OpenRouter i brakowało mi jednej rzeczy: żeby bez otwierania przeglądarki widzieć, ile zostało z limitu klucza i ile wydałem dziś. Tak powstał mod openrouter-balance, który zgłosiłem do repozytorium społeczności jako PR #85 w hamzafer/claude-code-mods. Efekt wygląda tak:

Powiększ

Zainstaluj gotowy mod w 2 minuty

Jeśli chcesz po prostu mieć tę linię u siebie, nie musisz niczego pisać. Mod jest w moim repozytorium krysmalskipl/claude-code-mods, które działa jako marketplace. Wpisz w terminalu:

claude plugin marketplace add krysmalskipl/claude-code-mods
claude plugin install openrouter-balance@krysmalskipl

Mod potrzebuje klucza OpenRouter i sam go szuka: w ustawieniach wtyczki, w zmiennych OPENROUTER_MANAGEMENT_KEY i OPENROUTER_API_KEY, w pęku kluczy macOS (Keychain), a na końcu w Twojej powłoce. Jeśli masz już OPENROUTER_API_KEY w ~/.zshrc, nic więcej nie robisz - mod znajdzie go nawet w Claude Desktop uruchomionym z Docka. Komunikat „1 userConfig option not yet set” po instalacji możesz wtedy zignorować.

Który klucz wybrać?

• Zwykły klucz API pokaże wydatki tego klucza dziś i w tym miesiącu oraz ile zostało z jego limitu.
• Klucz management (openrouter.ai → Settings → Management keys) pokaże prawdziwe saldo całego konta i model, na który poszło najwięcej pieniędzy. Nie może wywoływać modeli, więc bezpiecznie go trzymać. Najlepiej w Keychain: security add-generic-password -a "$USER" -s openrouter-key -w.

Po instalacji uruchom nową sesję Claude Code albo wpisz /reload-plugins. Linia pojawi się nad promptem, a /openrouter-balance pokaże szczegóły. Pełna instrukcja, z rozwiązywaniem problemów i aktualizacją, jest w README repozytorium.

Jak to działa od środka?

Pełna wersja ma ponad 300 linii, ale cały mechanizm zmieści się w około 50. Poniżej zbudujemy wersję mini, która robi najważniejsze: co 5 minut pyta OpenRouter o stan klucza i rysuje jedną linię nad promptem.

Krok 1: struktura folderu

Mod to zwykły folder z czterema plikami:

openrouter-mini/
├── .claude-plugin/
│   └── plugin.json      # name, version, description
├── hooks/
│   ├── hooks.json       # which file is the hooks module
│   └── register.tsx     # the mod's code
└── types/
    └── index.d.ts       # types of the state the mod keeps

Krok 2: manifest i lista modułów

.claude-plugin/plugin.json opisuje wtyczkę. Pole types wskazuje kontrakt stanu:

{
  "name": "openrouter-mini",
  "version": "0.1.0",
  "description": "Ile zostało z limitu klucza OpenRouter i ile wydałeś dziś - jedna linia nad promptem.",
  "author": { "name": "Jakub Krysmalski", "url": "https://krysmalski.pl" },
  "types": "./types/index.d.ts"
}

hooks/hooks.json wskazuje plik z kodem:

{ "modules": ["./register.tsx"] }

Krok 3: kontrakt stanu

Mod przechowuje ostatni odczyt z OpenRouter w stanie sesji. Ten stan trzyma Claude Code, a nie sam mod, więc liczby przetrwają nawet przeładowanie pliku w trakcie pracy. Każda wartość musi być zadeklarowana w types/index.d.ts:

export type Line = { left: number | null; limit: number | null; today: number } | null

declare module 'claude-code' {
  interface PluginState {
    'openrouter-mini': { line: Line }
  }
}

Krok 4: kod moda

Cały mod w hooks/register.tsx:

import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'

import type { Line } from '../types'

// The host keeps this state, so the line survives a reload of this file.
const line = atom({ plugin: 'openrouter-mini', key: 'line' } as const, null as Line)

export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    const result = await next(e)
    void refresh($)
    $.clock.every(5 * 60 * 1000, () => void refresh($)) // every 5 minutes
    return result
  })

  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const rest = await next(e) // what other mods draw here stays
    const now = await read($, line)
    if (!now) return rest
    const { Box, Text } = $.ui.resolve(e)
    const left = now.left !== null ? `$${now.left.toFixed(2)} z $${now.limit?.toFixed(2)} · ` : ''
    return (
      <Box flexDirection="column">
        <Box paddingX={1}>
          <Text>
            <Text color="#8b9cff" bold>{'◆ OpenRouter  '}</Text>
            <Text>{left}</Text>
            <Text bold>{`$${now.today.toFixed(2)}`}</Text>
            <Text dimColor>{' dziś'}</Text>
          </Text>
        </Box>
        {rest}
      </Box>
    )
  })
}

async function refresh($: EngineInterface) {
  const env = await $.process.run(['printenv', 'OPENROUTER_API_KEY'])
  const key = env.stdout.trim()
  if (!key) return
  const res = await $.http.fetch('https://openrouter.ai/api/v1/key', { headers: { authorization: `Bearer ${key}` } })
  if (!res.ok) return
  const d = JSON.parse(res.text).data
  await update($, line, () => ({ left: d.limit_remaining, limit: d.limit, today: d.usage_daily }))
}

Co tu się dzieje:

• session.start - po starcie sesji mod od razu pobiera dane i ustawia zegar, który robi to co 5 minut. next(e) na początku pozwala Claude Code najpierw normalnie wystartować sesję.
• ui.render z component: 'AbovePrompt' - za każdym razem, gdy Claude Code rysuje pasek nad promptem, mod dokłada swoją linię. rest to linie innych modów, więc nic nie znika.
• $.ui.resolve(e) - zwraca komponenty (Box, Text) dla aktualnej powierzchni. Ten sam kod narysuje linię w terminalu i w zakładce Code w Claude Desktop.
• atom, read, update - update zapisuje nowy odczyt, a Claude Code sam przerysowuje wszystko, co ten stan czyta.
• $.process.run i $.http.fetch - mod nie ma dostępu do Node.js ani przeglądarki. Wszystko, co wychodzi poza mod (zmienne środowiskowe, sieć, pliki), idzie przez $. Dzięki temu claude plugin validate może pokazać, czego dokładnie mod używa.
• Endpoint /api/v1/key działa ze zwykłym kluczem API i zwraca m.in. limit, limit_remaining oraz usage_daily (wydatki klucza w bieżącym dniu UTC).

Krok 5: uruchom mod i patrz, jak działa

Najprościej załadować folder do jednej sesji:

claude --plugin-dir ./openrouter-mini

Jeśli piszesz mod razem z Claude Code, możesz włączyć przeładowywanie na żywo. Przy pierwszym zapisanym pliku moda Claude Code zapyta: Enable hot reloading for this session? Po wybraniu Enable for this session każda zmiana w kodzie ładuje się sama po zakończeniu tury, bez restartu.

Powiększ

Krok 6: walidacja i test

Zanim podzielisz się modem, sprawdź go dwoma poleceniami:

claude plugin validate ./openrouter-mini
claude plugin test ./openrouter-mini

validate czyta kod tak jak Claude Code i wypisuje, na jakie zdarzenia mod reaguje i co wywołuje ($.http.fetch, $.process.run i tak dalej). To ta sama lista, którą warto przejrzeć przed instalacją cudzego moda.

test uruchamia pliki *.test.tsx z folderu tests/. W teście podstawiasz odpowiedzi silnika i API (np. udajesz, że OpenRouter zwrócił limit_remaining: 2.67), a potem sprawdzasz, co mod narysował. Nie wydajesz przy tym ani centa.

Co dodaje pełna wersja openrouter-balance?

Wersja mini wystarczy na start. W pełnej wersji doszło kilka rzeczy, które warto dodać do każdego moda korzystającego z API:

• Saldo całego konta - z kluczem typu management mod pyta endpoint /credits i pokazuje prawdziwe saldo, a z /activity model, na który poszło najwięcej pieniędzy w ostatnich 30 dniach.
• Kolory - zielony od $5, żółty poniżej $5, czerwony poniżej $2 z dopiskiem „top up soon”.
• Komenda /openrouter-balance - szczegóły: dziś, tydzień, miesiąc, limit klucza, wydatki według modeli.
• Bezpieczne trzymanie klucza - kolejno z /config, zmiennych środowiskowych, pęku kluczy macOS (Keychain) albo z Twojej powłoki, gdy aplikacja nie wczytała ~/.zshrc. Klucz jest trzymany tylko w pamięci.
• Odporność na błędy - brak sieci nie kasuje ostatnich liczb, tylko oznacza je jako offline, a odrzucony klucz jest nazwany wprost.

Mody pod SEO: meta-lint i link-check

Skoro mod widzi każdą edycję pliku, może pilnować podstaw SEO, kiedy Claude pisze wpis albo przerabia szablon strony. Do mojego repozytorium dodałem dwa takie mody:

claude plugin marketplace add krysmalskipl/claude-code-mods   # once per machine
claude plugin install meta-lint@krysmalskipl
claude plugin install link-check@krysmalskipl

Oba działają bez klucza i bez konfiguracji. Po instalacji uruchom nową sesję albo wpisz /reload-plugins.

Powiększ

meta-lint po każdej edycji pliku Markdown, MDX, Astro albo HTML pokazuje nad promptem jedną linię:

• title - długość tytułu z frontmattera (seo_title, meta_title, title), z <title> albo z pierwszego H1. Zielony przy 30-60 znakach, czerwony powyżej 60
• description - długość opisu z seo_description, description, excerpt albo z <meta name="description">. Zielony przy 70-160 znakach
• H1 - liczba nagłówków H1 w treści. Komentarz # w bloku kodu nie liczy się jako nagłówek
• obrazki bez alt i liczba słów

Komenda /meta-lint pokazuje szczegóły i podgląd snippetu w wynikach Google, a /meta-lint plik.md sprawdza dowolny plik. Wszystko liczy się lokalnie, nic nie wychodzi z komputera.

link-check sprawdza linki zewnętrzne, które Claude właśnie dodał do wpisu, strony albo szablonu. Tu widać przewagę moda nad zwykłym narzędziem: martwy link (błąd 4xx/5xx albo brak odpowiedzi) wraca do Claude'a razem z wynikiem edycji, więc model poprawia go jeszcze w tej samej turze. Ty widzisz go nad promptem, dopóki jest w pliku, a /links pokazuje listę. Kody 401, 403 i 429 mod traktuje jako działające, bo to zwykle blokady botów, a nie martwe strony.

Jedno ograniczenie warto znać. Link-check rozpozna martwy link tylko wtedy, gdy serwer uczciwie odpowie błędem. Strona, która na nieistniejący adres zwraca kod 200 (tzw. soft 404), dla żadnego narzędzia nie wygląda na zepsutą. To zresztą dobry powód, żeby sprawdzić, jak zachowuje się Twoja własna strona.

Jak system prompt w Claude CLI współpracuje z architekturą modów?

Częstym pytaniem osób konfigurujących środowisko deweloperskie jest to, czy mods zastępują instrukcje systemowe (system prompt). Odpowiedź brzmi: nie, te mechanizmy działają na zupełnie innych warstwach aplikacji.

Instrukcje systemowe w Claude Code konfigurujesz za pomocą pliku konfiguracyjnego CLAUDE.md, zmiennych środowiskowych lub standardowych reguł zachowania modelu. System prompt instruuje model językowy, w jaki sposób ma rozumować, jakich konwencji kodowania w Next.js czy TypeScript używać i jak formułować odpowiedzi.

Mod działa po etapie generowania tekstu przez model lub przed wysłaniem polecenia. Nawet jeśli model postanowi wywołać narzędzie Bash, mod w kodzie JS/TS może zweryfikować to żądanie, zmodyfikować argumenty albo całkowicie odrzucić wywołanie bez pytania modelu o zdanie. System prompt kształtuje intencję AI, a mod kontroluje faktyczne wykonanie w środowisku dewelopera.

Bezpieczeństwo i uprawnienia: o czym musisz pamiętać przed instalacją?

Mod nie działa w izolowanej piaskownicy. Kod wtyczki wykonuje się z Twoimi pełnymi uprawnieniami systemowymi wewnątrz procesu Claude Code.

Oznacza to bezpośrednie konsekwencje dla bezpieczeństwa Twojej stacji roboczej:

• Mod może czytać i modyfikować dowolne pliki, do których Twoje konto ma uprawnienia.
• Ma wgląd w zmienne środowiskowe, w tym klucze API zapisane w systemie czy plikach .env.
• Widzi całą treść promptów, transkrypcję sesji oraz odpowiedzi modelu.
• Może samodzielnie wykonywać zapytania sieciowe fetch/HTTP i zatwierdzać komendy w tle.

Wbudowany w Claude Code sandbox izoluje polecenia uruchamiane w powłoce Bash, ale procesy wystartowane bezpośrednio przez modyfikację JS działają poza nim. Dlatego nigdy nie instaluj wtyczek z niesprawdzonych repozytoriów.

Przed załadowaniem nowego dodatku przeanalizuj jego zawartość poleceniem walidacji:

claude plugin validate ./sciezka-do-pluginu

W sekcjach hooks: i calls: terminal wyświetli pełną listę zdarzeń, na które reaguje plugin, oraz akcji, które zamierza wykonywać. W razie problemów możesz uruchomić sesję w trybie awaryjnym komendą claude --safe-mode, co tymczasowo wyłącza wszystkie mody.

Jeśli chcesz całkowicie wyłączyć ładowanie modyfikacji we wszystkich sesjach, dodaj odpowiedni wpis w konfiguracji ~/.claude/settings.json:

{
  "disableAllHooks": true
}

Nowe możliwości automatyzacji w codziennej pracy deweloperskiej

Otwarcie Claude Code na wtyczki w TypeScript zbliża to narzędzie do pełnoprawnego, programowalnego środowiska pracy. Przy złożonych projektach możliwość zablokowania niechcianych operacji na dysku czy stałego monitorowania kosztów tokenów bez opuszczania terminala oszczędza sporo nerwów.

Świetnie łączy się to z innymi rozwiązaniami, które opisuję na blogu: od zaawansowanego routingu modeli, o którym przeczytasz we wpisie o konfiguracji Jev przez OpenRouter w terminalu i Claude Code, po pracę z modelami takimi jak Claude Sonnet 5.5. Jeśli łączysz pracę agentów terminalowych z systemami takimi jak n8n Agents i automatyzacjami opartymi na agentach AI, mody pozwalają spiąć powiadomienia webhook czy webhooki zwrotne bezpośrednio z poziomu interfejsu CLI. Z kolei osoby preferujące w pełni odizolowane środowiska mogą zestawić narzędzia terminalowe z lokalnymi modelami AI z Ollama i Qwen Coder.