@xortex/xcode 3.0.5 → 3.1.0

package/INSTALLATION.md

@@ -0,0 +1,285 @@
+# Installation Guide
+
+Complete installation instructions for XCode.
+
+## Prerequisites
+
+You need **either** Bun or Node.js installed:
+
+### Option A: Bun (Recommended - Faster)
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Option B: Node.js
+```bash
+# macOS
+brew install node
+
+# Ubuntu/Debian
+sudo apt-get install nodejs npm
+
+# Or download from https://nodejs.org/
+```
+
+---
+
+## Installation Methods
+
+### Method 1: One-Line Curl Install (macOS/Linux) ⭐ Recommended
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/XortexAI/XCode/main/install.sh | bash
+```
+
+What this does:
+1. Clones XCode to `~/.xcode`
+2. Installs dependencies with Bun/npm
+3. Creates `~/.local/bin/xcode` launcher
+4. Adds to PATH if needed
+
+### Method 2: npm Global Install
+
+```bash
+npm install -g @xortex/xcode
+```
+
+This installs XCode globally and adds `xcode` to your PATH automatically.
+
+### Method 3: Manual Clone
+
+```bash
+# 1. Clone repository
+git clone https://github.com/XortexAI/XCode.git ~/.xcode
+
+# 2. Install dependencies
+cd ~/.xcode
+bun install
+
+# 3. Create symlink
+mkdir -p ~/.local/bin
+ln -s ~/.xcode/bin/xcode ~/.local/bin/xcode
+
+# 4. Add to PATH (if not already)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Method 4: Docker (Coming Soon)
+
+```bash
+docker run -it xortex/xcode
+```
+
+---
+
+## Post-Installation
+
+### 1. Verify Installation
+
+```bash
+xcode --version
+# Output: xcode v3.0.2 — AI coding assistant with XMem memory
+```
+
+Or run the test suite:
+```bash
+xcode-test
+```
+
+### 2. Configure API Keys
+
+Add to your `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`:
+
+```bash
+# Required: At least one of these
+export OPENROUTER_API_KEY=sk-or-v1-...        # For multi-model access
+export ANTHROPIC_API_KEY=sk-ant-...           # For Claude models
+export GEMINI_API_KEY=...                     # For Google Gemini
+
+# Optional: XMem memory server
+export XMEM_API_URL=http://localhost:8000
+export XMEM_API_KEY=...
+```
+
+Reload your shell:
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### 3. First Run
+
+```bash
+# Interactive session with default model
+xcode
+
+# Or use a specific model
+xcode --model gemini-2.5-pro
+```
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+
+- Requires macOS 12 (Monterey) or later
+- Works with both Intel and Apple Silicon
+- If you get "unidentified developer" warnings, go to System Preferences > Security & Privacy
+
+### Linux
+
+- Tested on Ubuntu 20.04+, Debian 11+, Fedora 35+
+- Requires `git` and `curl` (usually pre-installed)
+- May need to install `build-essential` for native modules:
+  ```bash
+  sudo apt-get install build-essential
+  ```
+
+### Windows
+
+Currently supported via:
+- WSL2 (Windows Subsystem for Linux) - **Recommended**
+- Git Bash
+- PowerShell (with Node.js)
+
+WSL2 Installation:
+```powershell
+# In WSL2 terminal
+sudo apt-get update && sudo apt-get install git curl
+curl -fsSL https://raw.githubusercontent.com/XortexAI/XCode/main/install.sh | bash
+```
+
+---
+
+## Troubleshooting
+
+### "xcode: command not found"
+
+**Problem:** The binary isn't in your PATH
+
+**Solution:**
+```bash
+# Check if ~/.local/bin is in PATH
+echo $PATH | grep ".local/bin"
+
+# If not, add it
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### "Bun not found" or "tsx not found"
+
+**Problem:** Runtime not installed
+
+**Solution:**
+```bash
+# Install Bun (fastest)
+curl -fsSL https://bun.sh/install | bash
+
+# Or install tsx for Node
+npm install -g tsx
+```
+
+### "Permission denied"
+
+**Problem:** Script isn't executable
+
+**Solution:**
+```bash
+chmod +x ~/.local/bin/xcode
+```
+
+### "Module not found" errors
+
+**Problem:** Dependencies not installed
+
+**Solution:**
+```bash
+cd ~/.xcode
+bun install  # or: npm install
+```
+
+### API Key Errors
+
+**Problem:** Missing or invalid API key
+
+**Solution:**
+```bash
+# Check if key is set
+echo $OPENROUTER_API_KEY
+
+# Set it if empty
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+
+# Make it permanent by adding to ~/.bashrc
+```
+
+### Slow Performance
+
+**Problem:** Using npm instead of Bun
+
+**Solution:** Install Bun for 10x faster startup:
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+---
+
+## Updating XCode
+
+### If installed via curl script:
+
+```bash
+# Just run the install script again
+curl -fsSL https://raw.githubusercontent.com/XortexAI/XCode/main/install.sh | bash
+```
+
+### If installed via npm:
+
+```bash
+npm update -g @xortex/xcode
+```
+
+### If installed manually:
+
+```bash
+cd ~/.xcode
+git pull origin main
+bun install
+```
+
+---
+
+## Uninstalling
+
+### If installed via curl script:
+
+```bash
+rm -rf ~/.xcode ~/.local/bin/xcode
+```
+
+### If installed via npm:
+
+```bash
+npm uninstall -g @xortex/xcode
+```
+
+---
+
+## Getting Help
+
+- **GitHub Issues**: https://github.com/XortexAI/XCode/issues
+- **Documentation**: https://github.com/XortexAI/XCode/tree/main/docs
+- **Discord**: [Join our community](https://discord.gg/xortex)
+
+---
+
+## Next Steps
+
+After installation:
+
+1. [Quick Start Guide](QUICKSTART.md) - Get running in 2 minutes
+2. [Configure Models](docs/models.md) - Set up your preferred AI models
+3. [XMem Integration](docs/xmem.md) - Enable persistent memory
+4. [Usage Guide](docs/usage.md) - Learn the commands and features

package/QUICKSTART.md

@@ -0,0 +1,151 @@
+# Quick Start Guide
+
+Get XCode running in under 2 minutes.
+
+## Installation
+
+### Option 1: One-Line Install (Recommended)
+
+**macOS/Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/XortexAI/XCode/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+# Coming soon - use npm install for now
+```
+
+### Option 2: npm Install
+
+```bash
+npm install -g @xortex/xcode
+```
+
+### Option 3: Manual Install
+
+```bash
+git clone https://github.com/XortexAI/XCode.git ~/.xcode
+cd ~/.xcode
+bun install
+ln -s ~/.xcode/bin/xcode ~/.local/bin/xcode
+```
+
+## First Run
+
+### 1. Set Your API Key
+
+**For OpenRouter (recommended for multi-model access):**
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+**For Anthropic Claude:**
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**For Google Gemini:**
+```bash
+export GEMINI_API_KEY=...
+```
+
+### 2. Start XCode
+
+```bash
+# Default mode (uses Anthropic or Gemini if configured)
+xcode
+
+# Use specific models via OpenRouter
+xcode --model gemini-2.5-pro
+xcode --model kimi-k2.5
+xcode --model deepseek-v3.2
+
+# Enable OpenRouter mode explicitly
+CLAUDE_CODE_USE_OPENROUTER=1 xcode
+```
+
+## Configuration
+
+Create `~/.bashrc` or `~/.zshrc` entries:
+
+```bash
+# XCode configuration
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+export XMEM_API_URL=http://localhost:8000
+alias xc='xcode'  # Short alias
+```
+
+Then reload:
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+## Using XMem Memory
+
+For the best experience, run the XMem memory server:
+
+```bash
+# Terminal 1: Start XMem
+git clone https://github.com/XortexAI/XMem.git
+cd XMem
+pip install -e .
+uvicorn src.api.app:create_app --factory --host 0.0.0.0 --port 8000
+
+# Terminal 2: Start XCode with XMem
+export XMEM_API_URL=http://localhost:8000
+xcode
+```
+
+## Common Commands
+
+Once inside XCode:
+
+```
+/model gemini-2.5-pro    # Switch model
+/memory                  # Edit memory files
+/compact                 # Compact conversation
+/clear                   # Clear history
+/quit                    # Exit
+```
+
+## Troubleshooting
+
+### "xcode: command not found"
+
+Add to PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### "Bun not found"
+
+Install Bun:
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Or use Node.js:
+```bash
+npm install -g tsx
+# XCode will auto-detect and use npx tsx
+```
+
+### API Errors
+
+Check your API key:
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+xcode --model gemini-2.5-pro
+```
+
+## Next Steps
+
+- Read the [full documentation](docs/)
+- Explore [XMem integration](docs/xmem.md)
+- Configure [custom models](docs/models.md)
+- Set up [plugins](docs/plugins.md)
+
+---
+
+**Need help?** Open an issue: https://github.com/XortexAI/XCode/issues