Claude Code Modları: Ne Oldukları ve Her Ajanla Birlikte Sunduğumuz Mod

1 Ekim 2026'da Claude Code 2.1.287, değişiklik günlüğünde tek satırlık bir kayıtla çıktı: "Added Claude Mods". Dört gün sonra AgentsRoom, çalıştırdığı Claude ajanlarına modlarımızdan birini yüklemeye başladı.

Bu yazı modun ne olduğunu, eski genişletme noktalarının yapamadığı neleri yapabildiğini, nasıl yazılıp yüklendiğini ve test edildiğini, ve AgentsRoom'un başlattığı her Claude ajanına bir mod koyarken neler öğrendiğimizi anlatıyor. Claude Code ile ilgili bilgiler, Claude Code 2.1.318 kuruluyken 9 Kasım 2026'da okunan belgelerinden ve değişiklik günlüğünden alındı.

Kısa cevap. Mod, hooks module (hook modülü) içeren bir Claude Code eklentisidir: bir olay olduğunda Claude Code'un kendi süreci içinden fonksiyonlarını çağırdığı bir JavaScript ya da TypeScript dosyası. Bir fonksiyon olayı geçirebilir, değiştirebilir ya da Claude Code'un yerine yanıtlayabilir. Bir mod panel çizmeyi, komut eklemeyi ya da bir kabuk komutunu çalışmadan önce durdurmayı böyle yapar.

Mod nedir

Claude Code'un zaten eklentileri vardı: .claude-plugin/plugin.json konumunda bir manifest bulunan, becerileri, alt ajanları, ayar hook'larını ve MCP sunucularını tek bir birim olarak kurulsunlar diye paketleyen bir klasör. Mod, bir eklentinin içerebileceği bir şey daha. Eklentinin hooks/hooks.json dosyası modules anahtarı altında bir kod dosyası belirttiğinde, Claude Code o dosyayı yükler ve dışa aktardığı register fonksiyonunu çağırır. Eklenti bundan sonra mod olarak adlandırılır.

register içinde her on(event, hook) çağrısı bir olaya bir fonksiyon bağlar: bir araç çalışmadan önce tool.call, bir prompt gönderdiğinde prompt.submit, session.start, bir eğik çizgi komutu için command.run, Claude Code ekranının bir bölümünü çizerken ui.render ve daha fazlası. Her hook üç şey alır:

• $, mod API'si: bir modun kendi kodu dışında yapabildiği her şey, örneğin $.ui, $.command, $.fs, $.process ya da $.http.
• e, düz veri olarak olay: bir araç çağrısı için aracın adı ve argümanları.
• next, olayı önce diğer modlara, sonra Claude Code'un kendi davranışına ileten ve sonucu döndüren fonksiyon.

Ne olacağına hook'un next ile ne yaptığı karar verir. next(e) döndürürsen yalnızca gözlemlemiş olursun. next fonksiyonunu e nesnesinin değiştirilmiş bir kopyasıyla çağırırsan olayı yeniden yazmış olursun. next çağırmadan kendi sonucunu döndürürsen olayı sen yanıtlamış olursun: araç hiç çalışmaz ya da Claude Code kendi çizimini hiç yapmaz.

Belgeler bu fonksiyonlara da hook diyor. Bunlar settings.json içine yazdığın hook'lar değil; Claude Code onlara artık settings hooks, yani ayar hook'ları diyor.

Mod, ayar hook'u, beceri ya da MCP sunucusu

Bu dördü birbiriyle örtüşüyor ve aralarında en ağırı mod. İşi gören en hafif olanı seç.

Bir eklenti dördünü birden içerebilir, yani bir mod birlikte çalıştığı beceri ve MCP sunucusuyla yan yana sunulabilir.

Bir modun üç dosyası

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

plugin.json alışıldık eklenti manifestidir: bir ad, bir sürüm, bir açıklama. hooks.json koda işaret eder, { "modules": ["./register.ts"] }, o dosyaya göreli tek bir yol. register.ts ise hook modülüdür. Claude Code .js ve .ts dosyalarını paketleyici ve derleme adımı olmadan doğrudan yükler, izin verilen tek çıplak import (bare import) ise türler ve birkaç yardımcı için claude-code paketidir.

Sunduğumuz mod: bu dosyayı kim değiştirdi?

AgentsRoom aynı depo üzerinde birkaç kodlama ajanı çalıştırır ve Değişiklikler sekmesinde hangi ajanın hangi dosyayı değiştirdiğini gösterir, böylece her ajanın işini ayrı ayrı inceleyip commit edebilirsin. Claude'un Edit ve Write araçlarıyla yazılan dosyalar kolaydı: Claude Code onları bir ayar hook'u üzerinden bildirir. Bir kabuk komutuyla yazılan dosyalar ise öyle değildi. Bir sed -i, bir heredoc, bir codemod ya da bir rm hiçbir zaman bir dosya aracından geçmez.

Modlardan önce tahmin ediyorduk. AgentsRoom, her Bash komutunun ne zaman başlayıp bittiğini öğrenmek için ajanın oturum dökümünü okuyor, sonra dosyanın değişiklik zamanını bu aralıklarla eşleştiriyordu. Çoğu zaman işe yarıyordu ve adını koyabildiğimiz üç şekilde başarısız oluyordu:

• silinmiş bir dosyanın değişiklik zamanı yoktur, bu yüzden bir silme işlemi hiçbir zaman bir ajana atfedilmiyordu;
• grep gibi salt okunur bir komut, ajanın bu sırada her şeyi yazmış olabileceği bir aralık açıyordu;
• her şey, Claude Code'un istediği zaman değiştirebileceği döküm biçimine bağlıydı.

Mod tahmini ortadan kaldırıyor. agentsroom-changes modumuz iki kabuk aracı için tool.call olayına bağlanır. Komut çalışmadan hemen önce deponun bir anlık görüntüsünü alır (git status ile birlikte her değişmiş yolun boyutu ve değişiklik zamanı). Hemen sonra ikincisini alır. Farklı olan yollar, silmeler dahil, o komutun değiştirdikleridir ve mod bunları yerel bir HTTP uç noktası üzerinden AgentsRoom masaüstü uygulamasına gönderir. Claude Code'un kendisinin salt okunur olarak işaretlediği bir çağrı hiçbir şey üstlenmez.

İşte hook'un kısaltılmış hali. Tam dosya 177 satır, çoğu anlık görüntü ve onun sınırları.

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

Masaüstü uygulaması modu kendi klasörüne kopyalar ve her Claude ajanını, yalnızca kurulu Claude Code 2.1.287 ya da daha yeniyse, claude --plugin-dir <that folder> ile başlatır. Modu 5 Ekim 2026'da AgentsRoom 1.201.0 ile yayınladık.

Onu yayınlarken öğrendiklerimiz

Bir mod kullanıcıya asla bir araç çağrısına mal olmamalı. Hook'umuz Claude'un çalıştırdığı her kabuk komutunun önünde durur. Hata fırlatırsa ya da ağı beklerse Claude'un işi durur. Her adım korunur, masaüstü uygulamasına giden her gönderim yanıt beklenmeden ateşlenip unutulur ve kabul ettiğimiz tek bekleme, her biri 15 saniyeyle sınırlı iki git status anlık görüntüsüdür. Kaybolan bir gönderim bir atfa mal olur, komuta asla.

İstenmediğin yerde hiçbir şey yapma. Mod, AgentsRoom'un kendi ajanları için ayarladığı bir ortam değişkenini okur. Bu değişken yoksa, örneğin biri klasörü kendi kurulumuna kopyaladığı için, her hook doğrudan next(e) adımına geçer.

--plugin-dir ile yüklenen bir klasör izlenir. O klasördeki bir dosya değiştiğinde Claude Code modu yeniden yükler ve yeniden yükleme register fonksiyonunu tekrar çalıştırır. Bu, modu kurma biçimimizi belirledi: masaüstü uygulaması bir mod dosyasını yalnızca içeriği değiştiyse yazar, çünkü her ajan başlatılışında körlemesine yeniden yazmak, zaten açık olan her Claude konsolunda modu yeniden yüklerdi.

API'nin değişeceğini hesaba kat. Olaylar ve metotlar sürümden sürüme değişebilir, belgeler de bunu açıkça söylüyor. Bir mod --plugin-dir üzerinden yüklendiğinde Claude Code, çalışan sürümün tür bildirimlerini .claude-plugin/types/ içine yazar; tür denetimini bir web sayfasına göre değil, bunlara göre yapıyoruz. Ve bir sürüm modumuzu artık yüklemezse hiçbir şey bozulmaz: mod hiçbir zaman hazır olduğunu bildirmez ve AgentsRoom eski döküm yöntemine geri döner.

Kendi modunu yaz

İki yolun var.

Claude'a sor. Etkileşimli bir Claude Code oturumunda istediğin modu tarif et ("prompt'un üstünde geçerli git dalını göster"). Claude yerleşik bir beceri olan plugin-authoring becerisini kullanır, modu o oturuma ait bir klasöre yazar ve Claude Code, Claude'un yazdığı modları açıp açmayacağını sana bir kez sorar. Evet de, mod tur bitince yüklenir, sonra onu değiştiren her turdan sonra yeniden yüklenir.

Üç dosyayı kendin yaz, sonra:

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, modülünün işlediği olayları içeren bir hooks: satırı ve çağırdığı her mod API metodunu içeren bir calls: satırı yazdırır. İşlemek istediğin bir olay eksikse Claude Code o hook'u da çağırmaz. Statik analizin kuralları var: her çağrıyı eksiksiz yaz ($.ui.toast(...), asla const ui = $.ui), olay adlarını string literal olarak ver ve yalnızca kendi dosyalarını göreli yolla içe aktar.

Bir modu paylaşmak için ona olduğu şey gibi, bir eklenti gibi davran: klasörü gönder ya da insanlar /plugin install <name>@<marketplace> ile kurabilsin diye bir marketplace içinde listele (.claude-plugin/marketplace.json dosyası olan bir depo).

Bugün okuyabileceğin modlar

• Claude Code'a yerleşik olanlar: /plugin, Installed sekmesi, Built-in bölümü. Aralarında /diff paneli ve AGENTS.md dosyasını proje talimatları olarak okuyan yükleyici var; Anthropic bunların kaynak kodunu, testleriyle birlikte, anthropics/claude-code deposunun mods klasöründe yayımlıyor. Yine yerleşik olan ve sen açana kadar kapalı duran: You should know, senin ya da Claude'un gözden kaçırmış olabileceği şeyleri işaret eden yan bir ajan.
• Anthropic'in örnekleri, claude-code-playground deposunda: prompt'un üstüne çizilen bir bağlam penceresi tahmini, riskli bir kabuk komutunu bekletip neyi değiştireceğini gösteren bir koruma ve son turun düzenlemelerini adım adım dolaşan bir /replay komutu.
• Bizimki, yukarıda anlatılan: hiç arayüzü olmayan, tek bir tool.call hook'u olan bir mod. İhtiyacın bir panel değil de veriyse kopyalanacak iyi bir kalıp.

Başkasının modunu kurmadan önce

Bir mod sandbox içinde yalıtılmaz. Senin izinlerinle çalışır: dosyalarını okuyup yazabilir, ortam değişkenlerini ve ayarlarını (API anahtarları dahil) okuyabilir, program başlatabilir, ağ isteği yapabilir, her prompt'u ve her araç çağrısını görebilir ve sana sorulmadan önce bir araç çağrısını onaylayabilir. Claude Code'un sandbox'ını açtıysan, bu Claude'un çalıştırdığı Bash komutlarını kapsar, bir modun başlattığı süreçleri değil.

O yüzden kurmadan önce oku. Modu klonla ve klasör üzerinde claude plugin validate çalıştır: hooks: ve calls: satırları, hiçbir şey çalıştırmadan, neyi dinlediğini ve nelere eriştiğini söyler. Yalnızca prompt'un üstüne bir şerit çizen bir modun $.http ya da $.process çağırması için hiçbir neden yoktur. Kurduğun tüm modları durdurmak için tek bir oturumu --safe-mode ile başlat ya da ~/.claude/settings.json içinde "disableAllHooks": true ayarla.

Modlar nerede çalışır

Çizim yapan bir mod nerede çalıştığını kontrol etmeli ve hiçbir şeyin çizilmediği yerlerde metne geri dönmeli.

AgentsRoom'da

Hiçbir şey kurmana gerek yok: Claude Code 2.1.287'den itibaren her Claude ajanı modla birlikte başlar ve Değişiklikler sekmesi, her kabuk komutunun oluşturduğu, değiştirdiği ya da sildiği dosyaları bunu yapan ajanın yanında gösterir. Daha eski bir Claude Code'da AgentsRoom, kabuk yazımlarını eskisi gibi dökümden eşleştirmeye devam eder.

Aynı fikir mümkün olduğu yerlerde diğer CLI'larda da çalışıyor: oh-my-pi aynı sözleşmeye sahip bir uzantı alıyor, diğer CLI'lar ise kabuk yazımlarını eskiden olduğu gibi eşleştirmeye devam ediyor. Claude Code'un her adımda neyi açığa çıkardığına daha derinden bakmak istersen, Claude Code hook rehberimiz bir modun yanında durduğu ayar hook'larını anlatıyor.

Sık sorulan sorular

Claude Code'da mod nedir?

Mod, bir hooks module (hook modülü) içeren bir Claude Code eklentisidir: bir araç çağrısı, gönderilen bir prompt ya da ekranın bir bölümünün çizilmesi gibi bir şey olduğunda Claude Code'un kendi süreci içinden fonksiyonlarını çağırdığı bir JavaScript ya da TypeScript dosyası. Her fonksiyon olayı geçirebilir, değiştirebilir ya da kendisi karşılayabilir. Bir modun panel çizmesini, komut eklemesini ya da riskli bir kabuk komutunu bekletmesini sağlayan budur.

Modlar için hangi Claude Code sürümü gerekiyor?

Terminalde Claude Code 2.1.287 ya da daha yenisi: bu sürüm 1 Ekim 2026'da çıktı ve değişiklik günlüğünde "Added Claude Mods" yazıyor. Claude Desktop uygulamasının Code sekmesi modları 2.1.286'dan itibaren destekliyor. VS Code eklentisinde hook'lar çalışır, bir modun çizdiklerini görmek içinse eklentinin 2.1.299 ya da daha yeni sürümü gerekir. Kontrol etmek için claude --version komutunu çalıştır.

Mod ile Claude Code hook'u arasındaki fark nedir?

settings.json içindeki bir hook, bir olay tetiklendiğinde Claude Code'un dışında bir kabuk komutu, bir HTTP isteği ya da bir prompt çalıştırır. Bir modun hook'ları ise Claude Code'un içinde çalışan fonksiyonlardır. Bir ayar hook'unun yapamadığını yapabilirler: arayüze çizim yapmak, Claude turu olmadan çalışan bir eğik çizgi komutu eklemek, bir araç çağrısını yeniden yazmak ya da aracı çalıştırmadan yanıtlamak ve hook'lar arasında durum paylaşmak.

Claude Code modlarını kurmak güvenli mi?

Bir mod sandbox içinde yalıtılmaz. Senin izinlerinle çalışır, dosyalarını ve ortam değişkenlerini okuyabilir, program başlatabilir, ağ isteği yapabilir ve bir araç çağrısını onaylayabilir. Modları yalnızca güvendiğin yazarlardan kur ve önce klasör üzerinde claude plugin validate çalıştır: modu çalıştırmadan, dinlediği olayları ve yaptığı çağrıları listeler.

Claude Code mod örneklerini nerede bulabilirim?

Anthropic, /diff paneli ve AGENTS.md yükleyicisi gibi bazı yerleşik modların kaynak kodunu anthropics/claude-code deposunun mods klasöründe, örnek modları ise anthropics/claude-code-playground deposunda yayımlıyor. Bu yazıda anlatılan AgentsRoom modu dördüncü türden bir örnek: arayüzü olmayan, yalnızca bir tool.call hook'u olan bir mod.

Modları kapatabilir miyim?

Evet. Tek bir modu /plugin içindeki Installed sekmesinden devre dışı bırak, tek bir oturumu --safe-mode ile başlat ya da kurduğun tüm modları ayar hook'larınla birlikte durdurmak için ~/.claude/settings.json içinde disableAllHooks değerini true yap. --safe-mode ve disableAllHooks yerleşik modları çalışır halde bırakır: onlar /plugin içinde tek tek kapatılır.