Hive: Hafif bir çok ajanlı orkestratör

2025, ajanların yılıydı. Claude Code, LLM'lerle çalışmayı çok becerikli ama deneyimsiz bir junior geliştiriciyle eşli programlama yapmaya benzer hâle getirdi. Aralık 2025'te bir noktada, Opus 4.5'in yayımlanmasıyla yeteneklerde belirgin bir sıçrama fark edilir hâle geldi. Claude tek başına saatlerce çalışabiliyordu.

Bir sonraki bariz adım, tmux ile çok sayıda Claude Code oturumu açıp bunları farklı görevler üzerinde çalıştırmak. Bu o kadar yaygınlaştı ki Anthropic bundan "multi-Clauding" diye söz etmeye başladı. Steve Yegge'in tabiriyle bu, ajanlarla kodlamanın 6/7. seviyesi.

tmux harika, ama zihinsel yük çok ağırlaşıyor. Sürekli fikir üretme, yönlendirme ve inceleme arasında gidip geliyorsunuz. Darboğazın siz olduğunuz ve daha fazla ajanı yönetememenizin bir "beceri sorunu" olduğu açık. Bunun daha iyi bir yolu olmalı.

Ben de hive'ı geliştirdim.

Nedir

Hive, git worktree'lerini yalıtılmış yürütme ortamları olarak kullanarak birden fazla LLM kodlama ajanını SQLite kuyruğu üzerinden koordine eden, tek süreçte çalışan asenkron bir Python orkestratörüdür.

Sistemin üç temel bileşeni var. Kraliçe, proje yöneticiniz olarak görev yapan bir Claude oturumudur: işi anlatırsınız, o da kod tabanını inceler, işi bağımlılıkları olan görevlere ayırmayı önerir ve onayınızı bekler. İşçiler, her biri kendi git worktree'sinde kuyruktan görev alıp bunları yerine getiren paralel Claude (veya Codex) oturumlarıdır. Birleştirme Hattı, tamamlanan çalışmaları rebase eden, test eden ve main dalına birleştiren başka bir ajandır.

Temel tasarım ilkesi: Python'da deterministik orkestrasyon, belirsizlik içeren kararları LLM oturumlarına devretme. Durum makinesi geçişleri, görev üstlenme, üst kademeye aktarma? Python. Çakışma çözümü, test sorunlarını teşhis etme, işi stratejik olarak parçalara ayırma? Claude.

İşte bütün resim:

You
  ├─ CLI / Queen (TUI)
  └─ Daemon (background)
       ↓
SQLite Database (~/.hive/hive.db)
  ├─ Issues (work queue)
  ├─ Dependencies (DAG)
  ├─ Agents (ephemeral identity)
  ├─ Events (audit trail)
  ├─ Notes (inter-agent knowledge)
  └─ Merge Queue
       ↓
Orchestrator (async event loop)
  ├─ Main Loop (spawn workers when slots open)
  ├─ Event Consumer (status updates from backends)
  └─ Merge Processor (per-project)
       ↓
Backend Pool
  ├─ Claude WS Backend (claude CLI via WebSocket)
  ├─ Codex App Server Backend (stdio protocol)
  └─ Tau Backend (testing)
       ↓
Workers (each in its own git worktree)

Durum makinesi

Her görev, 7 durumdan oluşan bir yaşam döngüsünden geçer. Hive hakkında anlaşılması gereken en önemli nokta budur, çünkü tasarımdaki her karar bu durum makinesinin doğru çalışmasını sağlama gereğinden doğar.

OPEN ──(claim)──→ IN_PROGRESS ──(success)──→ DONE ──(merge)──→ FINALIZED
  ↑                    │
  └──(retry/switch)────┘
                       │
                  (exhausted)──→ ESCALATED
                       │
                  (manual)─────→ CANCELED

Üst kademeye aktarma politikası üç basamaklı bir zincirden oluşur.

1. Aynı ajanla yeniden dene; en fazla 2 deneme. Belki de model yalnızca o sefer kötü performans göstermiştir.
2. Ajan değiştir; temiz bir worktree'de yeni bir ajanla başla, en fazla 2 kez.
3. Bir insana aktar.

Bir anomali algılayıcısı da var: 10 dakikalık bir zaman aralığında 3 veya daha fazla başarısızlık, yeniden deneme haklarını atlayarak sorunun derhâl üst kademeye aktarılmasını tetikler. Bu, sistematik sorunları (bozuk test paketi, eksik bağımlılık, sağlayıcı sorunları) tokenları tüketmeden yakalar.

Görev üstlenme

Hazır görev kuyruğu, bağımlılık DAG'ını çözümleyen bir SQL sorgusudur:

SELECT * FROM issues
WHERE status = 'open'
  AND assignee IS NULL
  AND type != 'epic'
  AND NOT EXISTS (
    SELECT 1 FROM dependencies d
    JOIN issues blocker ON d.depends_on = blocker.id
    WHERE d.issue_id = issues.id
      AND blocker.status NOT IN ('done', 'finalized', 'canceled')
  )
ORDER BY priority ASC, created_at ASC

Bir görev ancak kendisini engelleyen tüm görevler çözüldüğünde "hazır" hâle gelir.

Görev üstlenme, CAS tarzı atomik bir güncellemedir: görevin hâlâ açık ve atanmamış olduğunu doğrula, bağımlılıkların hâlâ karşılandığını doğrula, ardından tek bir veritabanı işlemi içinde güncelle. İki işçi aynı görev için yarışırsa biri kazanır, diğerine ise False döner.

Arka uç soyutlaması

En çok memnun olduğum kısım bu. HiveBackend arayüzü, oturum yönetimini (create_session, abort_session, get_session_status), iletişimi (send_message_async, get_messages, reply_permission) ve olay akışını (on(event_type, handler), connect_with_reconnect()) kapsayan yaklaşık 15 metottan oluşuyor. Orkestratör hangi arka ucun çalıştığıyla ilgilenmez; yalnızca arayüzü çağırır.

Bu neden önemli? En gelişmiş modeller, birkaç ayda bir birincilik kürsüsündeki yerlerini birbirlerine devrediyor. Farklı modellerin farklı CLI sarmalayıcılarıyla nasıl etkileşime girdiği de belirsiz (duyduğuma göre Claude Code içinde GPT 5.4 oldukça iyiymiş). Hem modelden hem de çalıştırma altyapısından bağımsız olmak, diğer her şey hızla gelişirken temel orkestrasyon kodunun değişmek zorunda kalmaması demek.

Birleştirme hattı

Bir işçi bir görevi tamamladığında, çalışma bir birleştirme hattına girer.

Birleştirme işlemlerini "Rafineri" adlı özel bir Claude oturumu yürütür. Rafineri, çakışmaya ilişkin bağlamı veya test çıktısını alır, sorunu çözer ve yapılandırılmış bir sonuç dosyası yazar. Çalışmayı birleştirebilir (çakışma çözülmüş, testler geçiyor), reddedebilir (yeniden üzerinde çalışılması için open durumuna geri gönderebilir) veya bir insana aktarabilir (fazla karmaşık ya da belirsiz).

Rafineri, her proje için uzun süre açık kalan ve birden fazla birleştirme işleminde yeniden kullanılan bir oturumdur. Çok fazla bağlam biriktirdiğinde (>100 bin token veya >20 mesaj), hive oturumu yeni bir oturumla değiştirir. Her projeye ayrı bir MergeProcessor verilir; böylece çok projeli orkestrasyon, projeler arası birleştirme çekişmesi yaratmaz.

Ajanlar arası bilgi aktarımı

İşçiler çalışma sırasında .hive-notes.jsonl yazar:

{"category": "discovery", "content": "postgres dependency in main.py requires PGHOST to be set"}
{"category": "gotcha", "content": "tests require PYTHONPATH=src/"}

Bir işçi işini tamamladığında, hive onun notlarını toplar ve veritabanında saklar. İlişkili bir görevde (aynı epic, aynı proje) yeni bir işçi başlatırken hive, kardeş görevlerin ilgili notlarını isteme ekler.

Bu, 1 numaralı ajan test paketinin belirli bir ortam değişkenine ihtiyaç duyduğunu keşfederse, 3 numaralı ajanın (ilişkili bir görev üzerinde çalışan) bunu işe başlamadan önce bileceği anlamına gelir. Hiçbir ajanın tüm bilgiyi bağlamında tutması gerekmeden, bilgi sürü genelinde birikir.

Kraliçe

Kraliçe, hive ile etkileşim kurduğunuz ana noktadır. Terminalinizde çalışan bir Claude oturumudur (TUI modu). Ona bir gereksinim tanımı verirsiniz; ardından kod tabanını inceler, birikmiş proje bilgisini edinmek için .hive/project-context.md içeriğini okur, işi bağımlılıkları olan görevlere ayırmayı önerir, onayınızı bekler ve sonra görevleri oluşturup arka plan sürecini başlatır.

Betiklerde kullanmak için arayüzsüz bir mod da var:

hive queen --headless -p "Bump all dependencies and update the lockfile"

Kraliçe sayesinde tek tek ajanları yönlendirmekten proje yönetmeye geçersiniz. Siz ne yapılması gerektiğini ve işin nasıl parçalara ayrılacağını düşünürsünüz.

Yapılandırma ve değişiklik yapma kolaylığı

Hive, 4 katmanlı bir yapılandırma zinciri kullanır: yerleşik varsayılanlar → genel TOML (~/.hive/config.toml) → proje TOML'u (.hive.toml) → ortam değişkenleri. İlgi çekici ayarlar:

Öğrendiklerim

Kod tabanı yaklaşık 6.500 satır Python kodundan oluşuyor. Yerel olarak çalışacak, asgari düzeyde kaynak kullanacak ve bir öğleden sonra tamamını okuyup üzerinde değişiklik yapmaya başlayabileceğiniz kadar basit olacak şekilde tasarlandı.

hive üzerinde çalışırken öğrendiğim birkaç şey:

Bu iş için doğru veritabanı SQLite. WAL modu, yazma işlemleri sırasında eşzamanlı okumaya olanak tanıyor; busy_timeout pragması da kilit çekişmesini sorunsuzca yönetiyor. Tüm koordinasyon katmanını yalnızca SQL sorgularıyla kurabiliyorsunuz. 3-20 eşzamanlı ajan için SQLite fazlasıyla yeterli ve işletim kolaylığı çok değerli.

Git worktree'lerinin değeri hâlâ yeterince bilinmiyor. Her ajan, deponun main dalından ayrılan kendi worktree'sini alıyor. Birbirlerinin dosyalarına müdahale edemiyorlar; iş bittiğinde de rebase edip birleştiriyorsunuz. İş başarısız olursa worktree'yi siliyorsunuz. Yalıtım kusursuz, temizlemek ise çok kolay.

Not sistemi konusunda hâlâ emin değilim. Ajanların kod tabanı hakkında keşfettiklerini kardeş ajanlarla paylaşmasının, ilişkili görevlerde başarısızlık oranlarını anlamlı ölçüde azaltması mantıklı görünüyor. Ama bunu doğru biçimde ölçen görevler ve kıyaslama testleri tasarlamak zor. Gelecekteki çalışmaların üzerinde kapsamlı biçimde durması gereken bir konu bu.

Kod github.com/nwyin/hive adresinde. MIT lisansıyla sunuluyor ve fork'lanıp üzerinde değişiklik yapılması için tasarlandı. tmux içinde 3 veya daha fazla ajan yönetiyorsanız ve daha düzenli bir çözüm arıyorsanız bir göz atın.