Codex ile Local İş Akışı: Model ve Effort, Worktree'ler, Subagent'lar ve Hooks

Sürüm notu: Bu yazı Codex CLI 0.169.0'ı (13 Kasım 2026) ve ChatGPT desktop app'teki Codex modunu anlatır; model, effort, session, worktree, local environment, subagent, hook ve IDE extension ayrıntıları 15 Kasım 2026'da learn.chatgpt.com/docs'taki Models, Speed, Developer commands, Worktrees, Local environments, Subagents, Hooks ve Codex IDE extension sayfalarından, side chat ve subagent ayarındaki değişiklikler aynı gün Codex changelog'undan kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. Hook script'i PowerShell 7.7 ile, resmî input şemasına uyan örnek girdilerle bir test repo'sunda çalıştırılmış ve çıktısı resmî output şemasıyla doğrulanmış; hooks.json, custom agent ve config.toml dosyaları Codex'in JSON şemasıyla doğrulanmıştır.

Önce Tahmin Et

Sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) Emre, desktop app'te aynı anda iki chat'i iki ayrı worktree'de başlattı: biri sipariş listesine CSV (virgülle ayrılmış düz metin tablo formatı) export'u ekleyecek, diğeri Angular bağımlılıklarını güncelleyecekti. İkinci chat'te npm test hemen hata verdi. İki chat'in dotnet test koşuları da birbirinin verisini bozdu. Emre ayrıca iki PreToolUse hook'u yazmıştı: ilki her dosya değişikliğini log'luyor, ikincisi migration dosyalarını koruyordu; log'un her zaman korumadan önce yazılacağını varsaydı.

Tahminin ne? Worktree'de npm test neden hemen düştü? İki worktree'nin testleri neden çakıştı? Ve hook'ların sırası Emre'nin varsaydığı gibi mi? Cevaplar worktree ve hook bölümlerinde.

Model ve Reasoning Effort

15 Kasım 2026'da Models sayfası Codex için dört öneri veriyor. GPT (Generative Pre-trained Transformer; önceden eğitilmiş transformer modeli) ailesinden GPT-6 Astra en zor, uçtan uca işler için. GPT-6.1 Sol, Astra'ya yakın performansı daha düşük maliyetle verdiği için uzun ve tekrarlı işler için; Codex'te varsayılan context window'u 500.000 token. GPT-6.1 Terra yazı, görsel ve computer use işleri için, GPT-6 Luna da kapsamı net, yüksek hacimli işler için. Bookstore'da günlük iş için Sol, bir mimari kararı ya da zor bir hatayı çözmek için Astra, test çıktısı özeti ya da sınıflandırma gibi işler için Luna mantıklı bir başlangıç.

Reasoning effort modelin bir isteği ne kadar düşüneceğini belirliyor: CLI'da Low (desktop app'te Light), Medium, High, Extra High ve desteklenen modellerde Max. Belgelerin başlangıç önerisi Sol için client'ın varsayılan effort'u, Luna için High, Astra için Light. Effort değerlerinin model nesilleri arasında birebir eşleşmediği de özellikle yazılmış. Max tek bir işe daha çok düşünme süresi veriyor; Ultra ise işi subagent'lara bölüp paralel yürütüyor ve yalnız bölünebilir işlerde anlamlı. Luna Max'e kadar çıkıyor, Ultra'yı desteklemiyor.

# Session içinde: modeli değiştir, ya da yalnız effort'u değiştir
/model gpt-6.1-sol
/model --reasoning=high

# Açılışta
codex -m gpt-6-astra -c model_reasoning_effort=high

Hız ayrı bir ayar. Fast mode desteklenen modelleri hızlandırıyor ama abonelik kullanımını Standard'ın 2,5 katı hızla tüketiyor; CLI'da /fast ile açılıp kapanıyor. Maliyet tarafını yedinci yazıda ele alacağız.

Session'ları Yönetmek

Codex'te her şey bir chat. /new aynı terminal session'ında temiz bir chat açıyor; /resume kayıtlı bir chat'e dönüyor ve arama kapsamını seçtiriyor: yalnız bu dizin, bağlı worktree'lerle birlikte repo ya da her yer. /fork mevcut chat'i yeni bir ID ile kopyalayıp başka bir yaklaşımı denemeni sağlıyor. /side ise ana chat'ten ayrı bir transcript'le kısa bir yan chat açıyor: "Bu planda gözden kaçan bir risk var mı?" gibi bir soruyu ana işi bölmeden sormak için. Changelog'a göre 0.168 ile açılan features.tui_workspace yan konuşmayı ana chat'in yanında bir panelde gösteriyor, 0.169'da da birden çok yan chat sekmesi geldi.

Bir değişikliğe başlamadan önce /plan chat'i plan moduna alıyor; /goal ise chat'e "migration'ı bitir, testler yeşil kalsın" gibi kalıcı bir hedef bağlıyor. Desktop app'te her chat'in kendi projesine ya da worktree'sine bağlı bir integrated terminal'i var (Ctrl+`); Codex o terminalin çıktısını okuyabildiği için çalışan bir dev server'ı ya da düşen bir build'i işin içine katabiliyor.

Bookstore: Sipariş CSV Export'u

Bu özellik Claude Code serisinin dokuzuncu yazısındaki (/blog/claude-code-worktree-paralel-session-cloud) özellikle aynı; iki aracın aynı işte nasıl çalıştığını karşılaştırmak isteyenler için bilinçli bir seçim. Önce plan, sonra uygulama:

/plan Add GET /orders/export that returns the signed-in customer's orders as CSV
(OrderId, CreatedAt in UTC ISO 8601, Status, TotalAmount with invariant culture,
Currency). Stream the rows instead of loading all orders into memory, reuse the
existing filters of GET /orders, and add an "Export CSV" button to the My Orders
page in web/bookstore-web. List the files you will touch and the tests you will
add before changing anything.

Plan beklediğin dosyaları gösteriyorsa onay verip uygulatıyorsun. Kontrol yine senin koşunda: API tarafında dotnet test, istemci tarafında web/bookstore-web içinde npm test, sonra /diff ve git diff. Beklenmeyen bir bağımlılık (CSV için yeni bir NuGet paketi gibi) kök AGENTS.md'deki "paket eklemeden önce sor" kuralının devreye girmesi gereken yer.

Worktree'lerle Paralel Çalışmak

Worktree, aynı repo'nun Git metadata'sını paylaşan ikinci bir checkout'u. Desktop app'te composer'ın altında Worktree'yi ve başlangıç branch'ini seçip prompt'u gönderdiğinde Codex $CODEX_HOME/worktrees altında bir worktree açıyor ve orada detached HEAD durumunda çalışıyor. İş bitince ya Create branch here ile worktree'yi bir branch'e çeviriyorsun ya da Hand off ile chat'i ve kodu kendi local checkout'una taşıyorsun. Git bir branch'in aynı anda iki yerde checkout edilmesine izin vermediği için, belgelere göre aynı branch'i iki yerde açmaya çalışmak yerine Hand off kullanmak gerekiyor. CLI'da karşılıkları codex --worktree, codex exec --worktree ve session içinde /worktree.

Tahmindeki ilk sorunun cevabı burada. Worktree yalnız Git'in takip ettiği dosyalarla başlıyor; node_modules ya da restore edilmiş paketler orada yok. Desktop app'in local environment'ları bunun için: Codex yeni bir worktree açtığında çalışan bir setup script'i ve üst çubukta görünen action'lar. Configuration projenin kökündeki .codex klasöründe saklanıyor ve repo'ya commit'lenebiliyor; script'ler macOS, Windows ve Linux için ayrı yazılabiliyor. Windows'ta setup script'i agent'ın ortamında, yani WSL (Windows Subsystem for Linux; Windows içinde Linux çalıştıran katman) kullanılmıyorsa PowerShell'de çalışıyor. Bookstore'un Windows setup script'i:

dotnet restore Bookstore.slnx
Push-Location web/bookstore-web
npm ci
Pop-Location

Git'in yok saydığı ama yeni worktree'de gereken dosyalar için .worktreeinclude var; Bookstore'un secret'ları repo'da değil kullanıcı profilindeki user-secrets'ta durduğu için bu dosyaya ihtiyaç duymuyoruz. Tahmindeki ikinci sorunun cevabı da buradan çıkıyor: user-secrets profilde olduğu için her worktree aynı BookstoreDb connection string'ini okuyor ve iki paralel dotnet test aynı veritabanını değiştiriyor. Paralel çalışacaksan testleri kendi veritabanını açan bir yapıya taşı ya da her worktree'nin test koşusuna ConnectionStrings__BookstoreDb ortam değişkeniyle ayrı bir veritabanı adı ver; ng serve için de worktree başına ayrı bir port seç. Disk tarafında belgelere göre Codex varsayılan olarak yönettiği en yeni 15 worktree'yi tutuyor.

Subagent'lar

Güncel Codex sürümlerinde subagent'lar varsayılan olarak açık. Codex onları sen açıkça istediğinde ya da bir AGENTS.md veya skill talimatı istediğinde başlatıyor; her subagent kendi model ve tool çalışmasını yaptığı için tek agent'lı bir koşudan daha çok token harcıyor. Belgelerin önerisi paralel agent'ları keşif, test, triage ve log analizi gibi okuma ağırlıklı işlerde kullanmak; aynı anda kod düzenleyen agent'lar çakışma ve koordinasyon yükü getiriyor. Subagent'lar ana session'ın sandbox ve approval ayarlarını devralıyor; custom agent dosyası bunları değiştiremiyor.

Review the CSV export branch against main with parallel subagents. Use the
ef_query_reviewer agent for the queries in src/Bookstore.Api, one agent for
missing tests, and one for the Angular changes in web/bookstore-web. Wait for
all three, then summarize the findings by category with file references.

Codex default, worker ve explorer adlı yerleşik agent'larla geliyor. Kendi agent'ını .codex/agents/ (proje) ya da ~/.codex/agents/ (kişisel) altında bir TOML (anahtar-değer tabanlı configuration dosya formatı) dosyasıyla tanımlıyorsun; name, description ve developer_instructions zorunlu:

name = "ef_query_reviewer"
description = "Read-only reviewer for EF Core queries in src/Bookstore.Api. Use it to check new or changed LINQ queries for N+1 loads, missing AsNoTracking, client-side evaluation and unbounded result sets."
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
developer_instructions = """
You review EF Core code in src/Bookstore.Api. Do not edit files and never run commands that change state.
For every query you look at, report:
- loads inside loops (N+1) and missing Include or projection
- read-only queries without AsNoTracking
- filters or ordering that cannot be translated to SQL
- result sets without paging or Take
Answer with file:line references and one suggested fix per finding. Say "no findings" if there are none.
"""

"Do not edit files" bir talimat, sınır değil; belgeler custom agent talimatının ayrı bir read-only sandbox oluşturmadığını açıkça yazıyor. Kesin sınır istiyorsan review'u read-only bir session'da başlat. Proje dosyasındaki [agents] tablosuna max_concurrent_threads_per_session = 4 ekledik; subagent'ları tamamen kapatmak için agents.enabled = false kullanılıyor. Changelog'a göre 0.168'den beri features.multi_agent açıkça yazılmışsa Codex bir uyarı verip kapatma için agents.enabled'ı gösteriyor. CLI'da /subagents agent thread'leri arasında geçiş yapıyor; başka bir thread'den gelen onay isteğinde o tuşu o thread'i açıyor.

Hooks: Kuralı Zorlamak

AGENTS.md'deki "mevcut bir migration'ı düzenleme" kuralı bir talimat. Hook ise Codex'in yaşam döngüsünün belirli noktalarında senin script'ini çalıştırıyor: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, compaction ve subagent olayları. Hook'lar hooks.json dosyalarından ya da config.toml'daki [hooks] tablolarından okunuyor; proje hook'ları yalnız güvenilen projede yükleniyor. Güvenin bir adımı daha var: kurumsal olarak yönetilmeyen her hook, tanımının hash'i üzerinden onaylanmadan çalışmıyor. Yeni ya da değişmiş bir hook /hooks'ta incelenip trust edilene kadar atlanıyor.

Bookstore'un hook'u Codex'in dosya düzenleme tool'u apply_patch'i izliyor. Patch'teki *** Update File: ve *** Delete File: satırları commit'lenmiş bir migration'ı gösteriyorsa işlemi reddediyor; *** Add File: ile gelen yeni migration'lara dokunmuyor. commandWindows Windows'ta kullanılan komut; belgelerin önerisiyle script yolu Git kökünden çözülüyor, böylece Codex alt klasörde başlatılsa da hook bulunuyor:

{
  "description": "Bookstore hooks for Codex. Project hooks load only in a trusted project, and each one must be reviewed with /hooks before it runs.",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^apply_patch$",
        "hooks": [
          {
            "type": "command",
            "command": "pwsh -NoProfile -File \"$(git rev-parse --show-toplevel)/.codex/hooks/protect-migrations.ps1\"",
            "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -Command \"& (Join-Path (git rev-parse --show-toplevel) '.codex/hooks/protect-migrations.ps1')\"",
            "timeout": 30,
            "statusMessage": "Checking migration files"
          }
        ]
      }
    ]
  }
}

# PreToolUse (apply_patch): commit'lenmiş bir migration dosyasını değiştiren ya da silen patch'leri engeller.
# Yeni migration dosyaları ("*** Add File:") ve henüz commit'lenmemiş migration'lar düzenlenebilir kalır.
# Windows PowerShell 5.1 ve PowerShell 7 için yazıldı.
$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
$patch = [string]$payload.tool_input.command
if (-not $patch) { exit 0 }

$root = git -C $payload.cwd rev-parse --show-toplevel 2>$null
if (-not $root) { exit 0 }
$root = [System.IO.Path]::GetFullPath($root).TrimEnd('\', '/')

$blocked = @()
foreach ($line in $patch -split "`r?`n") {
    if ($line -notmatch '^\*\*\* (Update|Delete) File: (.+)$') { continue }

    # Patch, session dizinine göre göreli ya da mutlak bir yol kullanabilir.
    $path = $Matches[2].Trim()
    if (-not [System.IO.Path]::IsPathRooted($path)) { $path = Join-Path $payload.cwd $path }
    $full = [System.IO.Path]::GetFullPath($path)
    if (-not $full.StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)) { continue }

    $relative = $full.Substring($root.Length).TrimStart('\', '/').Replace('\', '/')
    if (-not $relative.StartsWith('src/Bookstore.Api/Data/Migrations/', [System.StringComparison]::OrdinalIgnoreCase)) { continue }

    git -C $root ls-files --error-unmatch -- $relative *> $null
    if ($LASTEXITCODE -eq 0) { $blocked += (Split-Path -Leaf $full) }
}

if ($blocked.Count -eq 0) { exit 0 }

[ordered]@{
    hookSpecificOutput = [ordered]@{
        hookEventName            = 'PreToolUse'
        permissionDecision       = 'deny'
        permissionDecisionReason = "Committed migration files cannot be changed: $($blocked -join ', '). Add a new migration with the add-migration skill."
    }
} | ConvertTo-Json -Depth 5 -Compress
exit 0

Tahmindeki üçüncü sorunun cevabı belgelerin ilk paragrafında: aynı olaya eşleşen command hook'ları eşzamanlı başlatılıyor ve biri diğerinin başlamasını engelleyemiyor. Log hook'u ile koruma hook'u arasında bir sıra yok; birinin diğerinin sonucuna ihtiyacı varsa ikisini tek script'te birleştir. Claude Code'da da durum aynı, eşleşen hook'lar paralel çalışıyor (serinin yedinci yazısı). Codex'e özgü farklar başka yerde: prompt ve agent tipindeki handler'lar okunup atlanıyor, PreToolUse'da "ask" kararı henüz desteklenmiyor ve web search gibi hosted tool'lar hook'tan geçmiyor. Belgeler tool hook'larını tam bir güvenlik sınırı değil, kullanışlı bir koruma olarak tanımlıyor. .codex klasörü sandbox'ta korunan bir yol olduğu için Codex hook'unu kendi kendine değiştiremiyor.

IDE Extension'da Aynı Akış

Aynı iş Visual Studio Code (VS Code) içinden de yapılabiliyor. Extension açık dosyaları, seçili kodu ve son chat'leri composer'a ekleyebiliyor, değişikliklerin özetini ve diff'ini kodun yanında gösteriyor ve uzun bir işi cloud'a devretmeye izin veriyor. Configuration, AGENTS.md zinciri, skill'ler, MCP (Model Context Protocol; agent'ların dış tool'lara bağlandığı açık protokol) server'ları ve hook'lar CLI ile aynı; ikisi aynı giriş kaydını da paylaşıyor. Windows'ta agent'ın WSL 2 içinde çalışmasını istiyorsan VS Code ayarlarında chatgpt.runCodexInWindowsSubsystemForLinux değerini true yapıyorsun. IDE'deki AI asistanlarının genel karşılaştırması IDE'ler serisinin dokuzuncu yazısında.

Üretimde Dikkat

Paralel işin maliyeti var. Her worktree ayrı bir checkout, ayrı paketler ve build çıktısı; her subagent ayrı model çağrıları demek. Okuma ağırlıklı işleri paralel çalıştır, düzenlemeleri tek bir chat'te topla ve birleştirmeden önce her subagent sonucunu kendin oku.

Hook'ları kod gibi review et. Commit'lenmiş bir hook ekipteki herkesin makinesinde onun yetkisiyle komut çalıştırıyor. Hash tabanlı trust, değişen hook'u yeniden onaya düşürüyor; --dangerously-bypass-hook-trust yalnız hook kaynaklarını zaten başka bir yerde denetleyen otomasyonlar için.

Sık Düşülen Tuzaklar

Worktree'ler arasında aynı veritabanı ve port. User-secrets profilde olduğu için her worktree aynı connection string'i okuyor. Test veritabanını ve dev server portunu worktree başına ayır.

Subagent sonuçlarını okumadan birleştirmek. Ana chat'in özeti, her subagent'ın ne yaptığının kısa hâli; şüphelendiğin yerde thread'i aç.

Hook'ların sıralı çalıştığını varsaymak. Eşleşen hook'lar eşzamanlı başlıyor; aralarındaki bağımlılığı tek script'te çöz.

Daha yüksek effort'u her zaman daha iyi sanmak. Max ve Ultra daha uzun sürüyor ve daha çok harcıyor; belgelere göre işlerin çoğu bunlara ihtiyaç duymuyor.

Küçük Bir Deneme

★☆☆ Aynı küçük işi /model --reasoning=low ve --reasoning=high ile iki ayrı chat'te iste. Süreyi, /status'taki kullanım değişimini ve sonuçtaki farkı not et.

★★☆ Desktop app'te bir worktree için setup script'i yaz, sonra iki paralel chat başlat ve her birinin testlerini ayrı bir veritabanı adıyla çalıştır. Çakışma kalktı mı?

★★★ Bookstore'daki hook'u kendi repo'na uyarla, /hooks ile trust et ve Codex'ten commit'lenmiş bir migration'ı düzenlemesini iste. Sonra script'te tek bir satırı değiştir ve hook'un yeniden onaya düştüğünü gör.

Bütün bunlar senin bilgisayarında oluyor; laptop'ın kapandığında iş de duruyor. Beşinci yazıda aynı işleri Codex Cloud'a taşıyacağız: reusable cloud environment'lar, .NET ve Angular kurulumu, aynı iş için paralel task'lar ve sonucu pull request'e çevirmek.