Deep Links

Deep Links — Claude Code’a URL ile oturum başlatma

Claude Code, claude-cli:// özel URL şeması sayesinde bir bağlantıya tıklayarak doğrudan terminal oturumu açmanıza olanak tanır. Bu bağlantılar; runbook’lara, uyarı panolarına, README dosyalarına veya CI bildirimlerine gömülebilir. Tıklayan kişi, Claude Code’u ilgili repo dizininde ve önceden doldurulmuş bir prompt ile başlatır.

Not: Deep links, Claude Code v2.1.91 veya daha yeni bir sürüm gerektirir.

Nasıl çalışır (How it works)

claude-cli:// öneki, işletim sisteminize kayıtlı özel bir URL şemasıdır. Tıpkı mailto: bağlantılarının e-posta istemcinizi açması gibi, claude-cli:// bağlantıları da Claude Code’u açar.

Bir bağlantıya tıklandığında:

1. Tarayıcı veya uygulama URL’yi işletim sistemine iletir.
2. İşletim sistemi claude-cli:// önekini tanır ve Claude Code’u başlatır.
3. Yeni bir terminal penceresi açılır; Claude Code, bağlantıda belirtilen dizinde çalışır ve prompt kutusu bağlantıdaki metinle önceden doldurulur.
4. Kullanıcı prompt’u okur, isterse düzenler ve Enter’a basarak gönderir.

Bağlantının kendisi herhangi bir yerde barındırılabilir, ancak oturum her zaman tıklamanın yapıldığı bilgisayarda yerel olarak açılır.

Uyarı: GitHub’da render edilen Markdown (README’ler, issue’lar, PR’lar ve wiki’ler) yalnızca http ve https şemalarına izin verir; claude-cli:// gibi özel şemaları kaldırır. Bu durumda bağlantı metni görünür ancak tıklanabilir olmaz. Çözüm için Sorun Giderme bölümüne bakın.

Başlatılan oturumda ne görünür (What a launched session shows)

Bir deep link asla kendi başına bir şey çalıştırmaz. Bağlantı yalnızca bir dizin seçer ve prompt kutusunu doldurur. Güvenmediğiniz bir sayfadan gelen bağlantıya tıklasanız bile, prompt etkisizdir: modele hiçbir şey ulaşmaz, ta ki siz prompt’u okuyup Enter’a basana kadar.

Oturum açıldığında, giriş satırının üzerinde bir banner gösterilir. Bu banner, oturumun harici bir bağlantı tarafından başlatıldığını ve hangi dizinin seçildiğini belirtir. 1.000 karakterden uzun prompt’lar için banner, kullanıcıya tam metni kaydırarak gözden geçirmesini ve Enter’a basmadan önce okumasını hatırlatır.

Seçilen dizin için geçerli olan izin kuralları, CLAUDE.md ve güven prompt’ları, diğer oturumlarla aynı şekilde uygulanır.

Bağlantı oluşturma (Build a link)

Her deep link, claude-cli://open ile başlar. Bu, işleyicinin kabul ettiği tek yoldur. Ardından isteğe bağlı sorgu parametreleri eklenir.

En basit haliyle bağlantı, Claude Code’u ev dizininde boş bir prompt ile açar:

claude-cli://open

Parametrelerle oturumun nerede başlayacağını ve prompt kutusunun ne içereceğini kontrol edebilirsiniz:

cwd ve repo parametreleri, çalışma dizinini ayarlamanın iki yoludur. İkisi de verilirse cwd önceliklidir ve repo yok sayılır — cwd yolu mevcut olmasa bile.

Aşağıdaki örnek, acme/payments reposunu ve iki satırlık bir tanı prompt’unu içerir:

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

Bu bağlantıya tıklandığında yeni bir terminal penceresi açılır, Claude Code acme/payments reposunun yerel klonunda başlar ve prompt kutusu şu metinle doldurulur:

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

Prompt’u göndermeden önce düzenleyebilirsiniz. Eğer reposun yerel bir klonu yoksa oturum ev dizininde açılır.

cwd ve repo arasında seçim yapma (Choose between cwd and repo)

• cwd kullanın: Bağlantıya tıklayan herkes projeyi aynı mutlak yolda bulunduruyorsa (örneğin standart bir devcontainer veya VM imajı).
• repo kullanın: Bağlantı paylaşılıyorsa ve herkes farklı bir konuma klonlama yapıyorsa.

Claude Code, slug’ı yerel bir yola şu şekilde çözer:

• Her claude çalıştırdığınızda, o dizinin dosya sistemi yolu, reponun GitHub owner/name slug’ı ile kaydedilir.
• Bir deep link geldiğinde, repo parametresi en son kullandığınız eşleşen yolu açar.
• Birden fazla klon ve worktree ayrı ayrı izlenir; en son hangisinde çalıştıysanız o seçilir.
• Arama yalnızca daha önce en az bir kez Claude Code çalıştırdığınız yolları bulur.

Bağlantı, hangi branch’in checkout edildiğini değiştirmez. Oturum, dizinin o anki durumunda açılır. Başlatılan oturum, hangi yolun seçildiğini ve o klonun en son ne zaman remote’tan veri çektiğini gösterir, böylece güncel olmayan kodla çalışıp çalışmadığınızı anlayabilirsiniz.

Örnekler (Examples)

Runbook’a bağlantı gömme (Embed a link in a runbook)

Bir runbook’taki deep link, olay yönetimi yapan kişiye tek tıkla doğru repoda ve hazır bir prompt ile araştırmaya başlama imkanı verir. Runbook’u render eden platformun özel URL şemalarına izin vermesi gerekir.

Prompt, URL’nin bir parçasıdır ve URL-encode edilmelidir. Kodlanmış değeri elde etmek için prompt metnini bir tarayıcı konsolunda encodeURIComponent ile veya herhangi bir URL kodlayıcı ile işleyin.

Aşağıdaki örnek, web-gateway servisi için bir olay runbook’una araştırma giriş noktası ekler:

## web-gateway'de yüksek 5xx oranı

1. PagerDuty'deki sayfayı onaylayın.
2. [Gateway reposunda Claude Code'u aç](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. İlk bulguları #incident kanalında paylaşın.

Kendi runbook’unuzda kullanmak için acme/web-gateway yerine servisinizin repo slug’ını yazın. Bu sayede Claude Code yüklü ve reposu klonlanmış mühendisler, 2. adıma tıklayarak prompt’u göndermeye hazır şekilde araştırmaya başlayabilir.

Kabuktan bağlantı açma (Open a link from the shell)

Bir deep link’i tıklamak yerine shell script, alias veya otomasyon içinden de açabilirsiniz. İşletim sisteminizin URL açma komutunu bağlantıyla birlikte çağırın.

macOS:

open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Linux:

xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Windows (PowerShell):

Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Windows (cmd.exe): start komutu ilk tırnaklı argümanını pencere başlığı olarak yorumlar, bu nedenle URL’den önce boş bir başlık geçin:

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Kayıt ve desteklenen platformlar (Registration and supported platforms)

Claude Code, claude-cli:// işleyicisini işletim sisteminize ilk interaktif oturumu başlattığınızda kaydeder. Ayrı bir kurulum komutu çalıştırmanız gerekmez. Kayıt yalnızca kullanıcı düzeyindeki konumlara yazılır:

İşleyici, Claude Code’u algılanan bir terminal öykünücüsünde başlatır:

• macOS: Claude Code, en son interaktif oturumunuzdaki terminali hatırlar ve onu yeniden kullanır. Desteklenen terminaller: iTerm2, Ghostty, kitty, Alacritty, WezTerm ve Terminal.app.
• Linux: Önce $TERMINAL ortam değişkenine, ardından x-terminal-emulator’a, sonra da yaygın öykünücüler listesine bakar.
• Windows: Önce Windows Terminal’i, sonra PowerShell’i, en son cmd.exe’yi tercih eder.

Kaydı tamamen engellemek için settings.json dosyasında disableDeepLinkRegistration değerini "disable" olarak ayarlayın. Bunu kuruluş genelinde zorunlu kılmak ve kullanıcıların tekrar etkinleştirmesini engellemek için yönetilen ayarları kullanın.

Terminal yerine VS Code sekmesi açma (Open a VS Code tab instead of a terminal)

VS Code eklentisi, kendi işleyicisini vscode://anthropic.claude-code/open adresinde kaydeder. Bu URL, bir terminal penceresi yerine Claude Code editör sekmesi açar. Parametreler için Diğer araçlardan VS Code sekmesi başlatma sayfasına bakın.

Sorun giderme (Troubleshooting)

Bağlantıya tıklandığında hiçbir şey olmuyor

İşleyici büyük olasılıkla henüz kaydedilmemiştir. O makinede bir kez interaktif claude oturumu başlatın, çıkın ve bağlantıyı tekrar deneyin. Linux’ta bir masaüstü ortamınız yoksa xdg-open’un gönderecek bir hedefi olmayabilir.

Bağlantı düz metin olarak görünüyor, tıklanabilir değil

Bazı Markdown render’ları yalnızca http ve https bağlantılarına izin verir, diğer URL şemalarını kaldırır. GitHub, README’lerde, issue’larda, PR’larda ve wiki’lerde bu şekilde davranır: [label](claude-cli://...) yalnızca label metni olarak render edilir, bağlantı ve URL kaldırılır. Bu platformlarda deep link’i bir kod bloğu içine koyun, böylece okuyucular URL’yi görüp tarayıcı adres çubuğuna yapıştırabilir.

Oturum repo yerine ev dizininde açılıyor

repo parametresi yalnızca Claude Code’un daha önce gördüğü klonları çözümler. Klonun içinde bir kez claude çalıştırın, böylece yolu kaydedilir. Alternatif olarak, bağlantıda cwd parametresini mutlak bir yol ile kullanın.

Bağlantı yanlış terminali açıyor

• macOS: Tercih ettiğiniz terminalde bir kez claude başlatın; sonraki deep link aynı terminali kullanacaktır.
• Linux: $TERMINAL ortam değişkenini tercih ettiğiniz öykünücünün komut adına ayarlayın.
• Windows: Sıra sabittir. Bağlantıların PowerShell veya cmd.exe yerine Windows Terminal’de açılmasını istiyorsanız Windows Terminal’i yükleyin.

İlgili kaynaklar (Learn more)

• Skills: Uzun bir runbook prompt’unu repoda /skill olarak saklayın, böylece deep link’in q parametresi yalnızca skill adını içerir.
• Non-interactive mode: Terminal açmadan Claude’u bir script’ten çalıştırın ve çıktıyı yakalayın.

Örnek kullanım senaryosu

Senaryo: Bir DevOps mühendisi, payment-service reposunda yaşanan yüksek hata oranı için bir incident runbook’u hazırlıyor. Runbook’a, olay yönetimi yapan mühendislerin tek tıkla doğru repoda ve hazır bir prompt ile araştırmaya başlamasını sağlayacak bir deep link eklemek istiyor.

Adımlar:

1. Prompt’u hazırlayın: Araştırma prompt’u şöyle olsun:

   payment-service'de hata oranı %5'in üzerinde. Son 30 dakikadaki hata loglarını kontrol et, son deploy'u incele ve ilgili Linear ticket'larını bul.
   

2. Prompt’u URL-encode edin: Tarayıcı konsolunda encodeURIComponent("payment-service'de hata oranı %5'in üzerinde. Son 30 dakikadaki hata loglarını kontrol et, son deploy'u incele ve ilgili Linear ticket'larını bul.") çalıştırın. Çıktı: payment-service'de%20hata%20oran%C4%B1%20%255'in%20%C3%BCzerinde.%20Son%2030%20dakikadaki%20hata%20loglar%C4%B1n%C4%B1%20kontrol%20et%2C%20son%20deploy'u%20incele%20ve%20ilgili%20Linear%20ticket'lar%C4%B1n%C4%B1%20bul.

3. Deep link’i oluşturun: Repo slug’ı acme/payment-service olduğu için link şu şekilde olur:

   claude-cli://open?repo=acme/payment-service&q=payment-service'de%20hata%20oran%C4%B1%20%255'in%20%C3%BCzerinde.%20Son%2030%20dakikadaki%20hata%20loglar%C4%B1n%C4%B1%20kontrol%20et%2C%20son%20deploy'u%20incele%20ve%20ilgili%20Linear%20ticket'lar%C4%B1n%C4%B1%20bul.
   

4. Runbook’a ekleyin: Runbook’un ilgili adımına Markdown bağlantısı olarak gömün:

   2. [payment-service'de hata araştırması başlat](claude-cli://open?repo=acme/payment-service&q=payment-service'de%20hata%20oran%C4%B1%20%255'in%20%C3%BCzerinde.%20Son%2030%20dakikadaki%20hata%20loglar%C4%B1n%C4%B1%20kontrol%20et%2C%20son%20deploy'u%20incele%20ve%20ilgili%20Linear%20ticket'lar%C4%B1n%C4%B1%20bul.)
   

5. Test edin: Kendi makinenizde bağlantıya tıklayın. Claude Code’un acme/payment-service klonunda yeni bir terminal penceresi açtığını ve prompt kutusunun hazır metinle doldurulduğunu doğrulayın.

6. Sorun giderme: Eğer bağlantı tıklanabilir değilse (örneğin GitHub wiki’sinde), linki bir kod bloğu içine alın:

   2. Aşağıdaki bağlantıyı kopyalayıp tarayıcı adres çubuğuna yapıştırın:
      `claude-cli://open?repo=acme/payment-service&q=payment-service'de%20hata%20oran%C4%B1%20%255'in%20%C3%BCzerinde.%20Son%2030%20dakikadaki%20hata%20loglar%C4%B1n%C4%B1%20kontrol%20et%2C%20son%20deploy'u%20incele%20ve%20ilgili%20Linear%20ticket'lar%C4%B1n%C4%B1%20bul.`
   

Bu sayede olay yönetimi yapan her mühendis, runbook’taki adıma tıklayarak (veya URL’yi yapıştırarak) saniyeler içinde araştırmaya başlayabilir.