Claude Code ile uzun oturumlar yürütürken 5 saatlik ve 7 günlük limitleri sürekli terminalden takip etmek verimsizleşiyor. ClaudeMeter, bu görünürlüğü macOS menü çubuğuna taşıyan; kullanım oranlarını, sıfırlanma sürelerini ve bildirim eşiklerini tek bakışta veren yerel bir yardımcı uygulama.
Problem
Claude Code CLI günlük akış için güçlü olsa da kullanım limitlerini sürekli göz önünde tutmak için ideal bir arayüz sunmuyor. Özellikle birden fazla görev arasında geçiş yaparken veya yoğun token tüketen oturumlarda, limitlere ne kadar yaklaşıldığını görmek için tekrar tekrar terminale dönmek gerekiyor.
Bu projede çözmek istediğim nokta, kullanım verisini bağlam bozmadan görünür kılmak ve bunu masaüstü deneyiminin doğal bir parçası hâline getirmekti.
Bu projede odaklandığım noktalar
- Menü çubuğunda her zaman erişilebilir bir kullanım özeti sunmak
- 5 saatlik, 7 günlük ve model bazlı haftalık limitleri anlaşılır göstermek
- Yaklaşan eşiklerde sistem bildirimi ile uyarı vermek
- Çevrimdışı durumlarda son bilinen veriyi kaybetmemek
- Ana kullanım API’si yanıt vermediğinde ikinci bir veri yoluna geçebilmek
- Yerel macOS deneyimini gereksiz karmaşıklık eklemeden korumak
Bağlantılar
- GitHub deposu: github.com/puq-ai/claude-meter
- Son sürüm: v1.3.0
- Platform: macOS 13.0+ (Ventura)
- Derleme aracı: Xcode 15+
Öne çıkan özellikler
Otomatik kullanım güncellemesi
Uygulama, Claude Code kullanım durumunu menü çubuğunda sürekli görünür tutuyor. Simge, kompakt ve detaylı görünüm modları sayesinde hem minimal hem de bilgi yoğun kullanım senaryolarına uyum sağlıyor.
- 5 saatlik kullanım limiti takibi
- 7 günlük kullanım limiti takibi
- API’nin
limitsdizisinde bildirdiği model bazlı haftalık limitler; her limit kendi adını taşıdığı için yeni bir model limiti uygulama güncellemesi beklemeden görünüyor - Ek kullanım (extra usage) takibi
- Sıfırlanma sürelerini doğrudan arayüzde gösterme
Bildirim ve eşik yönetimi
Kullanıcı, belirli oranlara yaklaştığında sistem seviyesinde uyarı alabiliyor. Bu da özellikle yoğun çalışma bloklarında limit sürprizlerini azaltıyor.
%75,%90ve%95eşiklerinde bildirim- Tekrarlı bildirimleri azaltan yavaşlatma mantığı
- Kullanıcı tercihine göre açılıp kapatılabilen uyarılar
Veri yenileme ve önbellek katmanı
Veri yenileme aralığı sabit değil; etkinlik seviyesine göre daha akıllı bir yaklaşım kullanılıyor. Ağ erişimi kesilse bile son bilinen veriler önbellek üzerinden görüntülenebiliyor.
- Etkinliğe göre uyarlanan yenileme stratejisi
- Çevrimdışı durumda son bilinen kullanım verisini koruma
- Hafif kaynak tüketimiyle arka planda çalışma
claude.ai yedek veri yolu ve uygulama içi giriş
Ana kullanım API’si hata verdiğinde veya hız sınırına takıldığında uygulama claude.ai web API’sine geçiyor. Ana yol hız sınırındayken ve yedek yol çalışırken ana yol her yenilemede boşuna denenmiyor; yedek yol da başarısız olursa ana yol hemen yeniden açılıyor, böylece kullanıcı hiçbir zaman veri yolu olmadan kalmıyor.
- claude.ai bağlantısı, tarayıcı geliştirici araçlarından çerez kopyalamak yerine uygulama içindeki bir giriş penceresiyle kuruluyor
- Elde edilen oturum anahtarı kabul edilmeden önce organizasyon uç noktasında doğrulanıyor; organizasyon kimliği de buradan otomatik çözülüyor
- Oturum anahtarı uygulamanın kendi Keychain kaydında saklanıyor; önceki sürümlerden kalan düz metin kayıt açılışta taşınıp siliniyor
- Kimlik doğrulama yoksa menü çubuğu yeşil bir %0 yerine uyarı gösteriyor ve açılır pencere bağlanma yolu sunuyor
Teknik mimari
ClaudeMeter, SwiftUI tabanlı bir macOS menü çubuğu uygulaması olarak kurgulanmış. Arayüz ve servis katmanları belirgin şekilde ayrılmış; veri akışı servisler ve yönetici katmanları üzerinden ilerliyor.
Öne çıkan mimari parçalar:
- APIService: kullanım verisini çekme, tekrar deneme ve hata yönetimi
- KeychainService: Claude Code kimlik bilgilerini okuma ve claude.ai oturum anahtarını uygulamanın kendi Keychain kaydında saklama
- NotificationService: macOS bildirim akışı ve eşik mantığı
- PollingManager: uyarlanabilir veri yenileme davranışı
- CacheManager: çevrimdışı kullanım için son veriyi saklama
- DependencyContainer: servislerin daha düzenli bağlanması için dependency injection yaklaşımı
Bu yapı sayesinde uygulama sadece görsel bir araç olarak kalmıyor; güvenlik, önbellek, veri yenileme ve bildirim davranışlarını birbirinden ayrıştırılmış sorumluluklarla yönetiyor.
Kurulum ve kullanım akışı
Projeyi iki farklı yoldan kullanmak mümkün:
- GitHub sürüm paketini indirip uygulamayı doğrudan macOS üzerinde çalıştırmak
- Kaynaktan derleyip Xcode üzerinden geliştirme yapmak
Kaynak koddan derleme akışı:
git clone https://github.com/puq-ai/claude-meter.git
cd claude-meter
xcodebuild -scheme ClaudeMeter -configuration Release build
Uygulama Claude Code CLI oturumunu kullandığı için önce aşağıdaki kimlik doğrulama akışının tamamlanması gerekiyor:
claude login
Bu adımdan sonra ClaudeMeter mevcut oturumu otomatik tespit edip kullanım verisini menü çubuğu arayüzüne taşıyor. Yedek veri yolu için claude.ai hesabına uygulamanın içinden de giriş yapılabiliyor.
Mühendislik notları
ClaudeMeter küçük bir menü çubuğu aracı olsa da veri yenileme, çevrimdışı durum, Keychain erişimi ve bildirim sıklığı gibi birbirinden bağımsız sorumluluklar taşıyor. Bu nedenle arayüz ile servis katmanlarını ayırmak, uygulamanın davranışını görünür ve test edilebilir tutmak açısından önemliydi.
v1.3.0’daki yedek veri yolu çalışması da aynı dersi verdi: bir yedek yol, tam da ana yolun kullanılamadığı durumda erişilebilir olmalı. Süresi dolmuş kimlik bilgisinin ağ isteğinden önce hata verip yedeği hiç denememesi, yerel saatin token geçerliliğine karar vermesi ve ana yol hâlâ 429 dönerken başarılı bir yedek yanıtın hız sınırı beklemesini hiç başlatmaması bu yüzden ayrı ayrı düzeltildi ve testle korundu.