Numex Codex CLI

Terminalde çalışan, Türkçe odaklı agentic yapay zeka asistanı. Sohbet eder, dosyalarınızı okur/düzenler ve komut çalıştırabilir.

Marka renkleri ve logo sistemi: Numex AI Marka Kiti · Ana Teal #00C9A7 · Osmanlı Altını #C9A237

Kurulum

Tek satır (Windows PowerShell):

irm https://www.numexai.com.tr/install-cli.ps1 | iex

Tek satır (macOS/Linux):

curl -fsSL https://www.numexai.com.tr/install-cli.sh | sh

veya npm:

npm install -g @numexai/cli

Geliştirme (bu repo):

cd numex-cli && npm link

Gereksinim: Node.js 18+

Başlangıç

numex basla          # önerilen — giriş + menü (sohbet veya uzaktan)
numex uzak           # doğrudan web'den PC kontrolü
numex login          # sadece giriş
numex                # terminal sohbeti

numex login tarayıcıyı açar; Google hesabınızla giriş yaptıktan sonra terminal otomatik bağlanır. Gelişmiş kullanım için numex login --anahtar ile elle anahtar girebilirsiniz.

Komutlar

| Komut | Açıklama | |-------|----------| | numex | Interaktif sohbet oturumu | | numex "soru" | Tek seferlik soru | | numex --devam | Son oturumdan kaldığınız yerden devam et | | numex --yolo | Onaysız mod — riskli işlemler otomatik (tehlikeli komutlar hariç) | | numex --tam-erisim | Dosya araçları tüm dosya sistemine erişir | | numex --lint | Değişiklik sonrası otomatik lint/hata düzeltme döngüsü | | numex --plan | Plan modu — salt-okuma keşif + uygulama planı (kod yazmadan önce) | | numex -p "görev" | Headless mod — tek komut çalıştır, sonucu yazdır (script/CI). --json ile yapılandırılmış çıktı | | numex komut init | Örnek özel komut oluştur (.numex/commands/) | | numex --izleme-yok | Canlı dosya izlemeyi kapat | | numex oturumlar | Kayıtlı oturumları listele | | numex login | numexai.com.tr üzerinden tarayıcı girişi | | numex login --anahtar | API anahtarını elle gir (gelişmiş) | | numex remote start | PC'yi numexai.com.tr/developers/remote sohbetine bağla | | numex config | Yapılandırmayı göster | | numex config set <anahtar> <değer> | Ayar değiştir (apiKey, baseUrl, maxOutputTokens, yolo, fullAccess, allowedPaths, trustedCommands) | | numex bakiye | Token bakiyesi | | numex undo | Son dosya değişikliğini geri al (checkpoint) | | numex geri-al | Son turun tüm dosya değişikliklerini geri al |

Oturum içi slash komutları

/yardim /temizle /geri /geri-al /kaydet /proje <yol> /indeks /embed /hafiza /mod /plan /erisim /izin <yol> /gorsel <yol> /izle /lint /komutlar /dizin /bakiye /cikis

• /gorsel "C:\yol\resim.png" [soru] — görsel/ekran görüntüsü ile sor (hata ekranı, tasarım, diyagram). Headless: numex -p "açıkla" -i resim.png

• Model, birbirinden bağımsız görevleri alt_ajan_paralel ile aynı anda (eşzamanlı, en fazla 4) alt-ajanlara dağıtabilir; çok-dosyalı düzenlemelerde önce toplu değişiklik özeti (N dosya · +x/-y) gösterilir.

• Toplu diff onayı: 2+ dosya değişecekse önce [E] hepsini kabul · [H] hepsini red · [S] tek tek incele seçeneği sunulur; tek tek modda [2/5] ile dosyalar arasında gezinilir (t=kalan tümü, r=kalan hepsini red).

• /proje "C:\yol\proje" — başka bir proje dizinine geçer; RAG indeksi, git ve canlı izleme otomatik o dizine yönelir. (CLI'yi ev dizininden başlattıysanız bunu kullanın.)

• /geri — son tek dosya değişikliğini geri alır (checkpoint)

• /geri-al — son turun tüm dosya değişikliklerini geri alır (tam rewind) + konuşmayı geri sarar

• Oturum dışı: numex undo · numex geri-al

• /plan — plan modunu açar/kapatır (salt-okuma keşif; yazma/komut kapalı, önce plan sunulur)

• /komutlar — tanımlı özel komutları listeler (.numex/commands/*.md)

• /kaydet — oturumu diske kaydeder

• /embed — semantik (embedding) indeks oluşturur; aramalar hibrit olur

• /mod — onay modunu değiştirir (güvenli ↔ yolo)

• /erisim — tam dosya erişimini açar/kapatır (proje ↔ tüm sistem)

Native tool calling (function calling)

Model, native function calling (yerel araç çağırma) ile araçları doğrudan çağırır. Bu, araç kullanımını çok daha güvenilir kılar. Model tek turda birden çok aracı çağırabilir (çoklu dosya düzenleme).

Kullanılabilir araçlar:

• dosya_oku — dosya içeriğini okur
• dosya_yaz — dosya oluşturur/günceller (diff önizleme + onay)
• dosya_duzenle — birebir bul/değiştir (diff önizleme + onay)
• dizin_listele — dizin içeriğini listeler
• dosya_ara — dosyalarda metin/regex arar
• proje_bilgi_ara — proje RAG araması (BM25 + embedding hibrit)
• proje_indeksle — RAG indeksini yenile
• git — git işlemleri: durum/diff/log (okuma), ekle/commit/dal/push (onaylı)
• hafiza_oku / hafiza_ekle — kalıcı oturumlar arası hafıza
• komut_calistir — shell komutu çalıştırır (onay ister)
• web_ara — internette güncel bilgi arar (Serper/Bing/Tavily/Google)
• web_getir — bir URL içeriğini okunabilir metne çevirir
• gorev_listesi — çok adımlı (3+) görevlerde plan çıkarır ve ilerlemeyi takip eder
• alt_ajan — odaklı bir alt görevi izole bir alt-ajana devreder (kendi araç döngüsü, sadece özet döner)

Yazma/komut işlemleri varsayılan olarak onaya tabidir; çoklu değişiklikte t (tümü) ile hepsini birden onaylayabilirsiniz. Yazma işlemleri geri alınabilir (/geri, /geri-al).

Plan modu

numex --plan veya oturum içinde /plan ile açılır. Plan modunda yazma/düzenleme/komut araçları kapalıdır; model yalnızca okuma/arama araçlarıyla keşif yapıp net bir uygulama planı sunar (ne yapılacak, hangi dosyalar değişecek, riskler). Planı onaylayıp /plan ile kapatınca uygulamaya geçilir.

Headless / pipe modu (script & CI)

numex -p "src/utils.js dosyasını incele ve özetle"     # sonucu düz metin yazar
numex -p "testleri çalıştır ve özetle" --json           # { ok, text, tools }
echo "bu değişikliği açıkla" | numex -p                  # stdin'den görev

Headless modda etkileşim yoktur: tehlikeli komutlar (rm -rf, format vb.) reddedilir, diğer işlemler otomatik onaylanır. --yolo, --plan, --tam-erisim bayraklarıyla birleştirilebilir.

Özel komutlar (.numex/commands)

Sık kullandığınız istemleri yeniden kullanılabilir komutlara dönüştürün. .numex/commands/<ad>.md (proje) veya ~/.numex/commands/<ad>.md (global) dosyaları oturum içinde /<ad> olarak çalışır.

numex komut init      # örnek .numex/commands/gozden-gecir.md oluşturur
# REPL içinde:
/komutlar             # tanımlı komutları listele
/gozden-gecir güvenlik   # {{args}} → "güvenlik" ile şablonu çalıştırır

Dosya biçimi (opsiyonel frontmatter + prompt şablonu):

---
aciklama: Değişiklikleri gözden geçir
---
Şu konuda incele: {{args}}

Alt-ajanlar

alt_ajan aracıyla model, odaklı ve bağımsız bir alt görevi izole bir ajana devredebilir. Alt-ajan kendi araç döngüsünde çalışır ve ana ajana yalnızca özet döner — bu, ana bağlamı temiz tutar ve büyük araştırma/çok modüllü işleri düzenler. salt_okuma: true ile alt-ajan yalnızca araştırma yapar. Sonsuz özyineleme engellidir (alt-ajan yeni alt-ajan başlatamaz).

Hooks (yaşam döngüsü olayları)

.numex/hooks.json (proje) veya ~/.numex/hooks.json (global) ile olaylarda shell komutları çalıştırın:

{
  "hooks": {
    "before-tool": [{ "matcher": "komut_calistir", "command": "node scripts/guard.js" }],
    "after-tool":  [{ "matcher": "dosya_yaz", "command": "npx prettier --write ." }],
    "user-prompt": [{ "command": "echo $NUMEX_HOOK_PAYLOAD >> .numex/audit.log" }],
    "session-start": [{ "command": "echo oturum başladı" }],
    "session-end":   [{ "command": "echo oturum bitti" }]
  }
}

• Olaylar: session-start, session-end, user-prompt, before-tool, after-tool
• matcher: araç adı veya regex (* = tümü). Yalnız before-tool/after-tool için geçerli.
• before-tool komutu non-zero çıkış verirse ilgili araç engellenir (güvenlik denetimi).
• Payload JSON'u stdin'den ve NUMEX_EVENT / NUMEX_TOOL / NUMEX_HOOK_PAYLOAD env değişkenlerinden alınır.

Workspace ve erişim

Dosya araçları çalışma dizini değil, proje kökü (.git, package.json vb. ile bulunur) ve allowedPaths içindeki dizinlerle sınırlıdır. --tam-erisim / /erisim ile tüm dosya sistemine izin verebilirsiniz.

Onay modları

• Güvenli (varsayılan): riskli işlemler onay ister.
• Yolo (--yolo / /mod): onay istemez; ancak rm -rf, format, shutdown, git push --force gibi tehlikeli komutlar yine onay ister.
• Güvenilir komutlar: git status, ls, node -v gibi salt-okuma komutları onaysız çalışır. config set trustedCommands "komut1,komut2" ile genişletilebilir.

Proje hafızası

Çalışma dizininde numex.md, NUMEX.md, .numex.md veya AGENTS.md varsa otomatik okunur ve modele proje talimatı olarak verilir.

Proje RAG (bilgi arama)

Proje dosyaları (docs/, src/, kod ve markdown) BM25 ile indekslenir. Model proje_bilgi_ara aracıyla proje genelinde arama yapabilir.

• Açılışta indeks otomatik oluşur (30 dk cache); ayarlar değişince (limit/kapsam) otomatik yeniden kurulur
• /indeks veya proje_indeksle ile yenilenir
• Tam metin arama için dosya_ara kullanılır

Kapsam ve limitler (yapılandırılabilir): İndeks varsayılan olarak proje kökünü, ayrıca ragIndexAllowedPaths açıkken allowedPaths içindeki ek dizinleri de tarar. Desteklenen uzantı listesi geniştir (JS/TS, Python, Go, Rust, Java/Kotlin, PHP, Ruby, Swift, C/C++, SCSS/LESS, TOML/INI, shell, vb.). ~/.numex/config.json ile ayarlanır:

| Anahtar | Varsayılan | Açıklama | |---|---|---| | ragMaxFiles | 4000 | İndekse alınacak azami dosya sayısı | | ragMaxFileKB | 512 | Azami dosya boyutu (KB); büyükler atlanır | | ragExtraExtensions | [] | Ek uzantılar, ör. [".php", ".rb"] | | ragIndexAllowedPaths | true | allowedPaths dizinlerini de indeksle |

REPL'de /izin "C:\yol\dizin" ile bir dizini hem dosya araçlarına hem RAG indeksine ekleyebilirsiniz (/izin sil <yol> ile kaldırılır).

Semantik (embedding) arama: /embed ile Numex embeddings kullanarak semantik indeks oluşturulur. Bundan sonra aramalar hibrit çalışır: BM25 (kelime) + kosinüs benzerliği (anlam) skorları harmanlanır (0.45/0.55). Bu, Cursor'a benzer şekilde anlam bazlı kod/doküman bulmayı sağlar.

Kalıcı hafıza (oturumlar arası)

~/.numex/memory.md dosyasında oturumlar arası notlar tutulur. Model hafiza_ekle / hafiza_oku araçlarını kullanır.

• /hafiza — dosyayı terminale yazdırır

Oturum özeti (bağlam sıkıştırma)

14+ tur veya ~9000+ karakter geçmişte eski mesajlar otomatik özetlenir; son 6 tur aynen korunur. Token limitine takılmadan uzun oturumlar sürdürülebilir.

Oturum kaydı

• Her tur otomatik kayıt → ~/.numex/sessions/
• numex --devam — son oturumu yükle
• /temizle — geçmişi sıfırla

MCP (Model Context Protocol)

GitHub, Postgres, dosya sistemi ve diğer MCP sunucularına bağlanın — Cursor/Claude Desktop ile aynı ekosistem.

numex mcp init          # ~/.numex/mcp.json oluştur
# REPL içinde:
/mcp                    # sunuculara bağlan
/mcp list               # yapılandırmayı listele

Örnek ~/.numex/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/projeleriniz"]
    }
  }
}

MCP araçları modele mcp__sunucu__arac adıyla sunulur.

VS Code eklentisi

numex-vscode/ — seçili kodu sor, satır içi tamamlama (LSP tanılama + API), CodeLens "Numex'e sor".

İndirme

• Web: numexai.com.tr/codex-cli
• npm: npm install -g @numexai/cli
• API anahtarı: numexai.com.tr/api

Canlı dosya izleme (otomatik indeksleme)

REPL açıldığında proje kökü izlenir; dosyalar değiştikçe RAG indeksi otomatik yenilenir (Cursor'un codebase indexing'ine benzer). 1.5 sn debounce ile toplu değişiklikler tek seferde işlenir.

• /izle — izlemeyi aç/kapat
• numex --izleme-yok veya config set watch false — kapatır
• config set autoEmbed true — izleme sırasında embedding indeksini de yeniler (token tüketir)

Otomatik yedek ve geri alma

Dosya yazma riski olan görevlerde (klasör oluştur, düzenle, kod yaz vb.) tur başlamadan önce CLI sessizce yedek alır:

• Git deposu varsa ve değişiklik varsa: git stash create (çalışma ağacını bozmaz)
• Her dosya yazımında checkpoint yedeklenir (~/.numex/checkpoints/)

Ekrana şu bilgi düşer: Yedek alındı; bir sorun olursa numex undo veya /geri-al yazarak eski haline dönebilirsiniz.

Otomatik sözdizimi kontrolü (Hata Kontrolü)

Dosya yazıldıktan sonra CLI, değiştirilen .js/.mjs/.cjs dosyalarında node --check ile sözdizimi kontrolü yapar. Görev listesine Hata Kontrolü adımı eklenir; hata varsa model otomatik düzeltmeye çalışır (en fazla 3 tur).

Örnek çıktı: Hata tespit edildi: script.js 45. satırda — ... Kendi kendine düzeltiliyor…

Otomatik lint/hata düzeltme döngüsü

Değişiklikten sonra projedeki tip/lint kontrolü (tsconfig → tsc, npm run typecheck/lint, eslint) çalıştırılır; hata varsa model hataları görüp düzeltir (en fazla 3 tur).

• numex --lint veya config set autoLint true — açar
• /lint — tek seferlik çalıştır · /lint oto — otomatik döngüyü aç/kapat
• lint_calistir aracı — model istediğinde de çalıştırabilir

VS Code eklentisi

numex-vscode/ klasöründe CLI'yi editöre bağlayan eklenti bulunur: seçili kodu sorma, dosya hakkında sohbet, entegre terminalde REPL. Kurulum için o klasördeki README'ye bakın.

Zengin çıktı

Yanıtlar terminalde markdown (başlık, liste, kalın, kod) ve kod bloğu sözdizimi renklendirmesiyle gösterilir.

Yapılandırma

Ayarlar ~/.numex/config.json içinde tutulur (izin 600). Ortam değişkenleriyle geçersiz kılınabilir:

• NUMEX_API_KEY
• NUMEX_BASE_URL

Mimari

bin/numex.js      → giriş noktası, argüman ayrıştırma
src/config.js     → API anahtarı / ayar yönetimi
src/api.js        → /chat/agent (function calling) + /chat/stream (SSE) istemcisi
src/agent.js      → sistem talimatı + proje hafızası
src/tools/        → dosya/shell/git araçları + JSON şemaları
src/workspace.js  → proje kökü tespiti + güvenli yol çözümleme
src/git.js        → git aracı (durum/diff/ekle/commit/dal/push)
src/approval.js   → onay modları + güvenilir/tehlikeli komut listeleri
src/watcher.js    → canlı dosya izleme + otomatik yeniden indeksleme
src/lint.js       → lint/tip kontrolü tespiti + çalıştırma
src/runner.js     → native function-calling döngüsü (tool_use → tool_result)
src/markdown.js   → markdown + kod renklendirme
src/diff.js       → renkli diff önizleme
src/rag/           → proje RAG: indeksleme + BM25 + embedding hibrit arama
src/context.js     → uzun oturum özeti / sıkıştırma
src/persistentMemory.js → ~/.numex/memory.md kalıcı hafıza
src/checkpoint.js → dosya değişikliği geri alma + tam rewind (turn bazlı)
src/autoBackup.js  → tur öncesi git stash create yedek
src/syntaxCheck.js → yazılan JS dosyalarında node --check
src/commands.js   → özel kullanıcı komutları (.numex/commands/*.md)
src/hooks.js      → yaşam döngüsü hook'ları (.numex/hooks.json)
src/subagent      → izole alt-ajan (runner.js: runSubagent)
src/tools/web.js  → web_ara + web_getir
src/tools/taskList.js → gorev_listesi (plan/ilerleme)
src/repl.js       → interaktif oturum

Backend:

• POST /api/developer/chat/agent — native function calling (araçlı ajan turu)
• POST /api/developer/chat/stream — SSE akışlı sohbet
• POST /api/developer/embeddings — toplu embedding üretimi (semantik RAG)
• POST /api/developer/search — web araması (web_ara aracı; token metrelenir)

Kimlik doğrulama: x-api-key başlığı.