atl setup-hooks

ATL'nin otomasyon hook'larını Claude Code'a kur; böylece platform kendi kendini bakımlı tutar — senden hiçbir elle iş beklemez.

v2'de otomasyon zorunludur, isteğe bağlı değil: atl install bu hook'ları zaten senin için bağlar. atl setup-hooks komutunu doğrudan yalnızca hook'ları ayrıca (yeniden) kurmak istiyorsan ya da kısıtlama aralığını değiştirmek istiyorsan çalıştırırsın.

Kullanım

atl setup-hooks                    # varsayılan 10 dakikalık tick kısıtlamasıyla kur
atl setup-hooks --throttle=5m      # oturum içinde daha sık tick (her 5 dakikalık etkinlikte)
atl setup-hooks --throttle=1h      # daha seyrek tick

--throttle yalnızca atl tick UserPromptSubmit hook'unu etkiler; atl retrieve (istem başına getirme hook'u) kısıtlamasızdır ve ucuzdur, SessionStart ise her zaman tam olarak çalışır.

Ne yapar?

~/.claude/settings.json dosyasına beş giriş yazar:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [
          { "type": "command", "command": "atl session-start" }
      ]}
    ],
    "UserPromptSubmit": [
      { "hooks": [
          { "type": "command", "command": "atl tick --throttle=10m" }
      ]},
      { "hooks": [
          { "type": "command", "command": "atl retrieve" }
      ]}
    ],
    "PreToolUse": [
      { "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": "atl guard" }
      ]}
    ],
    "Stop": [
      { "hooks": [
          { "type": "command", "command": "atl retrieve turn-end" }
      ]}
    ]
  }
}

Claude Code şunları kendiliğinden çalıştırır:

SessionStart — açılış zamanı bakımı

Yeni bir Claude Code oturumu açtığında bir kez çalışır. atl session-start, açılış zamanına ait işleri sırayla yapar:

1. Platform çekirdeğini yansıt — ikili içindeki kuralları ve becerileri global ~/.claude katmanına yeniler; yüklü atl sürümüyle eş adım kalır ve /rule ile yazdığın kuralları Claude yükleme yüzeyine (~/.claude/rules/) yansıtır.
2. Önceki oturumu drenaj et — bu projenin son drenajdan bu yana değişen transkriptlerini bulur, asistan metnini çıkarır ve satır içi <!-- learning: ... --> işaretçilerini ~/.atl/queue.db adresindeki kalıcı kuyruğa tam olarak bir kez aktarır. Aynı geçiş yakalama bekçisini de çalıştırır: en yeni oturum özlü ama işaretçisiz bir seriyle bittiyse, tek satırlık gözden-geçirme dürtmesini yazdırır (atl tick, 5. adım) — serisi fark edilmeden kapanan bir oturum için son-yakalama.
3. Doctor öz-denetimi — kuyruk sağlığı ile varlık bütünlüğü denetimlerini çalıştırır; sorunları yüzeye çıkarır ya da otomatik olarak iyileştirir.
4. Bekleyen öğrenmeleri sinyal et — kuyrukta işlenmemiş öğrenmeler varsa atl: N learning(s) pending — auto-drain them now in a background subagent (per the learning-capture rule) tek satırını yazdırır; Claude ardından bunları otomatik olarak katan tek bir arka plan /drain alt-ajanı (subagent) başlatır.
5. Otomatik güncelleme, kısıtlamalı (arka plan) — günde en çok bir kez, daha yeni bir atl sürümü olup olmadığını denetler ve varsa ayrık (detached) bir atl upgrade başlatır; ayrıca proje başına günde bir kez, daha yeni yayınlanmış takım sürümlerini çekmek için ayrık bir atl update başlatır. İkisi de arka planda çalışır, böylece açılışı asla engellemez ve bir sonraki oturum taze ikili / takımlarla çalışır. Devre dışı bırakmak için ATL_NO_SELF_UPDATE ya da ATL_NO_TEAM_UPDATE ayarla.
6. Getirme dizinini yenile (arka plan) — bu projenin bilgi külliyatı (wiki + journal, ayrıca bir delivery projesinin docs/ ağacı) son derlemeden bu yana değiştiyse, istem başına getirme hook'unun taze bir dizini olması için ayrık (detached) bir atl retrieve index başlatır. Kısıtlamalıdır, git worktree'leri içinde atlanır ve ATL_NO_RETRIEVE_INDEX ile devre dışı bırakılır.
7. Getirme çevirisi kimlik bilgisi bildirimi — bu projede bir getirme dizini varken çevirmenin kimlik bilgisi yoksa, bunun neye mal olduğunu yazdırır: bilgi tabanın İngilizce olduğu için İngilizce olmayan bir istem iki kol yerine tek kolla arar. Kimlik bilgisini bir hook'a ulaştırmayan iki yer vardır ve bildirim önce onları adıyla söyler — ~/.claude/settings.json içindeki env bloğu (Claude Code değişkeni kendi sürecinde tutar ve başlattığı hiçbir alt sürece geçirmez) ve ~/.zshrc (zsh bunu yalnızca etkileşimli kabuklarda okur). İşe yarayanlar: yalnızca token'ı içeren düz bir dosya olan ~/.atl/claude-token, ya da zsh'ın her çağrıda okuduğu ~/.zshenv içinden dışa aktarılan CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY. Kimlik bilgisi varsa ama son üç çeviri denemesi çalışamadıysa, ayrı bir bildirim bunun büyük olasılıkla süresi dolmuş bir kimlik bilgisi olduğunu söyler ve senin yapılandırdığın kaynağı adıyla anar. Bilgilendirmedir, asla bir kapı değil — getirme onsuz da çalışır — ve her oturumda yeniden yazdırılır; çünkü kendini yalnızca bir kez duyuran bir kurulum adımı, kaçırılan adımdır. Bilgi sistemi kılavuzuna bak.

SessionStart, hook stdout çıktısını Claude'un bağlamına ileten tek Claude Code olayıdır; dolayısıyla session-start komutunun yazdığı her şey Claude'a ulaşır — kurulu birimlerin yanında sahipsiz dosyalar durduğunda bir gc yetim-farkındalık satırı (atl: N orphaned file(s) beside installed units — run atl gc to review) dahil. Yüzeye çıkarılacak bir şey yoksa sessiz kalır; sıradan bir açılış hiçbir ek maliyete yol açmaz.

UserPromptSubmit — kısıtlamalı oturum içi tick

Claude'a gönderdiğin her mesajdan önce çalışır. atl tick --throttle=10m, her komut çağrısında ucuz işleri, kısıtlama penceresi boyunca ise yalnızca bir kez daha ağır işleri yapar:

• Fan-out (her çağrıda, nesil korumalı) — global katman bu proje son fan-out'undan bu yana değiştiyse güncellenen varlıkları çeker. Aksi hâlde tek bir küçük dosya okumasıdır; her mesaja binecek kadar ucuzdur.
• Drenaj + doctor (kısıtlamalı) — bu projenin transkriptlerini yeni işaretçiler için yeniden tarar, canlı oturum üzerinde yakalama bekçisini çalıştırır (işaretçisiz kuru seri başına bir kez, tek satırlık dürtme — atl tick, 5. adım) ve doctor öz-denetimini çalıştırır. Son tick kısıtlama penceresi içindeyse atlanır; mesaj başına maliyet tek bir dosya-bilgisi çağrısına düşer.
• Kazanımları yükselt (kısıtlamalı) — bu projenin birikmiş kazanımlarını global katmana taşır (katkılı, çakışma arşivleme, sabitlenebilir); elle atl promote çalıştırmayı beklemeden dolaşıma girer.

Bir şey yüzeye çıktığında Claude bağlamında ilgili satırı görür ve bunu kısaca belirtebilir. Hiçbir şey değişmediğinde hiçbir şey görmezsin.

UserPromptSubmit — istem başına bilgi getirme

Tick'in yanı sıra ikinci bir UserPromptSubmit girişi atl retrieve çalıştırır: bu projenin bilgi sayfalarını (wiki + journal) her isteme karşı sıralar — BM25 ile yerel bir anlamsal gömücü (embedder) birleştirilerek — ve en iyi eşleşmeleri bağlam olarak yüzeye çıkarır; böylece Claude yanıtlamadan önce en ilgili sayfalara başvurur. Bir delivery projesi (bir .delivery/config.json içeren) ayrıca depo içi docs/ ağacını wiki + journal ile birlikte dizinler. Hataya-açık (fail-open) çalışır: herhangi bir hata hiçbir şey yazdırmaz ve istemi asla engellemez. Bilgi sistemi kılavuzuna bak.

Stop — turun tamamlandığını kaydeder

Bir tur bittiğinde çalışır. atl retrieve turn-end retrieval ateşleme günlüğüne tek satır yazar ve hiçbir şey yazdırmaz; dolayısıyla Claude'un bağlamına ulaşmaz ve bir yanıtı etkilemez.

Tek bir sorunun cevaplanabilir olması için vardır: retrieval'ın yüzeye çıkardığı şeye kimse göre hareket ediyor mu? Bir tur işareti olmadan ateşleme günlüğü neyin sunulduğunu kaydeder, sonrasında ne olduğuna dair hiçbir şey kaydetmez; böylece "bu kanalı iyileştirmeye değer mi?" sorusu ancak tüm transkript üzerinde adli bir taramayla cevaplanabilir. atl retrieve stats danışma oranını buradan okur.

PreToolUse — uygulama muhafızı

Her Bash, Edit ve Write araç çağrısından önce çalışır (hook'un matcher alanıyla kapsamlanır). atl guard, ATL'nin disiplinini modelin atlayabileceği bir metin yerine deterministik bir uygulama olarak işletir — tersine çevrilebilirliğe göre ayrılmış iki katmanda:

• Felaket katmanı (engeller) — tersine çevrilemez bir Bash işlemi, gerekçesi Claude'a gösterilerek doğrudan reddedilir; böylece Claude güvenli bir yol seçebilir. Sabit küme: git push --force (yerine --force-with-lease kullan), git reset --hard, git clean -f, çalışma ağacını gözden çıkarma (git checkout . / git checkout -- <yol> / git checkout -f / git restore <yol> — git checkout main gibi bir dal değiştirme izinli kalır, yalnızca indeksten çıkaran git restore --staged de öyle), yıkıcı SQL (DROP TABLE / DROP DATABASE / TRUNCATE) ve commit/push kapısını atlayan --no-verify. rm -rf / ve rm -rf ~ bilerek dışarıda bırakıldı — Claude Code bunları bypass kipinde bile zaten kendisi engeller.
• Kalite katmanı (asla engellemez) — bağlam olarak enjekte edilen, izin kararı taşımayan üç uyarı; ikisi de ne akışı böler ne de onayına sunulanı değiştirir. Bir oturumda mevcut bir dosyayı ilk kez düzenlediğinde grep-before-edit hatırlatması (aynı dosyanın ikinci düzenlemesi sessizdir; yeni dosya oluşturmak muaftır). Ve bir Bash komutu boru hattından sonra $? okuduğunda, o durumun son komuta — içine boru yaptığın head/tail/grep'e — ait olduğunu hatırlatır; böylece çıktısını süzdüğün başarısız bir komut başarı bildirmez. pipefail verirsen uyarı susar, çünkü o zaman kastettiğin gerçekten boru hattının durumudur. Bir de: bir commit mesajını son yazılmasının üzerinden on dakikadan fazla geçmiş bir dosyadan okuduğunda, o dosyanın bu tura ait olmayabileceğini hatırlatır — onu yazması gereken heredoc hiç koşmadıysa (en sık nedeni, bu muhafızın onun parçası olduğu bileşik komutu reddetmesidir) commit doğru dosyalarla ve yanlış mesajla başarılı olur, ve bunu hiçbir şey bildirmez. Commit'ten hemen önce yazılmış bir mesaj sessiz kalır; olağan durum budur.

Muhafız her izin kipinde — bypassPermissions dahil — tetiklenir; çünkü bir PreToolUse hook'u, izin istemlerinin üstünde bir uygulama katmanıdır. Diğer hook'lar gibi çalışmanı asla başarısız kılmaz: bozuk girdi ya da herhangi bir iç hata durumunda sessiz kalır ve araç çağrısı sürer.

İşaretçi güdümlü öğrenme işlemesi Claude'a nasıl ulaşır?

Yakalama otomatiktir; yalnızca bilgi tabanına katma adımı bir Claude turu gerektirir (CLI'nin tek başına yapamayacağı LLM işi — CLI/Skill sınırı):

[N. oturumu kapatırsın]   satır içi öğrenme işaretçileri transkript dosyasında oturur
        ↓
[N+1. oturumu açarsın]
        ↓
SessionStart hook tetiklenir → atl session-start
        → önceki oturumun transkriptlerini ~/.atl/queue.db'ye drenaj eder (her işaretçi tam olarak bir kez kuyruğa girer)
        → kuyrukta bekleyen öğrenmeler varsa `atl: N learning(s) pending — auto-drain them now in a background subagent (per the learning-capture rule)` yazdırır
        ↓
Claude Code, stdout çıktısını Claude'un ilk additionalContext alanına enjekte eder
        ↓
[N+1. oturumda ilk turun]
        ↓
Claude sinyali görür, tek bir arka plan /drain alt-ajanı başlatır (aynı anda tek çalışan)
        ↓
/drain, kuyruktaki her öğrenmeyi wiki / journal / ajan KB'ye katar, ardından siler (ack)

Tek bir oturum içinde atl tick, mesajlar arasında kuyruğu güncel tutar; böylece bir sonraki session-start'ta (ya da bir sonraki atl learnings çağrısında) görülen sayı her zaman güncel olur.

İşaretçi biçimi ve kuyruk durum/peek/ack yüzeyi için atl learnings sayfasına, oturum içi döngü için atl tick sayfasına ve kuyruktaki öğrenmelerin bilgi tabanına nasıl katıldığına ilişkin ayrıntılar için /drain becerisi sayfasına bak.

Neden bu hook'lar?

Hook	Yanıtladığı soru
SessionStart (atl session-start üzerinden)	"Claude Code'u taze açıyorum — son oturumun geride bıraktıklarını drenaj et, bozuk bir şey varsa iyileştir, katlanacak öğrenmeler varsa haber ver."
UserPromptSubmit (atl tick üzerinden)	"Bu oturumda bir süredir çalışıyorum — kuyruğu güncel tut, global katman değişikliklerini çek ve kazanımları mesajlar arasında, ucuzca dolaşıma sok."
UserPromptSubmit (atl retrieve üzerinden)	"Az önce bir istem gönderdim — buna en ilgili proje bilgi sayfalarını yüzeye çıkar; böylece Claude yanıtlamadan önce onlara başvursun."
PreToolUse (atl guard üzerinden)	"Bir araç çalıştırmak üzereyim — tersine çevrilemez hataları doğrudan engelle ve bir dosyayı ilk düzenlemeden önce grep'lemeyi hatırlat."

İlk ikisi üç hızlı oturum içi döngüyü hayata geçirir (her mesajda fan-out, kısıtlamalı tick ve açılış zamanı drenajı); ikinci UserPromptSubmit girişi istem başına bilgi getirmeyi ekler; PreToolUse ise ATL'nin disiplinini eylem anında ısırır kılan uygulama katmanını ekler.

İdempotenlik — yeniden çalıştırması güvenlidir

Birleştirme, sahip olduğun diğer hook'ları korur. atl setup-hooks yeniden çalıştırıldığında (ya da aynı hook'ları bağlayan atl install çalıştırıldığında) yalnızca atl'ye ait girişlere dokunur — atl ön ekiyle başlayan her komut. settings.json dosyasındaki diğer tüm hook'lar, izinler, model ayarları ve extraKnownMarketplaces el değmemiş kalır. Yazma işlemi atomiktir.

Bunu ne zaman çalıştırmalısın?

• Etkileşimli Claude Code kullanıcıları için her zaman — atl install zaten yapar ama kısıtlamayı değiştirmek için yeniden çalıştırabilirsin.
• CI / betikli kullanım için önerilmez (hook'lar CI'da gereksiz yere tetiklenir).

Çevrimdışı davranış

Çekirdek kadans ağ gerektirmez — transkriptleri drenaj etmek, bbolt kuyruğu, doctor denetimleri ve istem başına yayma tümüyle çevrimdışı çalışır. Tek ağ geçişleri, session-start'ın kısıtlamalı, ayrık (detached) otomatik güncellemeleridir (ikili öz-güncellemesi ve takım güncellemesi); bunlar en iyi çaba iledir: çevrimdışıyken sessizce başarısız olur ve ayrık oldukları için açılışı asla engellemez. Bir hook çalışmanı asla engellememelidir; bu yüzden session-start ve tick oturumu başarısız kılmaz; bir şeyler ters giderse bir satır çıkarır (ya da sessiz kalır) ve komut istemi normal biçimde sürer.

İlgili

• atl tick — oturum içi bakım tick'i (UserPromptSubmit hook'unun çağırdığı komut)
• atl learnings — kalıcı öğrenme kuyruğunu incele (status / peek / ack)
• atl doctor — hook'ların her geçişte çalıştırdığı öz-denetim
• atl install — ilk kurulum (bu hook'ları senin için bağlar)
• CLI'yi kur — atl'yi makinene almak