Code Assistant

Rust'ta inşa edilmiş, otonom kod analizi ve modifikasyonu için komut satırı ve grafik arayüzler sağlayan bir AI coding assistant.

Ana Özellikler

Multi-Modal Tool Execution: Farklı LLM yeteneklerine uyum sağlar ve yerel function calling, XML-tarzı etiketler ve triple-caret blokları içeren takılabilir tool invocation modları sayesinde çeşitli AI sağlayıcıları arasında uyumluluğu garanti eder.

Real-Time Streaming Interface: Gelişmiş streaming işlemcileri, LLM'den akan tool invocation'ları ayrıştırır ve görüntüler. Güvenli olmayan tool kombinasyonlarını engellemek için akıllı filtreleme sağlar.

Session-Based Project Management: Her chat session belirli bir projeye bağlıdır ve kalıcı state, working memory ve ek destek ile draft mesajları korur.

Multiple Interface Options: Zed'in GPUI framework'ü üzerine inşa edilmiş modern GUI, geleneksel terminal arayüzü veya Claude Desktop gibi MCP istemcileriyle entegrasyonun headless MCP server modu arasından seçim yapın.

Agent Client Protocol (ACP) Support: Agent Client Protocol standardıyla tam uyumlu, Zed gibi ACP-uyumlu editörlerle sorunsuz entegrasyonı sağlar. Kurulum talimatları için Zed'in özel agent ekleme belgelerine bakın.

Session Compaction: Context alanı bitmeden önce, agent bir session özeti oluşturur ve çalışmaya devam eder.

Auto-Loaded Repository Guidance: Proje kökünden AGENTS.md (veya CLAUDE.md yedekleme) dosyasını otomatik olarak assistant'ın sistem bağlamına dahil eder ve davranışı repo'ya özel talimatlarla hizalar.

Kurulum

# macOS veya Linux üzerinde, rustup aracılığıyla Rust tool chain'i kurun:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Linux üzerinde, libxkbcommon‑dev ve libxkbcommon‑x11‑dev paketlerini kurun

# macOS üzerinde, metal tool chain'e ihtiyacınız vardır:
xcodebuild -downloadComponent MetalToolchain

# Ardından repo'yu clone edin ve derleyin:
git clone https://github.com/stippi/code-assistant
cd code-assistant
cargo build --release

Binary target/release/code-assistant adresinde kullanılabilir olacaktır.

İlk Kurulum

Derlemeden sonra konfigürasyon dosyalarınızı oluşturun:

# Config dizini oluştur
mkdir -p ~/.config/code-assistant

# Örnek konfigürasyonları kopyala
cp providers.example.json ~/.config/code-assistant/providers.json
cp models.example.json ~/.config/code-assistant/models.json

# API key'lerinizi eklemek için dosyaları düzenleyin
# Environment variable'ları ayarlayın veya JSON dosyalarını doğrudan güncelleyin
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

Ayrıntılı kurulum talimatları için Configuration bölümüne bakın.

Proje Konfigürasyonu

Mevcut projeleri tanımlamak için ~/.config/code-assistant/projects.json oluşturun:

{
  "code-assistant": {
    "path": "/Users/<username>/workspace/code-assistant",
    "format_on_save": {
      "**/*.rs": "cargo fmt" // Projede tüm dosyaları biçimlendirir, bu nedenle dosyaların zaten biçimlendirilmiş olduğundan emin olun
    }
  },
  "my-project": {
    "path": "/Users/<username>/workspace/my-project",
    "format_on_save": {
      "**/*.ts": "prettier --write {path}" // Formatlayıcı bir path kabul ederse "{path}" sağlayın
    }
  }
}

Format-on-Save Özelliği

İsteğe bağlı format_on_save alanı, modifikasyonlardan sonra dosyaların otomatik biçimlendirilmesine izin verir. Dosya desenlerini (glob sözdizimi kullanarak) shell komutlarıyla eşleştirir:

• Glob desenlerine uyan dosyalar, assistant tarafından değiştirildikten sonra otomatik olarak biçimlendirilir
• Tool parametreleri, biçimlendirilmiş içeriği yansıtmak üzere güncellenir ve LLM'nin mental modelini senkronize tutar
• Bu, auto-formatting nedeniyle oluşan edit çakışmalarını önler

Ayrıntılı dokumentasyon için docs/format-on-save-feature.md dosyasına bakın.

Önemli Notlar:

• Bu konfigürasyonda olmayan bir klasörden başlatırken, geçici bir proje otomatik olarak oluşturulur
• Assistant'ın mevcut projeye (geçici olanlar da dahil) ve yapılandırılmış tüm projelere erişimi vardır
• Her chat session kalıcı olarak ilk projesine ve klasörüne bağlıdır - bu daha sonra değiştirilemez
• Tool sözdizimi (native/xml/caret) da session oluşturma sırasında sabitlenir

Kullanım

GUI Modu (Önerilir)

# Grafik arayüzü ile başlat
code-assistant --ui

# Başlangıç görevi ile GUI'yi başlat
code-assistant --ui --task "Kimlik doğrulama sistemini analiz et"

Terminal Modu

# Temel kullanım
code-assistant --task "Bu kod tabanının amacını açıkla"

# Belirli model ile
code-assistant --task "Hata işleme ekle" --model "GPT-5"

Çalışma Dizini Önemli

code-assistant'ı başlattığınız dizin, session'ınızın proje bağlamını belirler. Assistant, çalışma dizininizi (PWD) hangi kod tabanı üzerinde çalıştığınızı anlamak için kullanır - dosya işlemleri, aramaları ve tool yürütmesini bu dizine kapsamlandırır.

En iyi pratik: code-assistant'ı başlatmadan önce her zaman projenizin kök dizinine cd yapın.

cd ~/workspace/my-project
code-assistant --ui

Sohbetler dizin tarafından gruplandırılır, bu nedenle doğru proje dizininden yeni bir sohbet başlatmak şunları sağlar:

• Assistant'ın doğru dosya bağlamı vardır ve kod tabanınızda gezinebilir
• Konuşma geçmişiniz proje başına organize kalır
• O projeden AGENTS.md veya CLAUDE.md rehber dosyaları otomatik olarak yüklenir

Farklı bir proje üzerinde çalışmanız gerekirse, mevcut bir session'ı başka bir yerden yeniden kullanmak yerine o projenin dizininden yeni bir sohbet açın.

MCP Server Modu

code-assistant server

ACP Agent Modu

# ACP-uyumlu agent olarak çalıştır
code-assistant acp

# Belirli model ile
code-assistant acp --model "Claude Sonnet 4.5"

ACP modu, Agent Client Protocol destekleyen editörlerle entegrasyonu sağlar; örneğin Zed. ACP modunda çalışırken, code-assistant stdin/stdout üzerinden JSON-RPC aracılığıyla iletişim kurar ve bekleyen mesajlar, real-time streaming ve uygun izin işleme ile tool yürütmesi gibi özellikleri destekler.

Konfigürasyon

Model Konfigürasyonu

Code-assistant, LLM sağlayıcılarını ve modellerini yönetmek için iki JSON konfigürasyon dosyası kullanır:

~/.config/code-assistant/providers.json - Sağlayıcı kimlik bilgileri ve uç noktalarını yapılandırın:

{
  "anthropic": {
    "label": "Anthropic Claude",
    "provider": "anthropic",
    "config": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "base_url": "https://api.anthropic.com/v1"
    }
  },
  "openai": {
    "label": "OpenAI",
    "provider": "openai-responses",
    "config": {
      "api_key": "${OPENAI_API_KEY}"
    }
  }
}

~/.config/code-assistant/models.json - Mevcut modelleri tanımlayın:

{
  "Claude Sonnet 4.5 (Thinking)": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 8192
      }
    }
  },
  "Claude Sonnet 4.5": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768
    }
  },
  "GPT-5": {
    "provider": "openai",
    "id": "gpt-5-codex",
    "config": {
      "temperature": 0.7
    }
  }
}

Environment Variable Substitution: API key'lerine başvurmak için sağlayıcı konfigürasyonlarında ${VAR_NAME} kullanın.

Tam Örnekler: Tüm desteklenen sağlayıcılarla (Anthropic, OpenAI, Ollama, SAP AI Core, Vertex AI, Groq, Cerebras, MistralAI, OpenRouter) tam konfigürasyon örnekleri için providers.example.json ve models.example.json dosyalarına bakın.

Tool Konfigürasyonu

Bazı tools, işlevsellik görmek için harici API key'lerine ihtiyaç duyar. Bunları ~/.config/code-assistant/tools.json dosyasında yapılandırın:

{
  "perplexity_api_key": "${PERPLEXITY_API_KEY}"
}

Kullanılabilir Tool Ayarları:

• perplexity_api_key - AI destekli web araması için perplexity_ask toolunu etkinleştirir

Gerekli konfigürasyonu olmayan tools, assistant tarafından kullanılabilir olmayacaktır.

Mevcut Modelleri Listele:

# Yapılandırılmış tüm modelleri gör
code-assistant --list-models

# Yapılandırılmış tüm sağlayıcıları gör
code-assistant --list-providers

{
  "mcpServers": {
    "code-assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["server"],
      "env": {
        "SHELL": "/bin/zsh"                 // Giriş shell'iniz
      }
    }
  }
}

{
  "agent_servers": {
    "Code-Assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["acp", "--model", "Claude Sonnet 4.5"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

# Session'ı kaydet (yalnızca Anthropic)
code-assistant --record session.json --model "Claude Sonnet 4.5" --task "Veritabanı sorgularını optimize et"

# Session'ı oynat
code-assistant --playback session.json --fast-playback

Mimari Vurgular

Code-assistant birkaç yenilikçi mimari kararı içerir:

Adaptive Tool Syntax: Hedef LLM'nin yeteneklerine bağlı olarak farklı sistem istekleri ve streaming işlemcilerini otomatik olarak oluşturur. Aynı çekirdek mantığın farklı function calling desteğine sahip sağlayıcılar arasında çalışmasını sağlar.

Smart Tool Filtering: Dosyaları okumadan önce düzenlemeyi denemeyi engeller gibi mantıksal hataları önleyen gerçek zamanlı tool invocation analizi. Güvenli olmayan kombinasyonlar algılandığında yanıtları mid-stream'de kesebilir.

Multi-Threaded Streaming: Tool invocation'ların gerçek zamanlı ayrıştırılmasını işleyen, UI güncellemelerini duyarlı tutan ve birden fazla chat session'ında uygun state yönetimini sağlayan sofistike async mimarisi.

Katkı Sağlama

Katkılar hoşlanır! Kod tabanı, async Rust, AI agent mimarisi ve cross-platform UI geliştirmeyle ilgili gelişmiş modelleri gösterir.

Yol Haritası

Bu bölüm gerçekten bir yol haritası değildir, çünkü öğeler belirli bir düzende değildir. Aşağıda, muhtemelen sonraki odak olacak bazı konular vardır.

• Block Replacing in Changed Files: Bir tool use bloğunu stream ederken, LLM'nin replace_in_file kullanmaya çalıştığını ve oldukça erken hangi dosyada olduğunu zaten biliyoruz. Ayrıca bu dosyanın LLM'nin onu son okumasından beri değiştirildiğini bilirsek, uygun bir hata mesajı ile girişimi engelleyebiliriz.
• Compact Tool Use Failures: LLM geçersiz bir tool call ürettiğinde veya uyumsuz bir search block ürettiğinde, başarısız girişimi mesaj geçmişinden çıkararak token'lar tasarruf edebilmeliyiz.
• Improve UI: UI'ın geliştirilmesinin çeşitli yolları vardır.
• Add Memory Tools: Belirli bir projede çalışırken kullanışlı bir bilgi tabanı oluşturmayı kolaylaştıran tools ekleyin.
• Security: İdeal olarak, tüm tools'lar için yürütme, git tarafından izlenen projede dosyalara erişimi sınırlandıran bir tür sandbox'ta çalışacaktır. Şu anda, tools absolute path'leri reddeder, ancak relative path'lerin projenin dışına işaret edip etmediğini veya git-ignored dosyalara erişmeye çalışıp çalışmadığını kontrol etmez. execute_command tool'u, sağlanan komut satırı ile bir shell çalıştırır ve bu anda tamamen kontrol edilmemiştir.
• Fuzzy matching search blocks: Fuzzy matching search blocks'ların faydalarını araştırın. Şu anda, dosyalar normalize edilir (her zaman \n satır sonları, sondaki boşluk yok). Bu, search block'ları eşleştirme başarı oranını oldukça artırır, ancak belirli fuzzy matching yolları başarıyı daha da artırabilir. Başarısız eşleşmeler, neredeyse her zaman LLM'yi bir dosyayı yeniden okumasını tetikledikleri için oldukça fazla verimsizliğe neden olur. replace_in_file tool'unun hata çıktısı tam dosyayı içerip LLM'ye dosyayı yeniden okumaması söylese bile.