Claude Code headless mod: betikler ve CI için claude -p

Claude Code headless mod, -p bayrağıdır. claude -p "prompt’un", Claude Code’u etkileşimli arayüz olmadan bir kez çalıştırır: prompt’unu (ve boru ile verdiğin her şeyi) okur, izin verdiğin araçlarla çalışır, sonucu yazdırır ve çıkar. Çıkış kodu 0 başarı, diğer her şey çalıştırmanın başarısız olduğu anlamına gelir. Bu da onu kabuk betiklerine, cron işlerine, git hook’larına ve CI hatlarına koyabileceğin sıradan bir komut satırı aracına dönüştürür.

Bu rehber gerçekten kullanacağın bayrakları anlatıyor: çıktı biçimleri, araç izinleri, tur ve bütçe limitleri, --bare, oturumlara devam etme ve veri borulama; ardından betikler, cron ve CI için kullanıma hazır kalıplar ve ne zaman Agent SDK’ya geçmen gerektiği geliyor. Buradaki her bayrak Ekim 2026 itibarıyla resmi CLI başvurusuna göre kontrol edildi.

Temeller

claude -p "What does the auth module do?"

-p ve --print aynı bayrak. Etkileşimli seçeneklerin çoğu onunla birlikte kullanılabilir; örneğin --model, --effort, --append-system-prompt ve --mcp-config. Birkaç seçenek yalnızca print modunda var; aralarında --max-turns, --max-budget-usd, --json-schema ve --no-session-persistence bulunuyor.

Betikler için iki ayrıntı önemli:

• Geçersiz bir bayrak verirsen hata, çalıştırma başlamadan stderr’e gider.
• Çalıştırmanın içinde bir şey başarısız olursa, örneğin kimlik doğrulama eksikse, hata stdout’a sonuç olarak yazdırılır. Yalnızca çıktıya değil, çıkış koduna bak.

Veriyi boru ile ver, sonucu yönlendir

Headless mod stdin’i okur; böylece loglar, diff’ler ve dosyalar her Unix aracında olduğu gibi içeri akar:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

git diff main | claude -p "Review this diff for bugs. List each as file:line and one sentence."

Boru ile verilen stdin 10MB ile sınırlı. Bunun üzerinde Claude Code hatayla çıkar; büyük girdiler için içeriği bir dosyaya yaz ve prompt’ta yolunu belirt.

Resmi belgelerin bir yazım hatası linter’ıyla yaptığı gibi bunu package.json’a da bağlayabilirsin:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Bir çıktı biçimi seç

--output-format üç değer alır:

JSON nesnesi cevabı result alanında taşır; yanında session_id, kullanım rakamları ve total_cost_usd bulunur. Bu maliyet istemci tarafında yapılan bir tahmindir ve faturandan farklı olabilir.

claude -p "Summarize this project" --output-format json | jq -r '.result'

—json-schema ile yapılandırılmış çıktı

Bir betik düz yazı yerine veriye ihtiyaç duyduğunda bir JSON Schema ver. Doğrulanmış sonuç structured_output alanına düşer:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Çalıştırma geçerli bir yapılandırılmış çıktı olmadan biterse, örneğin Claude reddettiği için, alan eksik olur. Kullanmadan önce kontrol et:

out=$(claude -p "Extract the main function names from auth.py" --output-format json --json-schema "$(cat schema.json)")
echo "$out" | jq -e '.structured_output' > /dev/null || { echo "no structured output" >&2; exit 1; }

Akış olayları

stream-json, --verbose gerektirir. Token’ları üretildikçe almak için --include-partial-messages ekle. Şu komut yalnızca akan metni yazdırır:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

İlk olay normalde model, araçlar, MCP sunucuları ve eklentilerle birlikte system/init’tir. Son satır, son metni, maliyeti ve oturum meta verisini içeren bir result mesajıdır. Yeniden denemeler system/api_retry olayları olarak görünür. Faydalı bir CI kapısı: --mcp-config verdiğinde doğrulamayı geçemeyen bir sunucu girdisi çalıştırmayı başarısız kılmadan atlanır ve init olayındaki mcp_server_errors içinde görünür. Bu dizi boş değilse işi başarısız say.

Çalıştırmanın neler yapabileceğini kontrol et

Bir betikte izin sorusunu yanıtlayacak kimse yok; bu yüzden Claude’un ne yapabileceğine baştan karar ver.

--allowedTools izin kuralı sözdizimiyle araçları önceden onaylar:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

*’dan önceki boşluk önemli: Bash(git diff *) git diff ile başlayan komutlarla eşleşir, Bash(git diff*) ise git diff-index ile de eşleşir.

--permission-mode, listelenmeyen her şey için temel davranışı belirler. Ekim 2026 itibarıyla (Claude Code v2.1.302 ve sonrası) hiçbir şey mod belirlemiyorsa bir -p çalıştırması Manual modda başlar ve onay gerektiren bir çağrı reddedilir. İşe yarayan değerler:

--tools hangi yerleşik araçların var olacağını kısıtlar, --disallowedTools de deny kuralları ekler. --permission-prompts none, Claude’a istekleri onaylayabilecek kimse olmadığını söyler, böylece onları yeniden denemeye devam etmez; reddedilenler son sonuçtaki permission_denials içinde listelenir. Kendi makinende izinleri atlamanın neden riskli olduğu Claude Code izinleri atlamak yazısında anlatılıyor.

Gözetimsiz her çalıştırmaya limit koy

• --max-turns 20, o kadar ajan turundan sonra durur ve hatayla çıkar. Varsayılan olarak limit yok.
• --max-budget-usd 5.00, tahmini harcama bu tutara ulaştığında durur. İstemci tarafındaki tahmini kullanır ve harcama sınırı biraz aşabilir; pay bırak.
• Kabuğundan ya da CI adımından gelen timeout yine de olması gereken bir şey. Bir çalıştırmayı SIGTERM ile durdurursan Claude Code 143 koduyla çıkar, bitmemiş tur için sonuç kaydetmez ve SessionEnd hook’larını yine de çalıştırır.

Tekrarlanabilir çalıştırmalar için —bare kullan

--bare olmadan claude -p, etkileşimli bir oturumla aynı şeyleri yükler: hook’lar, skill’ler, eklentiler, MCP sunucuları, otomatik bellek ve CLAUDE.md; hem çalışma klasöründen hem de ~/.claude’dan. Bu da aynı komutun dizüstü bilgisayarında ve bir CI runner’ında farklı davranması demek.

claude --bare -p "Summarize README.md" --allowedTools "Read"

--bare tüm bu keşfi atlar ve daha hızlı başlar. Yalnızca çalıştırmanın ihtiyaç duyduğunu verirsin:

Bare mod OAuth bilgilerini ya da sistem anahtar zincirini hiç okumaz. Anthropic API ile ANTHROPIC_API_KEY’i ayarla ya da --settings JSON’unda bir apiKeyHelper ver. Resmi belgeler betikli çağrılar için --bare öneriyor ve gelecekteki bir sürümde -p için varsayılan olacağını söylüyor; bu yüzden onu şimdiden açıkça yazmak, o gün geldiğinde betiklerini sabit tutar.

Önemsemen için bir sebep daha: --bare olmadan, yeni klonlanmış bir repoda çalışan bir -p çalıştırması o reponun proje hook’larını ve .mcp.json sunucularını güven diyaloğu olmadan çalıştırır. Bare olmayan bir headless çalıştırmayı incelemediğin koda yöneltme.

Oturumlara devam et ve kaldığın yerden aç

Headless çalıştırmalar etkileşimli olanlar gibi kaydedilir; böylece adımları zincirleyebilirsin:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Aynı anda birkaç çalıştırma olduğunda --continue yanlışını seçebilir. Bunun yerine oturum ID’sini yakala:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

--resume, oturumu makinedeki herhangi bir klasörden ID ile bulur; bir adı ya da bir oturumun .jsonl dökümünün yolunu da kabul eder. --fork-session, devam ettirilen konuşmaya eklemek yerine ondan yeni bir dal başlatır; --no-session-persistence de tek seferlik çalıştırmaların hiç kaydedilmemesini sağlar.

Betikler, cron ve CI için kalıplar

Dosyalar üzerinde bir döngü

Resmi en iyi pratikler sayfasında, birçok dosyaya yayılan mekanik bir değişiklik için iyi bir şablon var:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

Önce üç dosyada çalıştır, commit’leri oku, prompt’u düzelt, sonra gerisini çalıştır. Tur limitine ulaşan bir çalıştırma hatayla çıkar; döngün bunu loglayabilir.

Bir inceleme betiği

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Bunu review.sh olarak kaydet ve bash review.sh 123 çalıştır; inceleme metni result içinde.

Gecelik bir cron işi

# crontab -e
0 2 * * * cd /srv/app && claude --bare -p "Run the test suite, fix failing tests, commit on the current branch. Do not push." --allowedTools "Read,Edit,Bash(npm test *),Bash(git add *),Bash(git commit *)" --permission-mode dontAsk --max-turns 30 --output-format json >> /var/log/claude-nightly.jsonl 2>> /var/log/claude-nightly.err

Cron en az ortamla çalışır; claude’un PATH üzerinde olduğundan ve o kullanıcı için ANTHROPIC_API_KEY’in ayarlı olduğundan emin ol. Bunu main üzerinde değil, bir dalda ya da bir worktree’de çalıştır. --worktree eklersen -p --worktree çalıştırmalarının senin yerine temizlenmediğini unutma; onları git worktree remove <path> ile sil. Bütçeler ve sabah incelemesiyle tam gece kurulumu için Claude Code’u gece çalıştırmak, her işletim sistemindeki zamanlayıcılar için de Claude Code görevlerini zamanlamak yazısına bak.

CI hatları

CI’da --bare kullan, API anahtarını CI’ın gizli bilgi deposunda tut ve çıkış kodunu adımın sonucu olarak kabul et. Özellikle GitHub için resmi action bunu PR yorumları ve @claude anmalarıyla senin için sarmalıyor: Claude Code GitHub Actions yazısına bak. API anahtarı yerine abonelik kullanıyorsan claude setup-token, CI ve betikler için uzun ömürlü bir OAuth token’ı yazdırır; kaydedilmez, o yüzden hemen bir gizli bilgi olarak sakla. --bare’in OAuth’u yok saydığını unutma; abonelik token’ı bare olmayan bir çalıştırma gerektirir.

Tuzaklar

• Skill’ler ve slash komutları. Kullanıcı skill’leri, prompt’a /skill-name yazarsan çalışır. /login gibi yalnızca terminal arayüzünde var olan komutlar çalışmaz.
• Sessiz araç reddi. Claude bir şeyi yapamadığını söylüyorsa JSON sonucundaki permission_denials’a bak ve eksik kuralı --allowedTools’a ekle.
• Arka plan işleri. Bir -p çalıştırması, Claude’un başlattığı arka plan komutlarını ya da alt ajanları beklemek için açık kalabilir; varsayılan olarak 10 dakika boşta kaldıktan sonra beklemeyi bırakır.
• Sistem prompt’unu değiştirmek. --system-prompt, git durum anlık görüntüsü de dahil varsayılan prompt’u tamamen değiştirir. Boş bir sayfa istediğinden emin değilsen --append-system-prompt’u tercih et.

Ne zaman Agent SDK’ya geçmeli

claude -p, bir CLI’ın arkasındaki Agent SDK motorudur. Betiğin akışları ayrıştırmaya, onayları yönetmeye ya da çok sayıda oturumu idare etmeye başladığında Python ya da TypeScript için Agent SDK’ya geç. Kabuğa çıkmadan, kodda yerel mesaj nesneleri, araç onayı callback’leri ve yapılandırılmış çıktılar verir. Herhangi bir çalıştırma gözetimsiz kalmadan önce neleri yerine koyman gerektiği Claude Code en iyi pratikler yazısında.

AgentVera ile yapmak

Headless çalıştırmalar ateşle ve unut türündendir; bazen aynı otomasyonu izleyebileceğin bir terminalle istersin. AgentVera’da zamanlanmış görevler (her planda) uygulama açıkken bir cron takvimine göre bir ajana prompt gönderir ve ajan, açıp yönlendirebileceğin gerçek bir panelde çalışır. Otomasyonlar (Pro ve Team) CI kırmızıya döndüğünde ya da bir PR yorum aldığında bir ajan başlatır ve varsayılan dala asla push yapmaz. CI/CD merkezi GitHub Actions, GitLab ve Jenkins çalıştırmalarını listeler ve başarısız bir logu bir ajana devredebilir. Gece vardiyası (Pro ve Team) sıraya alınmış işleri gece boyunca bir worktree’de, night/<date>-<slug> dalında çalıştırır, push yapmadan commit atar ve bir sabah raporu bırakır. Bu çalıştırmaların bir log dosyasına gömülmek yerine görünür olmasını istiyorsan AgentVera’yı indir.

Toparlarsak

Headless Claude Code için temel tarif kısa: claude --bare -p "clear task with a check", açık bir --allowedTools listesi, --permission-mode dontAsk, --max-turns, --output-format json ve betiğinin dikkate aldığı bir çıkış kodu. Küçük başla, ilk çalıştırmaların ne ürettiğini oku ve ancak ondan sonra bir zamanlayıcıya bağla.