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

Adres: https://agentvera.dev/blog/claude-code-headless-mod/ · Yayın: 2026-10-27

Claude Code headless mod: claude -p, JSON ve stream-json çıktısı, --allowedTools, --max-turns, --bare, oturuma devam, boru ile girdi ve cron ile CI’da kullanım.

**Kısaca:**

- claude -p "prompt", Claude Code’u etkileşimli arayüz olmadan bir kez çalıştırır, sonucu yazdırır ve başarıda 0 ile çıkar; bu yüzden kabuk betiklerine, cron işlerine, git hook’larına ve CI’a uyar.
- Ayrıştırılabilir tek bir nesne (result, session_id, maliyet tahmini) için --output-format json, canlı olaylar için --verbose ile stream-json kullan; --json-schema doğrulanmış yapılandırılmış çıktı döndürür.
- Araçları --allowedTools ile önceden onayla, gerisini --permission-mode dontAsk ile reddet, çalıştırmaları --max-turns ile sınırla ve --bare ekle ki yerel hook’lar, MCP sunucuları ve CLAUDE.md yok sayılsın.

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

```bash
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:

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

```bash
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:

```json
{
  "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:

| Biçim | Ne alırsın | Ne için kullanılır |
| --- | --- | --- |
| `text` (varsayılan) | Düz metin olarak son cevap | İnsanlar, dosyalar, basit betikler |
| `json` | Sonda tek bir JSON nesnesi | Cevabın yanında meta veriye ihtiyaç duyan betikler |
| `stream-json` | Olduğu anda satır başına bir JSON olayı | Canlı ilerleme, özel arayüzler, loglama |

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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

| Mod | Headless bir çalıştırmadaki davranışı |
| --- | --- |
| `dontAsk` | Önceden onaylanmayan her şey reddedilir. Betikler için öngörülebilir seçim |
| `acceptEdits` | Dosya düzenlemelerine sormadan izin verilir |
| `plan` | Yalnızca okuma ve planlama, düzenleme yok |
| `auto` | Her eylemi bir sınıflandırıcı inceler; engellenen eylem reddedilir ve çalıştırma devam eder |
| `bypassPermissions` | Hiçbir kontrol yok. Yalnızca atılabilir bir kapsayıcı ya da VM içinde |

**`--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](/blog/claude-code-izinleri-atlamak/ "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.

```bash
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:

| Yüklenecek | Bayrak |
| --- | --- |
| Ek talimatlar | `--append-system-prompt`, `--append-system-prompt-file` |
| Ayarlar | `--settings <file-or-json>` |
| MCP sunucuları | `--mcp-config <file-or-json>` |
| Özel ajanlar | `--agents <file-or-json>` |
| Bir eklenti | `--plugin-dir <path>` |

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:

```bash
# 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:

```bash
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:

```bash
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

```bash
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

```bash
# 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](/blog/claude-code-gece-calistirma/ "Claude Code’u gece çalıştırmak"), her işletim sistemindeki zamanlayıcılar için de [Claude Code görevlerini zamanlamak](/blog/claude-code-zamanlanmis-gorevler/ "Claude Code zamanlanmış görevler") 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](/blog/claude-code-github-actions/ "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](/blog/claude-code-en-iyi-pratikler/ "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](/ozellikler/zamanlanmis-gorevler/ "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](/ozellikler/otomasyonlar/ "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](/ozellikler/ci-cd-merkezi/ "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ı](/ozellikler/gece-vardiyasi/ "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](/indir/ "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.

## Sık sorulanlar

**Claude Code headless mod nedir?** Claude Code’un -p (ya da --print) bayrağıyla etkileşimsiz çalıştırılmasıdır. Bir prompt verirsin, Claude izin verdiğin araçlarla işi yapar, sonucu stdout’a yazdırır ve çıkar. Çıkış kodu 0 başarı, sıfırdan farklı bir kod çalıştırmanın başarısız olduğu anlamına gelir; betikler buna göre dallanabilir.

**claude -p’nin sormadan dosya düzenlemesine nasıl izin veririm?** Araçları --allowedTools ile listele, örneğin --allowedTools "Read,Edit,Bash(npm test *)". Ekim 2026 itibarıyla hiçbir şey mod belirlemiyorsa -p çalıştırmaları Manual modda başlar ve onay gerektiren araç çağrıları reddedilir. Bunu açık hale getirmek için --permission-mode dontAsk, tüm dosya düzenlemelerine izin vermek için acceptEdits ekle.

**Claude Code’dan JSON çıktısı nasıl alırım?** --output-format json ekle. Yanıt tek bir JSON nesnesidir: cevap result alanında, yanında session_id, kullanım bilgileri ve bir total_cost_usd tahmini. Metni almak için jq -r ".result" ile boru kullan. structured_output içinde doğrulanmış veri almak için --json-schema ekle ve alanı kullanmadan önce var olduğunu kontrol et.

**Headless bir Claude Code oturumuna devam edebilir miyim?** Evet. claude -p "next step" --continue, geçerli klasördeki en son konuşmayı sürdürür. Belirli bir oturumu hedeflemek için bir JSON çalıştırmasından session_id’yi yakala ve --resume’a ver; Claude Code o makinedeki herhangi bir klasörden oturumu ID ile bulur.

**Headless mod Claude aboneliğimi mi yoksa API anahtarını mı kullanır?** Normal bir -p çalıştırması makinede hangi giriş varsa onu kullanır. --bare ile Claude Code OAuth bilgilerini ya da anahtar zincirini hiç okumaz; bu yüzden ANTHROPIC_API_KEY’e ya da --settings JSON’unda bir apiKeyHelper’a ihtiyaç duyar. Abonelikle CI için claude setup-token uzun ömürlü bir OAuth token’ı üretir.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/