Orkestra UI

Claude-Orchestration

Claude ekosistemini kullanan kişisel bir ajan orkestrasyon sistemi. Hepsi Claude Code içinde çalışır: plugin, subagent, skill, hook, workflow, mod ve otomatik hafıza.

• Maliyet merdiveni: Her iş, izin verilen en ucuz basamakta başlar. Basamaklar: betik → Haiku 5.5 → Sonnet 5.5 → Opus 5.5 medium → Opus 5.5 xhigh. Fable kullanılmaz: denetçi hiçbir basamakta işçinin altında kalmasın diye en üst basamak da Opus 5.5'tir.
• Ana ajan planlar, dağıtır, toplar: Planlama Opus 5.5 medium'da yapılır. Ana ajan işçi işi yapmaz ve onay yazmaz.
• Ayrı denetçi: Her işçi çıktısını ayrı bir denetci ajanı kabul kriterlerine göre denetler. Kimse kendi işini onaylayamaz. Kural üç katmanda zorlanır: ajan araç kısıtı, hook kimlik enjeksiyonu ve CLI kontrolü.
• Paralellik: Görev kartları bağımlılık grafiği olarak yürür. Yazma alanı kesişmeyen işler aynı anda koşar. Bir hook alan dışına yazmayı reddeder.
• Ortak defter: Her ajan bitince ne yaptığı otomatik olarak deftere eklenir. İhtiyacı olan ajan yalnız ilgili kayıtları okur.
• Token defteri: Her ajanın her süreç için harcadığı token ve maliyet kaydedilir; kırılım ajan × süreç × model.
• Kesin değeri sayac modülü yazar: motorun her tur sonunda bildirdiği kullanımı kaydeder.
• Yedek kaynak, hook'ların transkript okumasıdır. Alt ajan transkriptleri çıkış tokenını eksik tuttuğu için bu yalnız tahmindir.
• Sohbet maliyeti: Çalışma alanındaki her sohbet, kenar çubuğundaki adıyla ve maliyetiyle panelde listelenir.
• Kapanmış sohbetlerde motorun kendi hesabı (cost-state) gösterilir.
• Açık sohbetlerde defter değeri gösterilir ve ≈ ile işaretlenir.
• Perspektif: Oturumlar arasında arka planda hafıza bakımı ve skill avı yapılır. Yalnız öneri üretir; hafızayı onayınla değiştirir.
• Arayüz (tek veri kaynağı): Hook'lar ve CLI her durum değişikliğinde .claude/orkestra/ozet.json anlık görüntüsünü yazar; arayüzler yalnız bu dosyayı okur.
• Claude içinde (/orkestra, Pane orkestra, plugins/orkestra-ui/hooks/register.tsx paneCiz): işlerin yapılanlarını ve yapılacaklarını gösterir. Üstte yapılan / toplam iş sayısı, yüzde ve çubuk. Yapılanlar: en az bir maddesi biten işler (biten/toplam ad). Yapılacaklar: açık maddesi olan işler (ad · N açık), her birinin ilk üç açık maddesi ○ ile. Kaynak ozet.json içindeki isler alanı; üretimi plugins/orkestra/scripts/ozet.py _is_todolari (açık işlerin todo.md maddeleri, en çok beş). Panel veri yaşını değil üretim saatini (HH:MM) yazar; veri 10 dakikadan eskiyse veri eski (HH:MM) sarıyla gösterilir (register.tsx 238–239 ve 260–261). Kart listesi, maliyet ve son olaylar bu panelde yok; onlar /orkestra-web sayfalarındadır.
• Prompt üstü bant (AbovePrompt, register.tsx): Yalnız kullanıcıdan eylem beklenen durumda çıkar: ret (reddedildi), teslime hazır kart (onaylandi) ya da hazır perspektif raporu. Metin Orkestra · N ret · N teslime hazır · perspektif raporu hazır; Panel düğmesi Claude içi paneli açar. Yalnız maliyet bant çıkarmaz. Gizle o anki kart kimliklerini ve rapor durumunu imza olarak saklar; imza değişince (yeni ret, teslim ya da rapor) bant geri gelir.
• HTML canlı panel (/orkestra-web, ya da Bash'te orkestra panel, ya da araclarpaneli_ac.cmd): http://127.0.0.1:8765/ adresinde sekiz sayfa açar: Şimdi, Maliyet, Verim, Onaylar, Kurallar, İşler, Etki, Yapılacaklar. Sayfalar üç saniyede bir yenilenir. Yalnız koyu temadadır ve yalnız bu bilgisayardan erişilebilir.
• Şimdi (/): ne oluyor, senden ne bekleniyor. Sohbetler (kimi bekliyor), görev kartları, son olaylar. "Kimi bekliyor"u hook'lar yazar (UserPromptSubmit → Claude çalışıyor, Stop → seni bekliyor, SessionEnd → kapandı). "Ne/neden"i ana ajan yeni bir iş başlarken orkestra niyet --ne "…" --neden "…" ile yazar, bitince --sonuc "…" ekler. Kayıt bütün projeler için tek dosyada: ~/.claude/orkestra-panel/niyet.jsonl.
• Maliyet (/maliyet): ne kadar harcanıyor, nereye. Kapsam seçici, iş türü × model, ajan tablosu, zaman içinde harcama, kota, tüm projeler.
• Verim ve sağlık (/verim): sistem iyi çalışıyor mu. Basamak verimliliği, birim maliyet, kart akışı ve paralel zaman çizelgesi, skill getirisi, sağlık (hafıza sınırı, son perspektif, etiketsiz ajan, hook hataları).
• Yapılacaklar (/yapilacaklar): açık işlerin maddeleri ve kullanıcının kendi yapılacakları (/api/todo, /api/kullanici-todo).
• /analitik ve /analitik.html adresleri /verim'e yönlendirilir (301, sorgu dizesi korunur).
• Çalışma alanı başlıktaki seçiciden seçilir. Orkestra kurulu alanda tam görünüm, kurulu olmayanda yalnız maliyet gösterilir.
• Şimdi sayfasındaki Sohbeti aç düğmesi sohbeti Claude uygulamasında açmayı dener.
• Kota kaydı: Claude kullanım sınırlarını yalnız durum satırı komutuna verir (Pro/Max). projeye_kur.py, proje ayarında statusLine yoksa scripts/kota.py'yi bağlar; betik değerleri ~/.claude/orkestra-panel/kota.jsonl'a yazar.

Yapı

.claude-plugin/marketplace.json     yerel klasör marketplace'i (claude-orchestration)
plugins/orkestra/                   çekirdek plugin
  agents/      triyaj, isci-t1..t4, denetci, arastirmaci, hafiza-bakimcisi, skill-avcisi, arsivci
  skills/      is, baslat, maliyet, defter, perspektif, skill-avi        →  /orkestra:<ad>
  workflows/   calistir.js   (DAG yürütme, işçi → ayrı denetçi, 2 ret → basamak yükseltme)
  hooks/       hooks.json → scripts/hook.py (9 olay); sayac.ts (turn.complete → kesin token kaydı)
  scripts/     ork_lib.py, orkestra.py (CLI), hook.py, perspektif.py, ozet.py (anlık görüntü), panel.py (HTML sunucusu: sekiz sayfa, /analitik → /verim; sunulan dosyalar STATIK),
               analitik.py (analitik hesapları), kota.py (durum satırı: kota kaydı), niyet.py (Şimdi sayfasındaki Sohbetler bölümü: ne/neden/kimi bekliyor)
  assets/      sayfa başına <sayfa>.html ile <sayfa>.js (büyük sayfalarda ayrıca <sayfa>.css); ortak.css ve ortak.js (window.O) ortak kabuk; logo.png
  bin/         orkestra, orkestra.cmd (CLI'yı PATH'e koyar), fiyat.json
  tests/       test_cekirdek.py (python -m unittest)
  evals/       claude plugin eval vakaları
plugins/orkestra-ui/                arayüz modu (Pane + AbovePrompt bandı + /orkestra)
araclar/sifre_temizle.py            oturum kayıtlarından düz metin şifre temizleme (elle çalıştırılır)
araclar/yayin_kur.py                yayın klonunu açar, git hook'larını yazar; araclar/git_hooklar/ hook şablonları

Yeni bir projeye kurmak (tek komut)

python <depo>/araclar/projeye_kur.py <proje klasörü>

Komut şunları yapar:

• Plugin'leri proje kapsamında kurar.
• Proje ayarlarına orkestra varsayılanlarını ekler; var olan değerin üstüne yazmaz.
• Durum klasörünü açar.
• Git deposuysa .gitignore dosyasına satır ekler.
• CLAUDE.md dosyasına kısa bir bölüm ekler.

Genel ayarlara dokunmaz ve tekrar çalıştırmak güvenlidir.

• Önizleme için --kuru, arayüz olmadan kurmak için --ui-yok, projeden çıkarmak için --kaldir kullan.
• Kurulumdan sonra o projede yeni bir Claude oturumu aç.

Başka bilgisayarda kurulum (GitHub private)

Depo GitHub'da özel (private) tutulur. İki yol vardır; ikisi de marketplace kaynağı olarak GitHub deposunu kullanır (kök .claude/settings.json içindeki extraKnownMarketplaces → source: github).

Gereksinimler

• Claude Code: kurulu ve oturum açılmış (claude komutu ya da masaüstü uygulaması).
• Python 3: hook'lar ve orkestra CLI'ı Python betikleridir. Alt sürüm için resmi bir bildirim yoktur; kod taramasında en yüksek gereksinim 3.8'dir (atama ifadesi :=, plugins/orkestra/scripts/ozet.py:160). Her sürümde koşturulmadı, bu yüzden 3.8 alt sınırı doğrulanmadı; güncel bir 3.x kullan. python komutu PATH'te olmalıdır.
• pytest: test kapısı (is-bitti) pytest ister; kurulu değilse python plugins/orkestra/scripts/kur.py açık bir uyarı basar (kurulum yapmaz). Kur: python -m pip install pytest.
• ORKESTRA_PYTHON: kapının kendi Python çağrıları için yorumlayıcı yolu (ortam değişkeni). Ayarlı değilse py -3.13 bulunursa o, yoksa çalışan Python (sys.executable) kullanılır. test_komutu içindeki çağrılara dokunulmaz.
• git ve özel depoya okuma erişimi: Claude Code marketplace'i makinedeki git ile, soru sormadan (etkileşimsiz) klonlar; Claude Code'un kendi git belirteci yoktur. Kimlik doğrulama (kaynak: Grant access to a private marketplace):
• SSH: anahtar parolasız çalışmalı (örn. ssh-agent) ve github.com known_hosts içinde olmalı. owner/repo biçiminde Claude Code önce ssh -T git@github.com dener, olmazsa HTTPS'e düşer.
• HTTPS: git kimlik yardımcısında (credential helper) kayıtlı bir kimlik bilgisi gerekir; yardımcı soru soramaz. GitHub'da gh auth login ve ardından gh auth setup-git bunu kaydeder.
• SSH anahtarı olmayan makinede CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 ayarlanır (oturum içi /plugin kurulumları ve güncellemeler HTTPS'e kendiliğinden düşmez).
• Yalnız GITHUB_TOKEN ortam değişkeni arka plan denetimini tek başına doğrulamaz; belirteç ancak gh gibi bir kimlik yardımcısı üzerinden işe yarar.

Yol A: depoyu klonla ve Claude Code'da aç

1. Depoyu klonla: git clone https://github.com/mertdurukan/agenchestra.git.
2. Klasörde Claude Code'u aç ve klasöre güven (workspace trust).
3. Kök .claude/settings.json (extraKnownMarketplaces + enabledPlugins: orkestra@claude-orchestration, orkestra-ui@claude-orchestration) devreye girer; plugin'ler marketplace'ten yüklenir.
4. Yeni oturumda /plugin ile plugin'lerin listelendiğini doğrula. Sistem yalnız açılmış projelerde iz tutar: bu klasörde izleme istiyorsan /orkestra:baslat çalıştır.

Yol B: kendi projene kur (tek komut)

python <depo>/araclar/projeye_kur.py <proje klasörü> --kaynak github

• --repo SAHIP/DEPO ile GitHub deposu verilir; verilmezse klonun origin adresinden türetilir, bulunamazsa komut hata verir.
• --kaynak yerel (varsayılan) yayın klonunu kullanır: --yayin <yol>, yoksa ORKESTRA_YAYIN, yoksa <depo>/../claude-orchestration-yayin. --kaynak github bu yola ihtiyaç duymaz.
• Önce --kuru ile ne yapılacağını görebilirsin. Seçenekler için python <depo>/araclar/projeye_kur.py --help.
• Sonra o projede yeni bir Claude oturumu aç. Özel depo için yukarıdaki git kimlik bilgisi bu makinede hazır olmalıdır.

GitHub deposu

Depo mertdurukan/agenchestra (özel), bu klasörün origin'i. Kök .claude/settings.json bu depoyu marketplace kaynağı olarak gösterir. Yol B'de --repo verilmezse origin'den türetilir. Geliştirme akışı: commitle → git push. Yayın klonu ve autoUpdate ile işleyen yerel akış değişmez.

Depoya girmeyenler

• Çalışma verisi .claude/orkestra/ (kartlar, defter, maliyet, özet; .gitignore'da). Her makinede orkestra baslat ile yeniden açılır.
• Kişisel ve makineye özgü ayarlar: ~/.claude/settings.json, ~/.claude/orkestra-panel/ (niyet, kota kayıtları) ve plugin önbelleği ~/.claude/plugins/. Depodaki tek ayar dosyası kök .claude/settings.json'dır.
• Bir projeye Yol B ile kurulum, o projenin kendi .claude/settings.json, .gitignore ve CLAUDE.md dosyalarını değiştirir; bunlar o projenin deposuna aittir.

Resmi dokümanla doğrulama (Claude Code dokümanı, 15.10.2026'da okundu)

Kurulum ayrıntısı (çalışma alanına özgü)

Ayarlar bilgisayara değil çalışma alanına bağlıdır. Plugin'ler proje kapsamında kurulur ve yalnız o projede etkindir. Genel ayar dosyası (~/.claude/settings.json) boş kalır.

cd <proje klasörü>
claude plugin marketplace add <yayın klonu klasörü>
claude plugin install orkestra@claude-orchestration --scope project
claude plugin install orkestra-ui@claude-orchestration --scope project

Komutlar <proje>\.claude\settings.json dosyasına enabledPlugins ve extraKnownMarketplaces alanlarını yazar.

Model, effort, hafıza ve perspektif ayarları da aynı dosyadadır. Proje ayarı, genel ayardan önce gelir.

Masaüstü uygulamasında claude PATH'te yoktur. Gömülü ikili %APPDATA%\Claude\claude-code\<sürüm>\…\claude.exe altında bulunur. Hook'ların içinde aynı yol CLAUDE_CODE_EXECPATH değişkeninde durur.

Claude Code plugin'leri bu klasörden değil, kurulumda alınan kopyadan okur: ~/.claude/plugins/cache/claude-orchestration/<plugin>/<sürüm>/. plugin.json ve marketplace.json içinde version alanı bilerek yoktur; git deposundaki göreli yol girdilerinde sürüm commit SHA'sı olur. Bu yüzden bir değişiklik commitlenmeden kopyaya geçmez (claude plugin validate --strict yalnız bu eksik sürüm uyarısı yüzünden hata verir; --strictsiz geçer). Marketplace bu klasörden değil yayın klonundan okur (aşağıda). Akış: geliştir → commitle (push gerekmez) → yayın klonu otomatik ilerler → autoUpdate ya da orkestra guncelle.

• Değişikliği bu klasörde commitle. Commitlenmemiş (başka oturumların yarım) işler plugin kopyasına girmez.
• Otomatik: projenin extraKnownMarketplaces.claude-orchestration.autoUpdate değeri true (projeye_kur.py yazar). Claude Code ilk mesajdan sonra en çok 10 dakika içinde günceller, yeni kopya sonraki oturumda yüklenir.
• Hemen için: proje klasöründe orkestra guncelle (--kuru yalnız komutları yazar). Marketplace'i ve projede kurulu her plugin'i günceller; ardından yeni oturum aç ya da /reload-plugins.
• Oturum açılışında çalışan kopya kaynaktan farklıysa bağlama tek satır uyarı düşer (kaç dosya farklı, kaynakta commitlenmemiş değişiklik var mı).

Yayın klonu (plugin_yayin)

claude plugin update commit'i değil marketplace klasörünün o anki çalışma ağacını kopyalar. Paralel oturumların commitlenmemiş işi çalışan plugin'e sızmasın diye marketplace bu klasörden değil, bu deponun temiz git klonundan (yayın klonu) okur. Varsayılan konum <depo>/../claude-orchestration-yayin, --yayin ya da ORKESTRA_YAYIN ile değişir (origin = bu klasör).

• Kurulum (tek komut, tekrar güvenli): python araclar\yayin_kur.py (--yayin <yol> ya da ORKESTRA_YAYIN ile yol değişir). Klonu açar ve .git/hooks/ altına post-commit, post-rewrite (amend/rebase) ve orkestra-yayin-esitle.sh yazar; hook şablonları araclar/git_hooklar/ altında izlenir.
• plugin_yayin elle düzenlenmez: hook klondaki yerel değişikliği checkout -f ile ezer; yalnız main'deki commit'ler yayına çıkar (başka dalda atılan commit klona dokunmaz).
• Her commit sonrası hook klonu çalışma dalıyla eşitler. Hata commit'i bozmaz (her zaman 0 çıkar, mesaj stderr'e).
• Yayın klonu elle düzenlenmez. orkestra guncelle önce klonu fetch + hızlı ileri sarar; klon kirliyse nedenini yazıp reddeder.
• projeye_kur.py marketplace kaynağını varsayılan olarak bu klondan alır.

HTML panel bu kuralın dışındadır: python <bu klasör>\plugins\orkestra\scripts\orkestra.py panel doğrudan bu klasörden çalışır.

Bir projede orkestrayı açmak için /orkestra:baslat kullan; sistem yalnız açılmış projelerde iz tutar.

Kullanım

Paralel çalışma

Paralel oturumlar ve işçiler aynı commitlenmemiş çalışma ağacını paylaşır. Bir işçi dosyayı baştan yazarsa başka bir oturumun arada yaptığı değişiklik sessizce silinebilir. İki deterministik kapı bunu önler:

• Çakışma kapısı: Kart isleniyora geçerken (orkestra kart durum <id> isleniyor) yazma alanı, aynı fiziksel ağaçta açık olan bütün kartların (hangi oturumdan olursa olsun) alanlarıyla karşılaştırılır.
• Kesişim muhafazakârdır: iki desenden birinin literal öneki diğerinin altındaysa ya da desenler fnmatch ile birbirine uyuyorsa kesişir.
• Kesişme varsa geçiş reddedilir: çakışma: G-0xx (<desen>) — bekle ya da ayrı çalışma ağacı aç.
• Bir git deposunun kökünü ya da ini kapsayan alan paylaşılan ağaçta reddedilir. Bu kural bir izin listesidir. Desenin sabit öneki, ilk joker bileşenden önceki yoldur; göreli desende proje köküne göre hesaplanır. Önek bir git deposunun kesin alt yolu olmalıdır: RNV/, src/**/*.py, docs/a.md.
• Önek deponun kökünün kendisiyse desen reddedilir: **, */, /*.py, *.md. fnmatch'te * / dahil her karaktere uyar; kökteki *.md de bütün alt klasörlere uzanır.
• Önek hiçbir deponun içinde değilse joker taşıyan ya da var olan bir klasörü gösteren desen reddedilir: Üst/**, Depo*/, Z:/Ortak/. Depo dışında yalnız tek dosya literal yolu geçer.
• İç içe depoyu fiziksel kesişim yakalar. Dış depodaki RNV/**, altındaki bir depoda ya da o deponun worktree'sinde açık olan kartla çakışır.
• kart yeni ve kart toplu aynı denetimi yalnız uyarı olarak yazar. Yazma alanı boş kart denetlenmez.
• Kart çalışma ağacı: orkestra kart agac <id> kartın deposunda <depo>/.claude/worktrees/kart-<id> klasörüne kart/<id> dalıyla bir git worktree açar (ORKESTRA_AGAC_KOKU doluysa <kök>/<depo-adı>/kart-<id>). Klasör .git/info/excludea bir kez eklenir; .gitignore değişmez. Kayıtlı calisma_agaci.yol korunur, eski <depo>-kart-<id> düzeni çalışmaya devam eder.
• İptalde temiz ağaç git worktree remove ile kaldırılır, birleşmiş dal branch -d ile silinir (force yok). Kirli ağaç ve kayıt kalır, uyarı yazılır. orkestra kart agac-temizle proje deposunu ve kartlardaki tüm depoları (calisma_agaci, _birlesik, _kaldirildi) tarayıp biten/kartsız ağaçları listeler (kuru koşu), --uygula kaldırır; açık kartın ağacına ve kalıp dışı ağaçlara dokunmaz.
• Kartın yazma alanı yeni köke çevrilir. calisma_agaci alanı (depo, yol, dal, taban) karta yazılır. Çalışma ağacı: <yol> satırı kartın girdisinin başına eklenir; işçi istemi bu satırı görür.
• Ayrık çalışma ağaçlarındaki kartlar birbiriyle çakışmaz. Biri ötekinin içinde kalan (iç içe) depo ayrık sayılmaz.
• Hook, işçinin yazımını kartın çalışma ağacında denetler; paylaşılan ağaca yazmasını reddeder.
• Birleştirme: orkestra kart birlestir <id> kart dalını git merge --no-ff ile birleştirir, sonra worktree'yi kaldırır ve dalı siler.
• Kart dalında commitlenmemiş değişiklik varsa reddeder.
• Ana ağaçta kartın dosyalarında commitlenmemiş değişiklik varsa reddeder; sessiz ezme yoktur.
• Çatışmada git merge --abort yapar, kartı beklemedeye alır ve çatışan dosyaları karta not eder. Çatışmayı asla otomatik çözmez.
• orkestra kart teslim, çalışma ağacı olan kartta önce birleştirir; birleşmezse teslimi reddeder.

Çatışma yüzünden beklemede kalan kart, çalışma ağacı ve dalı korunmuş hâlde bekler. Yeniden birleştirmek için çatışmayı kart dalında çöz:

1. Kartın çalışma ağacında ana dalı birleştir: git -C <kart ağacı> merge <ana dal>.
2. Çatışan dosyaları (birlestirme_catismasi alanı) elle düzelt ve commit et.
3. orkestra kart birlestir <id> komutunu yeniden çalıştır; bu kez çatışmasız birleşir ve worktree temizlenir.

Çözüm işin kendisini değiştirdiği için kart yeniden işçi ve denetçiden geçer: isleniyor → is-bitti → onay → orkestra kart teslim <id>.

Basamaklar ve denetim eşlemesi

Bir iş aynı basamakta iki kez reddedilirse (AYNI_BASAMAKTA_EN_COK_RET = 2) bir üst basamakta yeniden denenir; yetenek-yetersiz nedeninde ilk ret de yükseltir. Kartta toplam ret DENETCI_OPUS_RET_ESIGI (= 2) değerine ulaşınca denetimler opus'a geçer (T4'te xhigh).

Testler

python -m unittest discover -s plugins/orkestra/tests -v
claude plugin validate plugins/orkestra --strict
claude plugin test plugins/orkestra-ui
claude plugin eval plugins/orkestra --trust-plugin --runs 1

Bilinen sınırlar

• Kabuk yazımı: Yazma alanı kapısı Write ve Edit araçlarını engeller. Kabukla yapılan yazımı yalnız korunan orkestra dosyaları için engeller.
• Mod API'si: Mod API'si erken erişimdedir; Claude Code sürümleri arasında değişebilir. Arayüz bozulursa çekirdek çalışmaya devam eder.
• Maliyet tutarları: Tutarlar API liste fiyatıyla yapılmış tahminlerdir. Abonelikte gerçek fatura değil,