Claude Code Mods: Çalışma biçimini ve arayüzünü özelleştirme rehberi
8 Ekim 2026 tarihli resmî dokümantasyona göre hazırlanmıştır.
Claude Code’un Mods özelliği, geliştiricilerin Claude Code’a kendi işlevlerini eklemesini, mevcut davranışlarını değiştirmesini ve arayüzünü özelleştirmesini sağlar. Bir mod, gönderilen prompt’u düzenleyebilir, bir araç çağrısını durdurabilir, çalışma sırasında bilgi gösteren bir panel açabilir veya özel bir komut oluşturabilir.
Anthropic’in 1 Ekim 2026’da duyurduğu bu özellik, Claude Code’u kişisel ve ekip ihtiyaçlarına göre şekillendirmeyi amaçlıyor. Örneğin sürekli kontrol ettiğiniz bir bilgiyi arayüze taşıyabilir veya belirli işlemlerden önce kendi kontrol adımlarınızı çalıştırabilirsiniz. Anthropic’in duyurusu
Mod tam olarak nedir?
Teknik açıdan mod, JavaScript veya TypeScript ile yazılmış bir hooks modülü içeren Claude Code plugin’idir. Claude Code, belirli olaylar gerçekleştiğinde bu modüldeki fonksiyonları çağırır. Mod da olayı gözlemleyebilir, değiştirebilir veya işlemi kendisi karşılayabilir.
Plugin, birlikte kurulup yüklenen bileşenlerin paketidir. İçinde skill’ler, ajan tanımları, klasik hook’lar ve MCP sunucuları bulunabilir. Bu pakete Claude Code’un içindeki olaylara bağlanan bir hooks modülü eklendiğinde paket, mod olarak da işlev görür.
Şekil 1 — Plugin’in içerebileceği bileşenler. Her pakette bütün bileşenlerin bulunması gerekmez.
Mod, plugin sisteminin kurulum ve dağıtım altyapısını kullanır. Aynı plugin hem bir mod hem de onunla ilişkili skill ve araçları içerebilir. Plugin yapısı
Skill, Hook ve MCP’den farkı ne?
Claude Code’un özelleştirme seçenekleri birbirine benzer görünebilir. Ancak her biri farklı bir ihtiyaca karşılık gelir:
| Özellik | Temel görevi | Tipik kullanım |
|---|---|---|
| Skill | Claude’un okuyacağı talimatları ve iş akışını tanımlamak | Kod incelemesini belirli kurallara göre yaptırmak |
| Settings Hook | Belirli olaylarda yapılandırılmış bir işlem çalıştırmak | Dosya düzenlendikten sonra bir script çalıştırmak |
| MCP | Claude’a dış sistemlerde işlem yapabileceği araçlar sunmak | Bir veri kaynağından kayıt sorgulamak |
| Mod | Claude Code’un olaylarına ve arayüzüne kodla müdahale etmek | Canlı panel eklemek veya bir işlem akışını değiştirmek |
Modlar özellikle arayüz çizmek, oturum içindeki olaylar arasında veri paylaşmak ve Claude Code’un mevcut davranışlarını yeniden düzenlemek gerektiğinde öne çıkar. Resmî karşılaştırma
Çalışma mantığı: Olaylar ve işlem zinciri
Claude Code, bir araç çalıştırmak veya prompt göndermek gibi işlemler sırasında olaylar üretir. Modlar, ilgilendikleri olaylar için fonksiyon kaydeder.
Bir olay işleyicisi genellikle üç bilgi alır:
$: Modun Claude Code ile etkileşim kurmasını sağlayan API.e: Olayın verileri; örneğin araç adı veya prompt metni.next: İşlemi zincirdeki sonraki işleyiciye ileten fonksiyon.
Modun davranışını, next ile kurduğu ilişki belirler:
Gözlemleme: Mod gerekli bilgiyi kaydeder ve olayı devam ettirir. Bir aracın ne kadar sürdüğünü ölçmek için önce next(e) sonucunu bekleyebilir, ardından süreyi kaydedebilir.
Değiştirme: Mod, olayın değiştirilmiş bir kopyasını sonraki işleyiciye aktarır. Örneğin prompt’a ek bağlam yerleştirebilir.
İşlemi karşılama: Mod, next çağırmadan kendi sonucunu döndürür. Böylece ilgili işlem için sonraki modlar ve Claude Code’un olağan davranışı çalışmaz.
Birden fazla mod aynı olayı işliyorsa bunlar bir zincir oluşturur. Zincirin başındaki mod, gelen olayı önce görür; işlemi devam ettirirse dönen sonucu da diğerlerinden sonra görür. Bu nedenle modların sırası, birlikte nasıl çalışacaklarını etkiler. Olay işleme ve sıralama
Şekil 2 — İki moddan oluşan örnek zincir. Mod A kendi sonucunu döndürürse sonraki aşamalar çalışmaz; devam ettirirse sonuç ters yönde geri döner. Zincirin çalışma mantığı
Mods ile neler yapılabilir?
Canlı arayüzler oluşturmak
Bir mod, konuşmanın yanında bir panel veya prompt’un üstünde bir bilgi alanı gösterebilir. Bu alanlara metin, buton ve giriş alanları eklenebilir. Kullanıcı bir butona bastığında mod verisini güncelleyip görünümü yeniden çizebilir.
Örneğin bir araç kullanım göstergesinde, araç çağrılarını izleyen işleyici sayacı günceller. Arayüz işleyicisi ise bu veriyi okuyup göstergenin görünümünü oluşturur:
Şekil 3 — Olayları izleyen kod ile görünümü oluşturan kodun paylaşılan veri üzerinden birlikte çalışması.
Modlar mevcut arayüzün bazı parçalarını da değiştirebilir: araç sonuçlarının görünümü veya çalışma göstergesi bunlara örnektir. Görünüm ui.render olaylarıyla oluşturulur. Terminal ve masaüstü uygulamasının desteklediği öğeler arasında farklılıklar bulunduğu için her görünümün iki ortamda da kontrol edilmesi gerekir. Arayüz geliştirme
Özel komutlar ve araçlar eklemek
Mod API’siyle kullanıcıya yönelik /komutlar ve Claude’un çağırabileceği araçlar kaydedilebilir.
Bu ayrım önemlidir: Bir komutu kullanıcı çalıştırır; bir aracı ise Claude, açıklamasına ve ihtiyaç duyduğu işleme göre seçer. Örneğin /build-status komutu bir panel açarken, ayrı bir araç Claude’a belirli bir derlemenin sonucunu sorgulama olanağı verebilir.
API ayrıca dosyalara, süreçlere, ağa ve zamanlayıcılara erişim sunar. Mod, belirli aralıklarla bir durumu kontrol edebilir veya küçük bir sınıflandırma işi için model çağrısı yapabilir. Bu model çağrıları kullanıcının planını veya API anahtarını kullanır. Mods API
Üç somut örnek
Anthropic’in örnek modları, özelliğin kapsamını görmeyi kolaylaştırır:
Token Weather, bağlam penceresinin doluluğunu prompt’un üzerinde gösterir. Doluluk oranını hava durumu simgeleriyle ifade eder ve yakın geçmişteki değişimi görselleştirir. Uzayan oturumlarda bağlam kullanımını takip etmeye yardımcı olur.
Blast Radius, bazı riskli komutları çalıştırılmadan önce bekletir. Komutun etkileyebileceği dosyaları veya değişiklikleri gösterir ve devam etme ya da iptal etme seçenekleri sunar. Ancak komut metnini yorumladığı için her olası çalıştırma biçimini yakalayamaz. Örneğin bir script’in içine gizlenmiş işlem, bu kontrolün kapsamı dışında kalabilir.
Replay Theater, son turdaki dosya düzenlemelerini adım adım incelemeye yönelik bir /replay deneyimi sunar. Claude’un yaptığı değişikliklerin sırasını görmeyi kolaylaştırır.
Bu örnekler, bilgi gösterme, işlemlere müdahale etme ve değişiklikleri inceleme gibi farklı ihtiyaçlara karşılık gelir. Anthropic’in örnek mod rehberi
Claude Code’un kendi özelliklerinden bazıları da mod olarak geliştirilmiştir. /diff paneli ve AGENTS.md desteği bunlar arasındadır. Bunların kaynak kodları, gerçek bir modun nasıl tasarlandığını incelemek isteyenler için yararlı örneklerdir. Yerleşik modların kaynakları
Hangi ortamlarda çalışır?
Bir modun olay işleyicilerinin çalışması ile çizdiği arayüzün görünmesi ayrı konulardır.
| Kullanım ortamı | Olay işleyicileri | Mod arayüzü |
|---|---|---|
| Claude Code terminal oturumu | Çalışır | Görünür |
| Claude Desktop’ın Code sekmesi | Çalışır | Desteklenen öğeler görünür |
| VS Code eklentisinin sohbet paneli | Çalışır | Görünmez |
claude -p ve Agent SDK | Çalışır | Görünmez |
Bu tablo, ilgili plugin’in oturumda yüklendiği durumlar içindir. Masaüstü uygulamasındaki WSL oturumlarında ise plugin desteği bulunmadığından modlar çalışmaz.
Dokümantasyona göre terminalde Claude Code 2.1.287 ve sonrası, masaüstü uygulamasının içerdiği Claude Code’da 2.1.286 ve sonrası desteklenir. Modlar varsayılan olarak açıktır; kurum politikaları bunların yüklenmesini sınırlayabilir. Platform ve sürüm desteği
Bir mod nasıl kurulur?
Modlar plugin olarak kuruldukları için mevcut plugin yönetimi kullanılır. Terminalde Claude Code içinden /plugin komutuyla eklentileri inceleyebilirsiniz.
Üçüncü taraf bir marketplace için genel akış şöyledir:
TEXT1/plugin marketplace add your-org/my-mods 2/plugin install my-mod@my-mods
Buradaki isimler şablondur; kuracağınız modun gerçek depo, plugin ve marketplace adlarıyla değiştirilmelidir.
Oturum içindeki kurulum komutu plugin’in ayrıntılarını açar. Kurulumdan önce kapsam seçilir: tüm projelerde kendi hesabınız için, yalnızca mevcut depoda kendiniz için veya depodaki ekip yapılandırması için etkinleştirme seçenekleri bulunur.
Kurulum sonucundaki mesaj, plugin’in hemen etkinleşip etkinleşmediğini belirtir. Gerekirse /reload-plugins kullanılır. Yüklenen plugin’leri /plugin içindeki Installed sekmesinden yönetebilirsiniz. Kurulum ve yönetim
Kendi modunu oluşturmak
Bir mod yazmaya başlamak için JavaScript veya TypeScript bilmek zorunlu değildir. İstediğiniz davranışı Claude Code’a tarif edebilirsiniz:
Create a Claude Code mod that displays the current Git branch above the prompt. Update the display when the branch changes, and show “Not a Git repository” when the current directory is outside a Git repository.
Claude Code’un yerleşik plugin-authoring skill’i, mod geliştirme sürecine yardımcı olur. Oturum sırasında oluşturulan mod için kullanıcı onayıyla yeniden yükleme etkinleştirilebilir; değişiklikler ilgili tur tamamlandığında yüklenir.
Bu şekilde oluşturulan mod başlangıçta onu üreten oturuma bağlıdır. Başka oturumlarda kullanmak veya kalıcı olarak saklamak için mod klasörünü ayrı bir yere alıp plugin olarak yüklemek gerekir.
Temel yapı üç dosyadan oluşur:
TEXT1my-mod/ 2├── .claude-plugin/ 3│ └── plugin.json 4└── hooks/ 5 ├── hooks.json 6 └── register.js
Manifest plugin’i tanımlar; hooks.json giriş modülünü gösterir; register.js olay işleyicilerini kaydeder. Claude Code JavaScript ve TypeScript dosyalarını doğrudan yükleyebilir; başlangıç için ayrıca bir derleme sistemi gerekmez. Mod oluşturma rehberi
Aşağıdaki örnek giriş modülü, Write ve Edit araçlarına gelen çağrıları sayar:
JAVASCRIPT1export function register(on) { 2 const edits = { requested: 0 }; 3 4 on("tool.call", { tool: ["Write", "Edit"] }, async ($, event, forward) => { 5 edits.requested += 1; 6 $.ui.log(`File change request: ${edits.requested}`); 7 return forward(event); 8 }); 9}
Buradaki forward, önceki açıklamadaki next fonksiyonudur; parametre adı farklı seçilmiştir. Kod çağrıyı devam ettirir. Sayaç, tamamlanmış dosya değişikliklerini değil, ilgili araçlara gelen çağrıları ölçer. İşleyici sözleşmesi
Durum yönetimi ve kullanım maliyeti
Moddaki sıradan değişkenler yeniden yüklemede sıfırlanabilir. Oturum boyunca yeniden yüklemelere dayanacak veriler için $.state, oturumlar arasında paylaşılacak kalıcı veriler için $.store kullanılabilir. Bir grafiğin geçmişini veya kullanıcının seçtiği görünümü korumak için bu ayrımı baştan yapmak gerekir. Durum yönetimi
Bir sayacı artırmak veya arayüz çizmek kendi başına model çağrısı gerektirmez. Ancak modun toplam kullanım etkisi, yaptığı işlere bağlıdır. Model çağrıları yapan bir mod kullanım tüketir; bağlama metin ekleyen bir mod da sonraki istekleri büyütebilir. Model çağrıları
Ayrıca modun bulunduğu plugin’in skill, ajan ve komut açıklamaları bağlamda yer kaplayabilir. Bu nedenle maliyeti değerlendirirken yalnızca mod kodunu değil, paketin tamamını düşünmek gerekir. Plugin’in bağlam etkisi claude plugin details ile incelenebilir. Plugin maliyetini ölçme
Güvenlik: Modlara hangi erişimi veriyorsunuz?
Bir mod, kullanıcı yetkileriyle çalışan koddur. Dosya okuyabilir ve yazabilir, süreç başlatabilir ve ağ bağlantısı kurabilir. Claude’un araç çağrılarına uygulanan izinler ile plugin’in kendi başına çalıştırdığı kodun erişimleri arasında fark vardır.
Claude Code’un Bash sandbox’ı, bir modun başlattığı süreçleri aynı şekilde sınırlamaz. Bu yüzden bir modun güvenilirliğini değerlendirirken kaynağını ve yaptığı işlemleri incelemek gerekir. Plugin’in ayrıntılarında bir hook’un bulunması, o hook’un tam olarak ne yaptığını açıklamaz. Kaynak kod ve bağımlılıklar da değerlendirilmelidir. Plugin güvenliği
Kurumsal ortamlarda sec-default adlı yerleşik mod, yönetilen talimatları ve politikaları kullanıcıların kurduğu modlardan korur. Yönetilen ayarları bulunan makinelerde veya Team ve Enterprise hesaplarında yüklenir.
Ancak bu koruma, modun tüm dosya ve süreç erişimini otomatik olarak sınırlandıran bir sandbox değildir. Örneğin Claude’un bir dosyayı araçla okumasını engelleyen kural, modun kendi $.fs erişimine aynı biçimde uygulanmaz. Yöneticiler kullanıcı modlarını engelleyebilir veya kendi politika modlarıyla ek sınırlamalar koyabilir. Kurumsal mod yönetimi
Test etmek ve sorunları bulmak
Bir modun statik kontrolü için şu komut kullanılabilir:
TEXT1claude plugin validate ./my-mod
Bu kontrol; manifest’i, olay kayıtlarını ve modun kullandığı API çağrılarını incelemeye yardımcı olur. Çıktıdaki hooks: ve calls: satırları modun hangi olayları işlediğini ve hangi API yöntemlerini çağırdığını gösterir. Doğrulama ve hata ayıklama
Davranış testleri için ise:
TEXT1claude plugin test ./my-mod
Test altyapısı, olayları modun işleyicilerinden geçirebilir ve Claude Code’un vereceği yanıtları test içinde tanımlayabilir. Böylece gerçek bir oturum, oturum açma veya ağ bağlantısı olmadan belirli davranışlar doğrulanabilir. Mod testleri
Güvenlikle ilgili bir mod geliştirirken hata davranışı ayrıca önemlidir. Bir hook başarısız olduğunda Claude Code onu atlayıp oturumu devam ettirebilir. Dolayısıyla işlemleri engelleyen bir modun, kendi kontrolü hata verdiğinde de engellemeyi sürdürecek biçimde tasarlanması gerekir. Hook hatalarını ele alma
İlk mod için doğru kapsamı seçmek
Başlangıç için mevcut Git dalını, araç çağrısı sayısını veya bağlam kullanımını gösteren küçük bir mod uygun bir çalışma alanıdır. Böyle bir örnekle olayları, görünüm güncellemelerini ve yeniden yüklemeyi öğrenmek kolaylaşır.
Sonraki adımda ihtiyaca göre etkileşim eklenebilir: Bir panel açan komut, görünümü değiştiren buton veya kullanıcıya soru soran bir işlem kontrolü. Her yeni işlevde hangi olayın izlendiğini, hangi erişimin kullanıldığını ve hata durumunda ne olacağını açık tutmak, modun bakımını ve incelemesini kolaylaştırır.