Pi kodlama ajanını geliştirirken öğrendiklerim

 (mariozechner.at)
15 puan yazan GN⁺ 2026-02-02 | 2 yorum | WhatsApp'ta paylaş
  • pi-coding-agent, karmaşık özellikleri en aza indirip kullanıcının bağlam kontrolü ve şeffaflık üzerinde tam hakimiyet kurabilmesi için tasarlanmış bir kodlama ajanı çerçevesidir
  • Temel bileşenler dört parçadan oluşur: pi-ai, pi-agent-core, pi-tui, pi-coding-agent; bunlar sırasıyla LLM API entegrasyonu, ajan döngüsü, terminal UI ve CLI entegrasyonunu üstlenir
  • Sistem promptu ve araç seti 1000 tokenın altında tutulur; yalnızca read/write/edit/bash olmak üzere dört araç sunularak aşırı sadeleştirme hedeflenir
  • Güvenlik kısıtları, alt ajanlar, plan modu ve MCP desteği tamamen dışarıda bırakılır; bunun yerine tam gözlemlenebilirlik ve kontrol önceliklendirilir
  • Benchmark sonuçları ve gerçek kullanım deneyimi, basit ve şeffaf tasarımın karmaşık ajanlarla yeterince rekabetçi olabildiğini gösterir

pi-ai ve pi-agent-core

  • pi-ai, Anthropic, OpenAI, Google, xAI, Groq gibi çeşitli LLM sağlayıcıları için birleşik API sunar
    • Streaming, araç çağırma, reasoning (trace) desteği, token ve maliyet takibi ile tarayıcı uyumluluğu içerir
    • Yalnızca dört ana API ile(OpenAI Completions/Responses, Anthropic Messages, Google Generative AI) çoğu modelle iletişim kurulabilir
  • Her sağlayıcıya özgü API farklarını ortak bir yapıda ele alır
    • Örn: max_tokens alan adı farkları, reasoning alanının yeri, developer rolü desteğinin olmaması
    • Token raporlama biçimleri çok farklı olduğundan kesin maliyet hesaplaması mümkün değildir; pi-ai bunu best-effort yaklaşımıyla izler
  • Context handoff özelliği sayesinde oturum ortasında model veya sağlayıcı değiştirilebilir
    • Örn: Anthropic → OpenAI → Google geçişinde reasoning içeriği `` etiketlerine dönüştürülerek korunur
  • Model registry ile tip güvenli model tanımları desteklenir
    • OpenRouter ve models.dev verileri parse edilerek model bazlı maliyet ve özellik bilgileri otomatik üretilir
  • İstek iptali (abort) ve kısmi sonuç döndürme tam olarak desteklenir
    • Streaming, AbortController ile durdurulduğunda ara sonuçlar olduğu gibi kullanılabilir
  • Araç sonucu ayrıştırma yapısı benimsenmiştir
    • LLM için metin ile UI’da gösterilecek veri ayrı döndürülür; argüman doğrulaması TypeBox/AJV ile yapılır
    • İleride araç sonucu streaming özelliği eklenmesi planlanır
  • Ajan döngüsü, mesaj işleme, araç çalıştırma ve sonuç geri bildirimi süreçlerini otomatik olarak tekrarlar
    • Olay tabanlı yapı sayesinde UI’nin tepkisel uygulanması kolaylaşır
    • Gereksiz kontrol parametreleri (maksimum adım sayısı vb.) kaldırılarak sadeleştirilmiştir

pi-tui

  • pi-tui, Node.js tabanlı bir terminal UI framework’üdür ve minimum flicker ile gerçek zamanlı güncellemeleri destekler
    • Differential rendering ile yalnızca değişen satırlar güncellenir
    • Senkronize çıktı dizileri (CSI ?2026h/l) kullanılarak flicker en aza indirilir
  • İki farklı TUI yaklaşımı arasından, scrollback buffer’ı koruyan CLI tarzı çıktı yöntemi tercih edilmiştir
    • Doğal kaydırma, arama gibi terminalin yerleşik özelliklerinden doğrudan yararlanılır
    • Claude Code, Codex ve Droid’e benzer bir yapıdadır
  • Retained mode UI kullanır
    • Her bileşen kendi render sonucunu cache’ler ve yalnızca değişiklik olduğunda yeniden çizer
    • Tüm ekranı yeniden render etmeden verimli güncelleme mümkündür
  • Performans ve bellek kullanımı çok düşüktür; birkaç yüz KB düzeyinde olduğundan büyük oturumlar da sorunsuz işlenir

pi-coding-agent

  • pi-coding-agent, CLI tabanlı bir kodlama ajanıdır ve şu özellikleri sunar
    • Windows/Linux/macOS desteği, oturum yönetimi (devam ettirme/dallanma), model değiştirme, proje bazlı AGENTS.md yükleme
    • OAuth kimlik doğrulama, temayı anlık değiştirme, HTML oturum dışa aktarma, headless mode (JSON/RPC) desteği
  • Sistem promptu, 1000 tokenın altında kalan kısa ve öz bir yapıya sahiptir
    • Yalnızca read/write/edit/bash olmak üzere dört araç belirtilir
    • Gereksiz açıklamalar ve karmaşık kurallar kaldırılmıştır; kullanıcılar bunu AGENTS.md ile serbestçe genişletebilir
  • Araç seti en az düzeyde, 4 araçtan oluşur
    • Sadece read, write, edit, bash kullanılır ve bu çoğu kodlama işi için yeterlidir
    • Ek araçlar isteğe bağlı olarak etkinleştirilebilir (örn: grep, find, ls)
  • YOLO modu varsayılan olarak uygulanır
    • Tüm dosya sistemine erişim ve komut çalıştırma konusunda kısıtlama yoktur
    • Güvenlik promptları ve ön doğrulama adımları kaldırılmıştır; bunun yerine container ortamı kullanılması önerilir
  • Yerleşik To-do, Plan modu, MCP, Background bash, Sub-agent özelliklerinin tamamı çıkarılmıştır
    • To-do/Plan, basitçe dosya tabanlı yönetimle (TODO.md, PLAN.md) değiştirilmiştir
    • MCP, token israfı ve karmaşıklık nedeniyle hariç tutulmuş; yerine CLI+README yaklaşımı tercih edilmiştir
    • Background bash için tmux kullanılması önerilir
    • Sub-agent, görünürlük eksikliği nedeniyle devre dışı bırakılmıştır; gerekirse bash üzerinden kendisini çağırabilir
  • Gözlemlenebilirlik (Observability) özellikle vurgulanır
    • Tüm komutlar, dosya erişimleri ve çıktılar şeffaf biçimde gösterilir
    • Claude Code gibi diğer ajanların “black box” yapısıyla karşıtlık oluşturur

Benchmark’lar

  • Terminal-Bench 2.0 üzerinde Claude Opus 4.5 modeliyle test edilmiştir
    • Codex, Cursor, Windsurf gibi araçlarla kıyaslandığında rekabetçi performans göstermiştir
    • Sonuç dosyası (results.json) herkese açık depoya gönderilmiştir
  • Terminus 2 gibi basit ajanlar da benzer performans göstererek minimal yaklaşımın geçerliliğini ortaya koymuştur

Sonuç

  • pi, karmaşık özelliklerden çok bağlam kontrolü, sadelik ve şeffaflığı önceleyen bir kodlama ajanıdır
  • Hem gerçek kullanımda hem benchmark’larda büyük ajanlarla eşdeğer verimlilik göstermiştir
  • Gelecekte eklenmesi planlanan başlıca özellikler context compaction ve araç sonucu streaming ile sınırlıdır
  • Proje açık kaynak olarak yayımlanmıştır ve fork etme ile genişletme özgürlüğü sunar
  • Temel ders şudur: “Sadelik kontroldür, kontrol de üretkenliktir”

İlgili okumalar

2 yorum

 
GN⁺ 2026-02-02
Hacker News yorumları

  • Gerçekten harika ve düşünülmüş bir proje gibi görünüyor
    Ben de context engineering ve ağaç tabanlı konuşma yapısının önemine tamamen katılıyorum
    Mevcut doğrusal konuşma akışı fazla kısıtlayıcı olduğu için, araştırma ya da fikir geliştirme sırasında LLM ile işbirliği yaparken rahatsız ediciydi
    Ben de benzer bir felsefeyle kişisel bir araç yaptım; bağlamı iyi kurup yeniden kullanıyor ya da yan görevler çalıştırıp sadece iyi sonuçları getiriyordu
    Senin yaptığın sürüm çok daha değerli bir uygulama. Sayende Pi’yi öğrenmiş oldum

    • Ben de benzer bir şey denedim. MIND_MAP.md adlı bir Markdown dosyasını grafik şeklinde yönetip alıntıları satır içinde kaydediyorum
      Oturumlar arası belleği koruyor ve alt ajanlar oluştururken bağlam israfını azaltıyor
      Örnek kodum incelenebilir

  • OpenClaw ile Pi-agent arasındaki ilişki bana ollama/llama-cpp ilişkisini hatırlatıyor
    İlki daha çok ilgi görüyor ama aslında ikincisi daha etkileyici
    Claude Code şu anda abonelik avantajları sayesinde iyi durumda, ancak pazar oturup API birim fiyatlarına yaklaşınca token bazlı ücretlendirmeye sahip premium deneyim daha iyi bir seçenek olabilir
    Sonuçta özelleştirilebilir ajan framework'lerinin kapalı uygulamalara üstün geleceğini düşünüyorum

    • Bence tam tersine API fiyatları daha da düşecek ve Claude Code’un abonelik avantajları büyüyecek
      Çıkarım maliyet yapısı düşünüldüğünden daha verimli ve R&D fonu da yeterli
      Tüm araçlar giderek gelişiyor ve rakip ürünler de kusursuz değil
    • Pi de abonelik entegrasyonunu destekliyor. OpenAI, GPT aboneliğinin Pi içinde kullanılmasına izin verdi
      Kişisel olarak Peter’ın projesinin ilgi görmesine seviniyorum
      OpenClaw tarafında hâlâ çok fazla PR var ama Pi’de bu sayı onun 1/100’ü kadar, bu yüzden yönetmesi çok daha kolay
    • Bu durum neredeyse ChatGPT ile GPT-3 arasındaki ilişkinin aynısı
      OpenAI de zamanında “ChatGPT’nin neden bu kadar popüler olduğunu anlamıyoruz, GPT zaten API olarak vardı” demişti
    • Sonunda ollama gibi enshittification yaşayabileceğini de düşünüyorum
    • Adının “pi” olması biraz kafa karıştırıcı. Zaten tanınmış başka bir “Pi” varken neden bu adın seçildiğini merak ediyorum

  • Google’ın hâlâ tool call streaming desteklememesi şaşırtıcı
    Yerel bir tokenizer bile sunmuyor; bu yüzden AI Studio her seferinde token saymak için API çağrısı yapan verimsiz bir yapıya sahip

    • AI Studio’da, giriş yapılmıyorken bile token saymaya devam eden bir bug var
      CPU kullanımı %100’e kadar çıkıyor; sanki dizüstü bilgisayarım bir TPU kümesinden daha fazla güç harcıyor gibi
    • Aslında Anthropic de tokenizer sunmuyor

  • Diğer kodlama ajanlarının güvenlik önlemlerinin çoğu sadece security theater
    Codex komutları OS sandbox’ı içinde çalıştırdığı için (ör. macOS Seatbelt) tamamen işe yaramaz değil

    • Okuma dışındaki tüm tool call işlemlerinin manuel onay gerektirmesi gerektiğini düşünüyorum
      Uğraştırıcı olsa da hatalı komutları düzeltmekten iyidir
    • Benim Codex’im, sandbox dışındaki SDK’yı yamalaması istenince Python ile dosyaları değiştiriyor
    • Ajanı container dışında çalıştırmak riskli. Bu en temel şeylerden biri
    • Ben Codex’i bir GitHub reposuna bağlayıp otomatik PR oluşturacak şekilde ayarladım
      Veritabanına dokunmuyor, yalnızca UI ve middleware kodunu değiştiriyor
    • Codex’in de Claude Code gibi isteğe bağlı olarak sandbox’ı devre dışı bırakıp bırakmadığını merak ediyorum
    • YOLO modu yalnızca container içinde kullanılmalı. Sadece gerekli kaynaklara erişecek şekilde sınırlandırılmalı

  • Şimdiden bazı power user'ların Pi’ye geçtiğini gördüm, ben de bunu düşünüyorum
    Pi’nin avantajları bağlam üzerinde tam kontrol ve genişletilebilir araç yapısı
    Sistem prompt’u, todo genişletmeleri, MCP adaptörleri gibi çeşitli örnekler var
    Bağlam performans sınırlarını ya da context rot, contextual drift gibi sorunları anlıyorsanız Pi’nin değeri açıkça görülüyor
    İlgili bağlantı derlemesi

    • Pi, moltXYZ içinde en çok ilgi görmesi gereken kısım
      Armin kesinlikle zamanının ilerisinde
      Claude Code’un hook ve bağlam yönetimi hâlâ yüzeysel

  • Ben hâlâ Cursor kullanıyorum
    Claude Code’a geçmeyi denedim ama küçük kod tabanımda Cursor çok daha hızlı
    Yine de diff-review arayüzünün Git ile entegre olmaması rahatsız edici
    Yapay zekanın yaptığı değişikliklerle benim yaptıklarımı ayırt etmek zor ve Git entegreli inceleme daha önemli geliyor

    • Cursor’un gücü kısa geri bildirim döngüsü
      Claude Code’da ise sonuca güvenip işi teslim etmişsin gibi bir his var ve bu tedirgin ediyor
      Modelleri özgürce değiştirebilmek kilit nokta. Dile ya da iş türüne göre model performansı değişiyor
    • VS Code için Claude Code eklentisini kurarsanız, büyük kod tabanı keşfiyle CC entegrasyonunu aynı anda kullanabilirsiniz
    • Claude Code’da varsayılan olarak proje indeksi yok, bu yüzden dosyaları tek tek dolaşıyor
      Ben başlangıçta dosya listesini bağlama ekleyen bir hook yazarak hızı artırdım
      Aynı anda birden çok dosyayı düzenleyen özel bir araç da yaptım ve yaklaşık 3 kat hızlandı, ama bazı istisna durumları yüzünden devre dışı bıraktım
    • Ben de bootstrap ile ilerleyen solo bir geliştiriciyim ve Claude’u küçük görev otomasyonu için kullanıyorum
      Örneğin frontend test otomasyonu ya da landing page düzenlemeleri gibi
      Ana özellikleri ise ayrı bir Claude oturumunda sıkı bir geri bildirim döngüsüyle yönetiyorum
    • Cursor da gelişiyor. Yakında AI yazımı satır izleme (blame) özelliği eklenecek; böylece hangi modelin hangi prompt ile ne yazdığını görmek mümkün olacak

  • Minimal ajan mimarisi üzerine olan yazı etkileyiciydi
    “Gerekli değilse yapma” felsefesini sevdim
    Ben OpenClaw kullanarak müşteri desteği, dağıtım izleme, kod inceleme gibi çeşitli workflow’ları paralel yönetiyorum
    Asıl mesele context engineering
    OpenClaw’un workspace-first modeli, AGENTS.md, TOOLS.md ve memory/ dizini üzerinden oturumlar arasında öğrenmeyi sürdürüyor
    Ajanın kendi kendine öğrenme sürecini loglar üzerinden gözlemleyebiliyorsunuz
    Güvenlik tiyatrosu yerine gerçekçi tehdit modelini kabul eden yaklaşımı beğeniyorum
    Birden fazla uzman ajanın paralel çalışmasının genel amaçlı tek bir ajandan daha iyi olduğu fikrine de katılıyorum
    Pi ile OpenClaw’u Terminal-Bench üzerinde karşılaştırmak ilginç olabilir

  • Armin Ronacher’in neden Pi kullandığına dair yazı güzeldi
    Armin’in gönderisini görünce Pi’nin OpenClaw’un ajan harness’i olduğunu ilk kez öğrendim

  • Pi’nin JavaScript tabanlı yapısı, tarayıcı sandbox mimarisiyle iyi örtüşüyor
    Bunun AI ajanlarının gelecekteki yönüne uygun olduğunu düşünüyorum
    Yine de yazarın vendor extensions konusunda biraz daha esnek olmasını isterdim
    İlgili tartışma

    • “Kesişimi standartlaştır, birleşimi açığa çıkar” ifadesi etkileyiciydi

  • Ben hâlâ YOLO modu kullanmıyorum
    Araçların tam oturması için muhtemelen 6 ay daha gerekecek
    Ajanların keyfi komutlar çalıştırmasına neredeyse hiç gerek yok
    lint, arama, düzenleme ve web erişimi gibi yetkiler izin sistemine entegre edilse yeterli
    Deno ya da Workerd gibi sandbox ve izin kontrolü sunan runtime’lar ilk savunma hattı olabilir
    Bu yüzden Anthropic’in Bun seçimini anlamakta zorlanıyorum — güvenlik mimarisi neredeyse yok