🍝 ZuppaClaude

⚡ Claude Code için tek komutla kurulum paketi - SuperClaude + Spec Kit + Claude-Z + Claude HUD

🇹🇷 Türkçe

📦 Nedir?

ZuppaClaude, Claude Code deneyiminizi güçlendiren araçları tek komutla kurar:

| Araç | Açıklama | |------|----------| | ⚡ SuperClaude | 30+ slash komutu ile gelişmiş iş akışları | | 📋 Spec Kit | Spec-driven development CLI aracı | | 🌐 Claude-Z | z.ai backend desteği (opsiyonel) | | 📊 Claude HUD | Gerçek zamanlı durum göstergesi (opsiyonel) | | 📝 CLAUDE.md | Optimize edilmiş sistem talimatları |

🚀 Hızlı Kurulum

📦 NPM ile (Önerilen)

npx zuppaclaude

Veya global kurulum:

npm install -g zuppaclaude
zuppaclaude

🐚 Shell ile

🍎 macOS / 🐧 Linux:

curl -fsSL https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/install.sh | bash

🌍 Alternatif (jsDelivr CDN):

curl -fsSL https://cdn.jsdelivr.net/gh/hasankaantan/zuppaclaude@main/install.sh | bash

🪟 Windows:

# Winget ile (önerilen)
winget install Anthropic.ClaudeCode

# veya PowerShell script ile
irm https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/install.ps1 | iex

📋 Gereksinimler

Kurulum scripti eksik bağımlılıkları otomatik kontrol eder:

| Gereksinim | Açıklama | |------------|----------| | 💻 OS | macOS, Linux veya Windows 10+ | | 📦 Node.js | 18.0 veya üzeri | | 🐍 Python | 3.8 veya üzeri | | 📂 git | Versiyon kontrol | | 🤖 Claude Code | v2.x (önerilir) |

✅ Kurulum Sonrası

1. 🔄 Claude Code'u yeniden başlat

2. ⚡ SuperClaude test et:

   /sc:help

3. 📋 Spec Kit test et:

   specify --help

4. 🌐 Claude-Z test et (kurulduysa):

   claude-z

⚡ SuperClaude Komutları

🎯 Planlama & Tasarım

| Komut | Açıklama | |-------|----------| | /sc:brainstorm | 💡 Fikir geliştirme | | /sc:design | 🏗️ Mimari tasarım | | /sc:estimate | ⏱️ Zaman/kaynak tahmini | | /sc:spec-panel | 📑 Spesifikasyon paneli |

💻 Geliştirme

| Komut | Açıklama | |-------|----------| | /sc:implement | ⚙️ Kod implementasyonu | | /sc:build | 🔨 Build ve derleme | | /sc:improve | ✨ Kod iyileştirme | | /sc:explain | 📖 Kod açıklama |

🧪 Test & Kalite

| Komut | Açıklama | |-------|----------| | /sc:test | 🧪 Test oluşturma | | /sc:analyze | 🔍 Kod analizi | | /sc:troubleshoot | 🐛 Hata ayıklama | | /sc:reflect | 🪞 Retrospektif |

📊 Proje Yönetimi

| Komut | Açıklama | |-------|----------| | /sc:task | ✅ Görev yönetimi | | /sc:workflow | 🔄 İş akışı yönetimi | | /sc:pm | 📈 Proje yönetimi |

📋 Spec Kit İş Akışı

specify init         # 🚀 Proje başlat
specify constitution # 📜 Proje kuralları
specify spec         # 📋 Fonksiyonel gereksinimler
specify plan         # 📐 Teknik plan
specify tasks        # ✅ Görev breakdown

🌐 Claude-Z (z.ai Backend)

Kurulum sırasında Z.AI API key'inizi girmeniz istenir (z.ai adresinden alın).

# z.ai backend ile Claude Code çalıştır
claude-z

🔌 Sağladığı MCP Serverlar: | Server | Açıklama | |--------|----------| | web-search-prime | 🔍 Gelişmiş web arama | | web-reader | 📄 Web sayfası okuma | | zread | 📚 Doküman okuma | | zai-mcp-server | 🔗 Z.AI MCP entegrasyonu |

📊 Claude HUD (Durum Göstergesi)

Claude Code'a gerçek zamanlı statusline ekler. Kurulum sırasında etkinleştirmeyi seçebilirsiniz.

📈 Gösterdikleri:

• 📊 Context window kullanımı
• 🔧 Aktif araçlar ve dosya işlemleri
• 🤖 Çalışan agent'lar
• ✅ Todo/görev ilerlemesi

⚙️ Kurulum sonrası:

setup-claude-hud  # Talimatları gösterir

Ardından Claude Code içinde:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

🩺 Sistem Kontrolü (Doctor)

ZuppaClaude kurulumunuzun sağlığını kontrol edin:

npx zuppaclaude doctor    # 🔍 Sistem kontrolü

Veya Claude Code içinden:

/zc:doctor

🔍 Kontrol Edilen Öğeler: | Kategori | Kontroller | |----------|------------| | 💻 Sistem | OS, Node.js versiyonu, disk alanı | | 🤖 Claude Code | Versiyon, güncellik, dizin | | 📦 ZuppaClaude | Versiyon, güncellik, ayarlar | | 🧩 Bileşenler | SuperClaude, Spec Kit, Claude-Z, HUD, rclone | | 🔧 Bağımlılıklar | Git, Python, Pip | | 🌐 Ortam | Environment variables |

⚙️ Ayar Yönetimi

ZuppaClaude seçimlerinizi kaydeder ve tekrar kurulumda otomatik kullanır.

📦 NPM ile:

npx zuppaclaude settings show              # 👁️ Ayarları görüntüle
npx zuppaclaude settings export ~/backup.json  # 💾 Dışa aktar
npx zuppaclaude settings import ~/backup.json  # 📥 İçe aktar
npx zuppaclaude settings reset             # 🔄 Fabrika ayarları

🐚 Shell ile:

./zc-settings.sh show              # 👁️ Ayarları görüntüle
./zc-settings.sh export ~/backup.json  # 💾 Dışa aktar
./zc-settings.sh import ~/backup.json  # 📥 İçe aktar
./zc-settings.sh reset             # 🔄 Fabrika ayarları

✨ Özellikler: | Özellik | Açıklama | |---------|----------| | 💾 Otomatik kayıt | Kurulum sonrası tercihler kaydedilir | | ⚡ Hızlı kurulum | Önceki ayarlarla tek komutla kurulum | | 🔐 API key koruması | Base64 encoded saklama | | 🛡️ Uninstall koruması | Kaldırırken ayarları koruma opsiyonu |

💾 Yedekleme & Geri Yükleme

Claude Code session'larınızı ve ayarlarınızı yedekleyin. Context kaybı, format veya compacting durumlarında kullanışlı.

🔄 Tam Yedekleme (Sessions + Ayarlar):

npx zuppaclaude backup              # 💾 Lokal tam yedek
npx zuppaclaude backup --cloud gdrive  # ☁️ Google Drive'a yedekle
npx zuppaclaude restore <id>        # ♻️ Yedekten geri yükle
npx zuppaclaude restore <id> --cloud gdrive  # ☁️ Cloud'dan geri yükle

📋 Sadece Session İşlemleri:

npx zuppaclaude session list        # 📋 Tüm session'ları listele
npx zuppaclaude session backup      # 💾 Sadece session'ları yedekle
npx zuppaclaude session backups     # 📦 Mevcut yedekleri listele

☁️ Cloud Yedekleme (rclone)

Google Drive, Dropbox, OneDrive, S3, SFTP ve 40+ cloud servise yedekleme.

# Kurulum
brew install rclone      # macOS
rclone config            # Remote ayarla (gdrive, dropbox vs.)

# Kullanım
npx zuppaclaude cloud setup         # 📖 Kurulum talimatları
npx zuppaclaude cloud remotes       # 📋 Mevcut remote'ları listele
npx zuppaclaude backup --cloud gdrive  # ☁️ Yedekle ve upload et
npx zuppaclaude cloud backups gdrive   # 📦 Cloud'daki yedekleri listele

✨ Özellikler: | Özellik | Açıklama | |---------|----------| | 🔒 Güvenli restore | Mevcut session'lar üzerine yazılmaz | | 📜 Tam yedek | Sessions + Settings + History | | ☁️ 40+ cloud | rclone ile Google Drive, Dropbox, S3, SFTP... | | 🔐 Encryption | rclone encryption desteği |

🤖 Ralph (Otonom PRD Geliştirme)

PRD (Product Requirements Document) dosyasındaki user story'leri otomatik olarak implement eden otonom AI agent döngüsü.

🚀 Başlatma:

npx zuppaclaude ralph init       # 📁 Proje dosyalarını oluştur
npx zuppaclaude ralph run        # 🔄 Döngüyü başlat (varsayılan: 10 iterasyon)
npx zuppaclaude ralph run 20     # 🔄 20 iterasyon ile çalıştır
npx zuppaclaude ralph status     # 📊 PRD durumunu göster

📂 Dosyalar: | Dosya | Açıklama | |-------|----------| | prd.json | User story'ler ve pass/fail durumu | | ralph-prompt.md | Her iterasyona verilen talimatlar | | progress.txt | Öğrenilen şeyler (kalıcı bellek) | | AGENTS.md | Kod pattern'leri ve convention'lar |

🔄 Nasıl Çalışır:

1. PRD'den en yüksek öncelikli incomplete story'yi seçer
2. Minimal, focused değişiklikler yapar
3. Quality check'leri çalıştırır (typecheck, lint, test)
4. progress.txt'e öğrenilenleri yazar
5. Story'yi passes: true olarak işaretler
6. Sonraki iterasyona geçer

💡 snarktank/ralph projesinden esinlenilmiştir.

🗑️ Kaldırma

📦 NPM ile:

npx zuppaclaude uninstall

🐚 Shell ile:

🍎 macOS / 🐧 Linux:

curl -fsSL https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/uninstall.sh | bash

🪟 Windows:

irm https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/uninstall.ps1 | iex

📁 Dosya Konumları

| Dosya | 🍎🐧 macOS/Linux | 🪟 Windows | |-------|------------------|------------| | ⚡ SuperClaude | ~/.claude/commands/sc/ | %USERPROFILE%\.claude\commands\sc\ | | 📝 Konfigürasyon | ~/.claude/CLAUDE.md | %USERPROFILE%\.claude\CLAUDE.md | | 🌐 Claude-Z | ~/.local/bin/claude-z | %USERPROFILE%\.local\bin\claude-z.cmd | | 📊 Claude HUD | ~/.local/bin/setup-claude-hud | %USERPROFILE%\.local\bin\setup-claude-hud.cmd | | 🔧 Z.AI Config | ~/.config/zai/ | %USERPROFILE%\.config\zai\ | | ⚙️ Ayarlar | ~/.config/zuppaclaude/ | %USERPROFILE%\.config\zuppaclaude\ |

🇬🇧 English

📦 What is it?

ZuppaClaude installs tools to supercharge your Claude Code experience with a single command:

| Tool | Description | |------|-------------| | ⚡ SuperClaude | 30+ slash commands for enhanced workflows | | 📋 Spec Kit | Spec-driven development CLI tool | | 🌐 Claude-Z | z.ai backend support (optional) | | 📊 Claude HUD | Real-time status display (optional) | | 📝 CLAUDE.md | Optimized system instructions |

🚀 Quick Install

📦 Via NPM (Recommended)

npx zuppaclaude

Or install globally:

npm install -g zuppaclaude
zuppaclaude

🐚 Via Shell

🍎 macOS / 🐧 Linux:

curl -fsSL https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/install.sh | bash

🌍 Alternative (jsDelivr CDN):

curl -fsSL https://cdn.jsdelivr.net/gh/hasankaantan/zuppaclaude@main/install.sh | bash

🪟 Windows:

# With Winget (recommended)
winget install Anthropic.ClaudeCode

# or PowerShell script
irm https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/install.ps1 | iex

📋 Requirements

The installer automatically checks for missing dependencies:

| Requirement | Description | |-------------|-------------| | 💻 OS | macOS, Linux, or Windows 10+ | | 📦 Node.js | 18.0 or higher | | 🐍 Python | 3.8 or higher | | 📂 git | Version control | | 🤖 Claude Code | v2.x (recommended) |

✅ After Installation

1. 🔄 Restart Claude Code

2. ⚡ Test SuperClaude:

   /sc:help

3. 📋 Test Spec Kit:

   specify --help

4. 🌐 Test Claude-Z (if installed):

   claude-z

⚡ SuperClaude Commands

🎯 Planning & Design

| Command | Description | |---------|-------------| | /sc:brainstorm | 💡 Idea development | | /sc:design | 🏗️ Architectural design | | /sc:estimate | ⏱️ Time/resource estimation | | /sc:spec-panel | 📑 Specification panel |

💻 Development

| Command | Description | |---------|-------------| | /sc:implement | ⚙️ Code implementation | | /sc:build | 🔨 Build and compile | | /sc:improve | ✨ Code improvement | | /sc:explain | 📖 Code explanation |

🧪 Testing & Quality

| Command | Description | |---------|-------------| | /sc:test | 🧪 Test creation | | /sc:analyze | 🔍 Code analysis | | /sc:troubleshoot | 🐛 Debugging | | /sc:reflect | 🪞 Retrospective |

📊 Project Management

| Command | Description | |---------|-------------| | /sc:task | ✅ Task management | | /sc:workflow | 🔄 Workflow management | | /sc:pm | 📈 Project management |

📋 Spec Kit Workflow

specify init         # 🚀 Initialize project
specify constitution # 📜 Project rules
specify spec         # 📋 Functional requirements
specify plan         # 📐 Technical plan
specify tasks        # ✅ Task breakdown

🌐 Claude-Z (z.ai Backend)

During installation, you'll be asked for your Z.AI API key (get it from z.ai).

# Run Claude Code with z.ai backend
claude-z

🔌 Provided MCP Servers: | Server | Description | |--------|-------------| | web-search-prime | 🔍 Enhanced web search | | web-reader | 📄 Web page reading | | zread | 📚 Document reading | | zai-mcp-server | 🔗 Z.AI MCP integration |

📊 Claude HUD (Status Display)

Adds a real-time statusline to Claude Code. You can enable it during installation.

📈 What it shows:

• 📊 Context window usage
• 🔧 Active tools and file operations
• 🤖 Running agents
• ✅ Todo/task progress

⚙️ After installation:

setup-claude-hud  # Shows instructions

Then inside Claude Code:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

🩺 System Health Check (Doctor)

Check your ZuppaClaude installation health:

npx zuppaclaude doctor    # 🔍 System health check

Or from within Claude Code:

/zc:doctor

🔍 What it Checks: | Category | Checks | |----------|--------| | 💻 System | OS, Node.js version, disk space | | 🤖 Claude Code | Version, updates, directory | | 📦 ZuppaClaude | Version, updates, settings | | 🧩 Components | SuperClaude, Spec Kit, Claude-Z, HUD, rclone | | 🔧 Dependencies | Git, Python, Pip | | 🌐 Environment | Environment variables |

⚙️ Settings Management

ZuppaClaude saves your choices and automatically uses them on reinstall.

📦 Via NPM:

npx zuppaclaude settings show              # 👁️ View settings
npx zuppaclaude settings export ~/backup.json  # 💾 Export
npx zuppaclaude settings import ~/backup.json  # 📥 Import
npx zuppaclaude settings reset             # 🔄 Reset to defaults

🐚 Via Shell:

🍎🐧 macOS/Linux:

./zc-settings.sh show              # 👁️ View settings
./zc-settings.sh export ~/backup.json  # 💾 Export
./zc-settings.sh import ~/backup.json  # 📥 Import
./zc-settings.sh reset             # 🔄 Reset to defaults

🪟 Windows:

.\zc-settings.ps1 show
.\zc-settings.ps1 export ~\backup.json
.\zc-settings.ps1 import ~\backup.json
.\zc-settings.ps1 reset

✨ Features: | Feature | Description | |---------|-------------| | 💾 Auto-save | Preferences saved after installation | | ⚡ Quick reinstall | One-command reinstall with previous settings | | 🔐 API key protection | Base64 encoded storage | | 🛡️ Uninstall protection | Option to preserve settings when uninstalling |

💾 Backup & Restore

Backup your Claude Code sessions and settings. Useful for context loss, formatting, or conversation compacting.

🔄 Full Backup (Sessions + Settings):

npx zuppaclaude backup              # 💾 Local full backup
npx zuppaclaude backup --cloud gdrive  # ☁️ Backup to Google Drive
npx zuppaclaude restore <id>        # ♻️ Restore from backup
npx zuppaclaude restore <id> --cloud gdrive  # ☁️ Restore from cloud

📋 Session-only Operations:

npx zuppaclaude session list        # 📋 List all sessions
npx zuppaclaude session backup      # 💾 Backup sessions only
npx zuppaclaude session backups     # 📦 List available backups

☁️ Cloud Backup (rclone)

Backup to Google Drive, Dropbox, OneDrive, S3, SFTP, and 40+ cloud services.

# Setup
brew install rclone      # macOS
rclone config            # Configure remote (gdrive, dropbox, etc.)

# Usage
npx zuppaclaude cloud setup         # 📖 Setup instructions
npx zuppaclaude cloud remotes       # 📋 List configured remotes
npx zuppaclaude backup --cloud gdrive  # ☁️ Backup and upload
npx zuppaclaude cloud backups gdrive   # 📦 List cloud backups

✨ Features: | Feature | Description | |---------|-------------| | 🔒 Safe restore | Existing sessions are not overwritten | | 📜 Full backup | Sessions + Settings + History | | ☁️ 40+ clouds | Google Drive, Dropbox, S3, SFTP via rclone | | 🔐 Encryption | rclone encryption support |

🤖 Ralph (Autonomous PRD Development)

Autonomous AI agent loop that implements user stories from a PRD (Product Requirements Document) automatically.

🚀 Getting Started:

npx zuppaclaude ralph init       # 📁 Create project files
npx zuppaclaude ralph run        # 🔄 Start loop (default: 10 iterations)
npx zuppaclaude ralph run 20     # 🔄 Run with 20 iterations
npx zuppaclaude ralph status     # 📊 Show PRD status

📂 Files: | File | Description | |------|-------------| | prd.json | User stories with pass/fail status | | ralph-prompt.md | Instructions for each iteration | | progress.txt | Learnings (persistent memory) | | AGENTS.md | Code patterns and conventions |

🔄 How it Works:

1. Selects highest priority incomplete story from PRD
2. Makes minimal, focused changes
3. Runs quality checks (typecheck, lint, test)
4. Documents learnings in progress.txt
5. Marks story as passes: true
6. Moves to next iteration

💡 Inspired by snarktank/ralph

🗑️ Uninstall

📦 Via NPM:

npx zuppaclaude uninstall

🐚 Via Shell:

🍎 macOS / 🐧 Linux:

curl -fsSL https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/uninstall.sh | bash

🪟 Windows:

irm https://raw.githubusercontent.com/hasankaantan/zuppaclaude/main/uninstall.ps1 | iex

📁 File Locations

| File | 🍎🐧 macOS/Linux | 🪟 Windows | |------|------------------|------------| | ⚡ SuperClaude | ~/.claude/commands/sc/ | %USERPROFILE%\.claude\commands\sc\ | | 📝 Configuration | ~/.claude/CLAUDE.md | %USERPROFILE%\.claude\CLAUDE.md | | 🌐 Claude-Z | ~/.local/bin/claude-z | %USERPROFILE%\.local\bin\claude-z.cmd | | 📊 Claude HUD | ~/.local/bin/setup-claude-hud | %USERPROFILE%\.local\bin\setup-claude-hud.cmd | | 🔧 Z.AI Config | ~/.config/zai/ | %USERPROFILE%\.config\zai\ | | ⚙️ Settings | ~/.config/zuppaclaude/ | %USERPROFILE%\.config\zuppaclaude\ |

🔧 Troubleshooting

❌ "specify" command not found

🍎🐧 macOS/Linux: Add to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

🪟 Windows: Restart PowerShell or add %USERPROFILE%\.local\bin to PATH.

❌ SuperClaude commands not showing

🔄 Restart Claude Code completely (quit and reopen).

❌ Execution Policy Error (Windows)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

🙏 Credits

| Project | Author | |---------|--------| | Claude Code | Anthropic | | SuperClaude Framework | SuperClaude Org | | Spec Kit | GitHub | | z.ai | Z.AI | | Claude HUD | Jarrod Watts | | Ralph | Snarktank |

📄 License

MIT