Kurulum ve kullanım kılavuzu

1Başlarken

Hexabit Studio, çok sayıda yazılım projesini AI ajanlarla yürüten geliştirici için bir macOS uygulamasıdır. Projeleriniz, görevleriniz, kararlarınız ve ajan hafızası kendi diskinizdeki dosyalarda durur; uygulama bunları okur ve gösterir.

Gereksinimler

• macOS 26 ve üzeri; Apple Silicon (arm64) Mac. Intel Mac desteği planlanmıyor.
• Kendi Claude Code ve/veya Codex hesabınız. Model kullanımı bu hesaplardan faturalanır; abonelik bedeline dahil değildir. Claude Code ile tam çalışma vardır, Codex desteği erken aşamadadır.
• Hesap için bir e-posta adresi. İlk açılışta adrese tek kullanımlık kod gönderilir.

2Kurulum

İki yol var: tek komutluk betik (önerilen) ve dmg disk görüntüsü. İkisi de aynı uygulamayı /Applications klasörüne yerleştirir.

Yol 1 — install.sh (önerilen)

Terminal’de şu komutu çalıştırın:

curl -fsSL https://hexabitlabs.com/install.sh | sh

Önce okumak isterseniz betiği indirip inceleyin, sonra çalıştırın:

curl -fsSL -o install.sh https://hexabitlabs.com/install.sh
less install.sh
sh install.sh

Betik sırayla şunları yapar:

1. Mac’i denetler: macOS 26+ ve Apple Silicon.
2. Sürüm bilgisini, imzasını ve paketi indirir; paketin SHA-256 özetini karşılaştırır.
3. Paketle gelen küçük doğrulayıcıyla Ed25519 imzasını denetler. Biri tutmazsa hiçbir şey kurulmaz.
4. Uygulamayı /Applications klasörüne kopyalar, karantina işaretini temizler ve kod imzasını doğrular. Hata olursa eski sürüm yerinde kalır.
5. Uygulamayı açar; ilk açılış sihirbazı başlar (sonraki bölüm).

Betik seçenekleri:

• --add-path — hx komutunu terminalde kullanmak için ~/.zprofile dosyasına işaretli tek bir PATH satırı ekler.
• --no-launch — kurduktan sonra uygulamayı açmaz.
• --force — aynı sürüm kuruluysa da yeniden kurar. Betiği ikinci kez çalıştırmak güvenlidir.
• --uninstall — uygulamayı kaldırır. ~/.hexabitlabs altındaki verinize dokunmaz.

Bu yolda “Yine de Aç” adımı gerekmez; betik karantina işaretini kendisi temizler.

Yol 2 — dmg

Betik çalıştırmak istemiyorsanız:

1. dmg dosyasını açın ve HexabitLabs’i Applications klasörüne sürükleyin.
2. Uygulamayı bir kez açmayı deneyin. Bu sürüm Apple Developer ID ile imzalı olmadığı için macOS “açılamıyor” der.
3. Sistem Ayarları › Gizlilik ve Güvenlik bölümünü açın, aşağı kaydırın ve “HexabitLabs’i yine de aç” düğmesine basın.
4. Parolanızı girin. Uygulama açılır; bu adım yalnız ilk açılışta gerekir.

Kaldırma

install.sh ile kurduysanız sh install.sh --uninstall. dmg ile kurduysanız uygulamayı Applications klasöründen silin. Hub verisi (~/.hexabitlabs) her iki durumda da yerinde kalır; isterseniz kendiniz silersiniz.

3İlk açılış sihirbazı

Uygulama ilk açıldığında hesap ve kurulum adımlarını sırayla gösterir. Hesap doğrulanmadan uygulama içeriği açılmaz.

1. E-posta ile giriş

E-posta adresinizi yazın, aydınlatma metnini okuduğunuzu onaylayın ve Kod gönder’e basın. Adrese 6 haneli tek kullanımlık kod gelir; parola yoktur. Kodu bir sonraki ekrana girin. Adres hiçbir ekranda tam gösterilmez, maskelidir. Elinizde etkinleştirme kodu varsa Etkinleştirme kodum var bağlantısını kullanın.

2. Deneme veya abonelik

Doğrulamadan sonra plan seçersiniz: 14 gün deneme (bütün özellikler, kart bilgisi istenmez, hesap ve Mac başına bir kez), Studio Pro aylık (12 USD/ay) ya da yıllık (120 USD/yıl). Başka bir Mac’te aldığınız abonelik varsa Başka Mac’te aldığım abonelik var düğmesi aboneliği bu Mac’e getirir. Satın alma henüz açık değildir; ayrıntı için Abonelik ve lisans bölümüne bakın.

3. Kurulum biçimi

Hızlı kurulum (önerilen) önerilen ayarlarla tek ekranda biter; model indirilmez, birkaç dakika sürer. Uzman kurulum 9 adımda her ayarı tek tek sorar, isteğe bağlı adımlar atlanabilir. Her ayar sonradan Ayarlar’dan değişir.

Kur’a basmadan önce uygulama, yazacağı yerleri ve her biri için geri alma notunu gösterir; Kur düğmesi bu listenin onayıdır. Hızlı kurulumun yapacakları:

• Denetlenir, kurulmaz/yazılmaz: Node, Claude Code / Codex CLI / Gemini CLI (kurulu mu; ayar dosyası yazılmaz), Ollama (model indirilmez), ajan izin profili (önerilir, yazılmaz).
• Yazılır: ~/.hexabitlabs klasörü, gömülü kütüphane (kural ve yetenek paketi) ve hx araçları; genel kurallar (Compact talimatları, eşikler, token modu, disk uyarısı, hook’lar). Değişen her dosyanın yedeği yanında *.hx-bak olarak durur.
• Atlanır: iletişim ve bütçe (sonra Ayarlar’dan).

4. Kurulum tamamlandı

İşlem bitince adım adım özet görürsünüz. Bir adım başarısız olursa kurulum durur; eksik adım Ayarlar › Kurulum › Onar ile tamamlanır. Uygulamayı aç ile ana ekrana geçersiniz.

4İlk proje

Projeleriniz dosya tabanlıdır: her proje klasöründe AGENTS.md ve bir hexabit/ dizini (görevler, kararlar, ajanlar, bilgi modeli) bulunur. Hexabit Studio bu dosyaları okur ve görselleştirir; verinizi kendi sunucusuna taşımaz.

1. Ana Sayfa › Proje ekle ile mevcut bir proje klasörünü içe alın. Kurulum sihirbazı proje içe almaz; bu adım sonradan yapılır.
2. Kenar çubuğunda Proje — <ad> grubu belirir: Ana Sayfa, İşler, Ekip, İstekler, Depo, Bilgi, Kalite.
3. Ekip bölümünde projenin ajanlarını, Bilgi bölümünde bilgi modelini (ekranlar, varlıklar, fonksiyonlar) görürsünüz.

Ana Sayfa’da (Kapsam: Tüm Projeler) bütün projelerinizin özeti, dikkat bekleyen işler ve çalışan ajanlar tek ekranda durur. Üst ortadaki “ada”, çalışan Claude Code oturumlarını ve ajan sayısını gösterir.

5İlk ajan görevi

Bir işi ajana vermek için önce görev açarsınız. Görevler İşler ekranında Kanban panosunda akar: Bekleyen → Atandı → Çalışıyor → İncelemede ve sonrası.

1. İşler’de + Görev ile görev açın: başlığı ve ölçülebilir kabul kriterlerini yazın.
2. Görevi bir ajana atayın (Atanan süzgeciyle ajana göre listeleyebilirsiniz).
3. Görev ayrıntısında Oturum Başlat ile ajanı çalıştırın. Ajan, görevi, kuralları ve bağlamı okuyarak çalışır.
4. İlerlemeyi Kanban’da, ajanın canlı durumunu Etkinlik ekranında izleyin.

Kenar çubuğunun altındaki Otonom / Manuel çalışma kipi, ajanın ne kadar özerk çalışacağını belirler.

Ajan Ofisi

Etkinlik › Ofis ekranı ekibi bir ofis olarak gösterir: kim çalışıyor, kim bekliyor, kim onay istiyor ya da engelli. Kart | Karakter anahtarıyla iki görünüm arasında geçersiniz; Karakter görünümünde ajanlar masalarında çalışır, yeni ajan kapıdan girer. Dört ofis teması (Modern, Gece, Ahşap, Minimal) vardır, her ajanın avatarını (saç, ten, aksesuar, kıyafet) düzenleyebilirsiniz; avatar ajanın AGENT.md dosyasına yazılır. Hareketi azalt animasyonları durağan pozlara çevirir.

6Onay ve inceleme

Ajan işi bitirince görev İncelemede durumuna geçer. Kabul ve ret kararı sizindir; ajan kendi işini onaylamaz.

Test rozeti

Görev kartında ve ayrıntısında bir test rozeti görünür. Doğrula projenin kendi doğrulama komutunu (project.yaml ya da AGENTS.md’deki “Doğrulama komutu”) çalıştırır ve sonucu görev kaydına yazar: geçti/kaldı, süre, özet. Terminalde karşılığı hx task verify TASK-###.

Diff tabanlı inceleme

İnceleme ekranı görevin commit’lerini, değişen dosyaları ve satır satır farkı gösterir. Kabul kriterleri sekmesinde her kriter için kanıt görürsünüz. Kaynak Kodda Aç değişikliği kaynak gezgininde açar. Karar için Onayla… ya da Düzeltme İste… düğmeleri vardır; düzeltme isterseniz ajan gerekçenizle işe döner.

Değişmeden önce: Etki Analizi

Kalite › Etki Analizi, bir değişikliğin nereleri etkileyeceğini önceden gösterir: etkilenen ekranlar, kod dosyaları, testler ve risk. Değişiklik senaryosu ile “şu ekrana şu veriyi eklemek istiyorum” diye sorarsınız; araç hangi ekranların o alanı okuduğunu/yazdığını ve çalıştırmanız gereken testleri sade cümlelerle yazar.

Geri alınamaz işler

Silme, yayın, dağıtım ve güvenlik gibi geri alınamaz işlerde ajanlar önce sizden açık onay ister; onay beklerken görev Onay bekliyor olarak görünür.

7Sürümler ve güncelleme

Yüklü sürüm ve güncelleme ayarları Ayarlar › Güncellemeler’dedir.

• Kanal: Kararlı (varsayılan) ya da Beta. Beta yeni özellikleri kararlıdan önce getirir; sorun çıkabilir.
• Denetim: günde bir otomatik denetim ve Şimdi Denetle. Güncellemeler Ed25519 imzası ve dosya boyutuyla doğrulanır.
• Geri dönüş: ayarlarınız, Anahtar Zinciri ve ~/.hexabitlabs verisi güncellemeyle değişmez; yeni sürüm açılmazsa önceki sürüme dönülür. Yedekler ~/.hexabitlabs/.updates/backup altındadır.

8Abonelik ve lisans

Hexabit Studio Pro tek plandır: 12 USD/ay ya da 120 USD/yıl; tek kullanıcı, en çok 2 Mac; güncellemeler dahildir, uzaktan yönetim (tarayıcı paneli, mobil uygulama) hazır oldukça eklenir. Hesap e-posta ile açılır, parola yoktur. Fiyat, vergi, indirim ve iade koşulları için Fiyat sayfasına bakın.

Durumunuzu görmek

Araç çubuğundaki rozet planınızı (ya da kalan deneme süresini) gösterir. Rozete tıklayınca plan, ödenmiş dönem sonu ve Aboneliği yönet düğmesi açılır. Abonelik dönem sonunda otomatik yenilenir; iptal ederseniz dönem sonuna kadar açık kalır.

Aboneliği yönet ödeme sağlayıcısının hesap sayfasını açar; bağlantı, ödeme hesabı açılınca etkinleşir Yakında.

Süre bitince ne olur?

Deneme ya da abonelik bitince uygulama kilitlenir; projeleriniz ve dosyalarınız yerinde kalır. Kilit ekranından plan seçebilir, etkinleştirme kodu girebilir ya da Ödemeyi yeniden denetle ile yenilemenin ulaşıp ulaşmadığına bakabilirsiniz; abonelik yenilenince kilit kalkar.

Başka Mac’e taşımak

Aboneliğiniz hesaba bağlıdır. Yeni Mac’te e-postanızla girip Başka Mac’te aldığım abonelik var deyin; kod gerekmez. En çok 2 Mac’te kullanılır.

9Sık sorunlar