Tmux ve Claude Code: Oturumlar, Send-Keys ve Sınırlar

tmux, yapay zeka kodlama ajanlarınızı kapalı bir terminalden veya kopan bir SSH bağlantısından etkilenmeyen, isimlendirilmiş ve ayrılabilir (detachable) oturumlarda çalıştırır. Tek bir pencerede birden fazla ajanı barındırabilir, bir betik üzerinden herhangi birine yazmak için send-keys komutunu kullanabilir ve ekran çıktısını okumak için capture-pane özelliğinden yararlanabilirsiniz. Yazılım geliştiricilerin bu ikiliyi tercih etmesinin temel nedeni tam olarak bu güçlü kombinasyondur.

Her şeyi sıfırdan inşa etmeye başlamadan önce yerleşik çözümü kontrol etmekte fayda var: Claude Code'un güncel sürümleri, claude --worktree --tmux komutu ile sizin için hem git çalışma ağacını (worktree) hem de tmux oturumunu otomatik olarak oluşturabilir. Bu rehberde önce yerleşik özelliği, ardından bu özelliğin kapsamadığı alanları ve proje bazlı oturum yönetimini inceleyeceğiz.

Tmux ve Ajanlar Neden Birlikte Çok İyi Çalışır?#

Bir kodlama ajanı, terminalle sürekli iletişim halinde kalmak isteyen uzun süreli bir süreçtir (long-running process). Tmux'un üç temel özelliği bu yapıya kusursuz şekilde uyum sağlar:

• Bağlantı kopmalarına karşı dayanıklıdır: Sanal terminale (pty) kendi terminal pencereniz değil, doğrudan tmux sunucusu sahiptir. Pencereyi kapatsanız, SSH bağlantınız kopsa veya bilgisayarınızı uyku moduna alsanız bile ajan çalışmaya devam eder; tekrar bağlandığınızda (reattach) bıraktığınız yerde sizi bekler.
• Tek pencerede çoklu oturum barındırır: Dört farklı ajan, uygulama değiştiricide aradığınız dört ayrı pencere yerine, tek bir tuş vuruşuyla aralarında geçiş yapabileceğiniz dört isimlendirilmiş oturuma dönüşür.
• Dışarıdan betiklerle yönetilebilir (scriptable): Herhangi bir kabuk (shell), çalışan bir ajana komut gönderebilir veya ekranını okuyabilir. Ekstra bir IPC ( Süreçler Arası İletişim) kurmanıza veya API bağlamanıza gerek kalmaz. Ajan orkestrasyonu betiklerinde tmux'un sürekli karşımıza çıkmasının nedeni bu pratik özelliktir.

Kendi Sisteminizi Kurmadan Önce: Yerleşik Bayraklar#

Claude Code, tek bir dal (branch) üzerinde çalışan tekil ajan senaryoları için hazır parametrelerle gelir. Güncel sürümdeki claude --help çıktısında yer alan iki önemli bayrak şunlardır:

• -w, --worktree [name]: Bu oturum için yeni bir git worktree oluşturur (isteğe bağlı olarak isimlendirilebilir).
• --tmux: Çalışma ağacı için bir tmux oturumu başlatır (--worktree gerektirir). Mevcut olduğunda iTerm2 yerel bölmelerini (native panes) kullanır; geleneksel tmux için --tmux=classic kullanılır.

Böylece bir görevi izole edip ona özel oturum açma işlemi tek bir komuta iner:

claude --worktree --tmux
# veya çalışma ağacına özel bir isim vererek:
claude --worktree auth-refactor --tmux

Pratik geliştirme sürecinde bu komuta güvenmeden önce iki kritik detaya dikkat etmelisiniz:

1. --tmux bayrağı --worktree olmadan hata verir; yani genel bir oturum açma bayrağı değil, oturum oluşturan bir çalışma ağacı özelliğidir.
2. iTerm2 kullanıyorsanız varsayılan olarak yerel bölmeleri tercih eder. Bu görsel olarak hoş olsa da standart tmux komutlarının bağlanabileceği gerçek bir oturum oluşturmaz. Oturumu betiklerle yönetmeyi planlıyorsanız gerçek tmux altyapısı için mutlaka --tmux=classic parametresini geçmelisiniz.

Tek bir dalda tek bir ajan çalıştıracaksanız en pratik çözüm budur. Ancak bu yerleşik yöntem; tek oturumda birden fazla ajan çalıştırmayı, izlemek için bölmeleri (panes) dizmeyi, dışarıdan bir betikle ajana komut yazmayı, hangi ajanın sizden yanıt beklediğini bildirmeyi veya tüm bunları SSH üzerinden uzak bir sunucuda kurmayı kapsamaz. İşte bu noktalar, geliştiricilerin manuel tmux yapılandırmasına geçtiği yerlerdir.

Proje Bazlı İsimlendirilmiş Oturumlar#

Sistemi kullanılabilir ve düzenli tutan temel organizasyon kuralı şudur: Görev veya ajan başına değil, her depo (repo) için depo adıyla isimlendirilmiş tek bir tmux oturumu açmak. Görevler gelip geçicidir ancak proje kalıcıdır.

# Bir proje dizininde arka planda (detached) oturum başlatma
tmux new-session -d -s api -c ~/code/api

# Oturuma bağlanma (eğer yoksa otomatik oluşturur)
tmux new-session -A -s api -c ~/code/api

Buradaki -A parametresi "bağlan veya oluştur" (attach-or-create) anlamına gelir. Tek bir komutu tekrar tekrar güvenli bir şekilde çalıştırmanızı sağlar. Bunu kabuk yapılandırmanızda (~/.zshrc) bir fonksiyona dönüştürerek iş akışınızı hızlandırabilirsiniz:

# ~/.zshrc
agent() {
  local dir="${1:-$PWD}"
  local name="$(basename "$dir")"
  tmux new-session -A -s "$name" -c "$dir"
}