mageagent-local 2.0.1

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,364 @@
+# Troubleshooting Guide
+
+This guide covers common issues and their solutions when running MageAgent.
+
+## Quick Diagnostics
+
+Run these commands to diagnose issues:
+
+```bash
+# Check if server is running
+mageagent status
+
+# View recent logs
+tail -50 ~/.claude/debug/mageagent.log
+
+# Check error log
+tail -50 ~/.claude/debug/mageagent.error.log
+
+# Check port usage
+lsof -i :3457
+
+# Check memory
+top -l 1 -o mem | head -10
+
+# Check models exist
+ls -la ~/.cache/mlx-models/
+```
+
+## Common Issues
+
+### 1. Server Won't Start
+
+**Symptom**: `mageagent start` fails or exits immediately
+
+**Possible Causes & Solutions**:
+
+#### Port already in use
+```bash
+# Find what's using port 3457
+lsof -i :3457
+
+# Kill the process
+kill -9 <PID>
+
+# Or kill by port
+kill -9 $(lsof -t -i:3457)
+
+# Restart
+mageagent start
+```
+
+#### Python dependencies missing
+```bash
+# Reinstall dependencies
+pip3 install --upgrade mlx mlx-lm fastapi uvicorn pydantic huggingface_hub
+```
+
+#### Server file not found
+```bash
+# Reinstall MageAgent
+mageagent install
+```
+
+#### Permission issues
+```bash
+# Fix permissions
+chmod +x ~/.claude/scripts/mageagent-server.sh
+chmod 644 ~/.claude/mageagent/server.py
+```
+
+---
+
+### 2. Model Not Found Errors
+
+**Symptom**: `FileNotFoundError: Model not found at /path/to/model`
+
+**Solution**:
+
+```bash
+# Check what models exist
+ls -la ~/.cache/mlx-models/
+
+# Download missing models
+mageagent models
+
+# Or download individually
+python3 -c "
+from huggingface_hub import snapshot_download
+snapshot_download('mlx-community/Hermes-3-Llama-3.1-8B-8bit',
+                  local_dir='$HOME/.cache/mlx-models/Hermes-3-Llama-3.1-8B-8bit')
+"
+```
+
+Required models:
+- `Hermes-3-Llama-3.1-8B-8bit` (9GB) - Tool calling
+- `Qwen2.5-Coder-7B-Instruct-4bit` (5GB) - Validation
+- `Qwen2.5-Coder-32B-Instruct-4bit` (18GB) - Coding
+- `Qwen2.5-72B-Instruct-8bit` (77GB) - Primary reasoning
+
+---
+
+### 3. Out of Memory Errors
+
+**Symptom**: Process killed, "Killed: 9", or memory allocation errors
+
+**Solutions**:
+
+1. **Close other applications**
+   ```bash
+   # Check memory pressure
+   memory_pressure
+
+   # See top memory consumers
+   top -l 1 -o mem | head -20
+   ```
+
+2. **Use smaller patterns**
+   - `mageagent:tools` - Only 9GB (Hermes-3)
+   - `mageagent:validator` - Only 5GB (Qwen-7B)
+   - `mageagent:competitor` - Only 18GB (Qwen-32B)
+   - Avoid `mageagent:compete` which loads multiple large models
+
+3. **Restart server to clear model cache**
+   ```bash
+   mageagent restart
+   ```
+
+4. **Check your system memory**
+   - 64GB: Can run tools, validator, competitor
+   - 128GB: Can run all patterns including hybrid and compete
+   - 96GB: May struggle with compete pattern
+
+---
+
+### 4. Slow Responses
+
+**Symptom**: Responses take 60+ seconds
+
+**Causes & Solutions**:
+
+1. **First request loads models** (normal)
+   - 72B model takes 5-10 seconds to load
+   - Subsequent requests are faster
+
+2. **Use faster patterns**
+   ```bash
+   # Fast patterns
+   mageagent:tools      # 3-5s
+   mageagent:validator  # 2-3s
+
+   # Slower patterns (use for important tasks)
+   mageagent:hybrid     # 30-60s
+   mageagent:validated  # 40-80s
+   mageagent:compete    # 60-120s
+   ```
+
+3. **Check system load**
+   ```bash
+   # See if system is under load
+   top -l 1
+
+   # Check thermal throttling
+   pmset -g thermlog
+   ```
+
+---
+
+### 5. Tool Calls Not Extracted
+
+**Symptom**: Response doesn't contain `<tool_calls>` section
+
+**Solutions**:
+
+1. **Verify Hermes-3 Q8 is downloaded**
+   ```bash
+   ls -la ~/.cache/mlx-models/Hermes-3-Llama-3.1-8B-8bit/
+   ```
+
+2. **Use hybrid pattern** (always attempts extraction)
+   ```bash
+   curl -X POST http://localhost:3457/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{"model": "mageagent:hybrid", "messages": [{"role": "user", "content": "Read the file at /tmp/test.txt"}]}'
+   ```
+
+3. **Check prompt contains tool keywords**
+   - "read file", "write file", "execute", "run", "search", "find", "edit"
+   - "tool", "function call", "glob", "grep", "bash"
+
+---
+
+### 6. API Connection Refused
+
+**Symptom**: `curl: (7) Failed to connect to localhost port 3457`
+
+**Solutions**:
+
+1. **Check if server is running**
+   ```bash
+   mageagent status
+   ```
+
+2. **Start the server**
+   ```bash
+   mageagent start
+   ```
+
+3. **Check firewall** (rarely an issue for localhost)
+   ```bash
+   # Temporarily disable firewall for testing
+   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off
+   # Remember to re-enable!
+   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on
+   ```
+
+---
+
+### 7. JSON Parse Errors
+
+**Symptom**: `json.decoder.JSONDecodeError` in logs
+
+**Cause**: Model output not properly formatted
+
+**Solutions**:
+
+1. **Lower temperature**
+   ```bash
+   curl -X POST http://localhost:3457/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{
+       "model": "mageagent:tools",
+       "messages": [...],
+       "temperature": 0.3
+     }'
+   ```
+
+2. **Restart server** (may have corrupted state)
+   ```bash
+   mageagent restart
+   ```
+
+---
+
+### 8. Import Errors
+
+**Symptom**: `ModuleNotFoundError: No module named 'mlx'`
+
+**Solution**:
+```bash
+# Make sure you're using the right Python
+which python3
+# Should be: /usr/bin/python3 or /opt/homebrew/bin/python3
+
+# Reinstall packages
+pip3 install --upgrade mlx mlx-lm fastapi uvicorn pydantic
+
+# If using pyenv or conda, make sure the right env is active
+```
+
+---
+
+### 9. LaunchAgent Issues
+
+**Symptom**: Server doesn't auto-start on boot
+
+**Solutions**:
+
+1. **Check plist syntax**
+   ```bash
+   plutil -lint ~/Library/LaunchAgents/com.adverant.mageagent.plist
+   ```
+
+2. **Reload LaunchAgent**
+   ```bash
+   launchctl unload ~/Library/LaunchAgents/com.adverant.mageagent.plist
+   launchctl load ~/Library/LaunchAgents/com.adverant.mageagent.plist
+   ```
+
+3. **Check system logs**
+   ```bash
+   log show --predicate 'subsystem == "com.apple.launchd"' --last 5m | grep mageagent
+   ```
+
+---
+
+### 10. Claude Code Router Issues
+
+**Symptom**: `/model mageagent,mageagent:hybrid` doesn't work
+
+**Solutions**:
+
+1. **Check router config**
+   ```bash
+   cat ~/.claude-code-router/config.json
+   ```
+
+   Should include:
+   ```json
+   {
+     "providers": [
+       {
+         "name": "mageagent",
+         "api_base_url": "http://localhost:3457/v1/chat/completions",
+         "api_key": "local",
+         "models": ["mageagent:hybrid", ...]
+       }
+     ]
+   }
+   ```
+
+2. **Restart Claude Code Router**
+   ```bash
+   ccr restart
+   ```
+
+3. **Verify MageAgent is responding**
+   ```bash
+   curl http://localhost:3457/health
+   ```
+
+---
+
+## Getting More Help
+
+### Collect Debug Information
+
+Before reporting an issue, collect this info:
+
+```bash
+# System info
+uname -a
+sysctl -n machdep.cpu.brand_string
+sysctl -n hw.memsize | awk '{print $0/1024/1024/1024 " GB"}'
+
+# MageAgent version
+cat ~/.claude/mageagent/server.py | grep "version"
+
+# Python version
+python3 --version
+
+# Installed packages
+pip3 list | grep -E "(mlx|fastapi|uvicorn|pydantic)"
+
+# Server status
+mageagent status
+
+# Recent logs
+tail -100 ~/.claude/debug/mageagent.log
+tail -100 ~/.claude/debug/mageagent.error.log
+```
+
+### Report Issues
+
+Open an issue at: https://github.com/adverant/nexus-local-mageagent/issues
+
+Include:
+1. System information (from above)
+2. Steps to reproduce
+3. Expected vs actual behavior
+4. Relevant log output
+
+---
+
+*Made with care by [Adverant](https://github.com/adverant)*

package/docs/VSCODE_SETUP.md

@@ -0,0 +1,230 @@
+# VSCode Extension Setup Guide
+
+This guide explains how to configure the Claude Code VSCode extension to work with MageAgent for multi-model orchestration.
+
+## Overview
+
+MageAgent runs as a local server on port 3457, providing an OpenAI-compatible API. The Claude Code VSCode extension can be configured to use MageAgent through the Claude Code Router.
+
+## Prerequisites
+
+1. MageAgent server running (`~/.claude/scripts/mageagent-server.sh start`)
+2. Claude Code Router installed (`npm install -g @musistudio/claude-code-router`)
+3. Claude Code VSCode extension installed
+
+## Configuration Steps
+
+### Step 1: Configure Router for MageAgent
+
+Create or update `~/.claude-code-router/config.json`:
+
+```json
+{
+  "providers": [
+    {
+      "name": "mageagent",
+      "api_base_url": "http://localhost:3457/v1/chat/completions",
+      "api_key": "local",
+      "models": [
+        "mageagent:auto",
+        "mageagent:hybrid",
+        "mageagent:validated",
+        "mageagent:compete",
+        "mageagent:tools",
+        "mageagent:primary",
+        "mageagent:validator",
+        "mageagent:competitor"
+      ]
+    },
+    {
+      "name": "anthropic",
+      "api_base_url": "https://api.anthropic.com",
+      "api_key": "${ANTHROPIC_API_KEY}",
+      "models": [
+        "claude-opus-4-5-20251101",
+        "claude-sonnet-4-5-20250929"
+      ]
+    }
+  ],
+  "Router": {
+    "default": "mageagent,mageagent:hybrid"
+  }
+}
+```
+
+### Step 2: Configure Claude Settings
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456"
+  }
+}
+```
+
+This tells Claude Code to route all API calls through your local router.
+
+### Step 3: Set System Environment Variable
+
+Add to your `~/.zshrc`:
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
+```
+
+Then reload:
+```bash
+source ~/.zshrc
+```
+
+### Step 4: Restart VSCode Completely
+
+**Important**: You must completely quit and restart VSCode (not just reload window) for environment variables to take effect.
+
+```bash
+# Quit VSCode completely, then relaunch
+code .
+```
+
+### Step 5: Verify Services Running
+
+Before using VSCode, ensure both services are running:
+
+```bash
+# Check MageAgent server
+curl http://localhost:3457/health
+
+# Check Claude Code Router
+ccr status
+```
+
+## Using MageAgent in VSCode
+
+### Switching Models
+
+Use the `/model` command in any Claude Code session:
+
+```bash
+# Use MageAgent hybrid (recommended)
+/model mageagent,mageagent:hybrid
+
+# Use MageAgent validated for code quality
+/model mageagent,mageagent:validated
+
+# Use MageAgent compete for critical code
+/model mageagent,mageagent:compete
+
+# Switch back to Claude Opus
+/model anthropic,claude-opus-4-5-20251101
+```
+
+### Natural Language Switching
+
+Just say:
+- "use mageagent" → Switches to hybrid pattern
+- "mage validated" → Switches to validated pattern
+- "use claude" → Switches back to Claude
+
+### Pattern Selection Tips
+
+| Pattern | When to Use |
+|---------|-------------|
+| `hybrid` | Default for most tasks |
+| `validated` | Production code, need error checking |
+| `compete` | Critical features, want best quality |
+| `tools` | Quick file operations |
+| `auto` | Let MageAgent decide |
+
+## Troubleshooting
+
+### Extension Not Using Router
+
+1. **Check router is running**:
+   ```bash
+   ccr status
+   ```
+
+2. **Verify environment variable**:
+   ```bash
+   echo $ANTHROPIC_BASE_URL
+   # Should output: http://127.0.0.1:3456
+   ```
+
+3. **Restart VSCode completely** - not just reload window
+
+### MageAgent Server Not Responding
+
+1. **Check server status**:
+   ```bash
+   ~/.claude/scripts/mageagent-server.sh status
+   ```
+
+2. **View logs**:
+   ```bash
+   tail -f ~/.claude/debug/mageagent.log
+   ```
+
+3. **Restart server**:
+   ```bash
+   ~/.claude/scripts/mageagent-server.sh stop
+   ~/.claude/scripts/mageagent-server.sh start
+   ```
+
+### Model Loading Slow
+
+Large models (72B) take 5-10 seconds to load initially. Subsequent requests are faster as models are cached in memory.
+
+Monitor memory usage:
+```bash
+top -l 1 -o mem | head -10
+```
+
+### Out of Memory
+
+If you see memory errors:
+1. Close other applications
+2. Use smaller patterns (`tools`, `validator`)
+3. Restart MageAgent to clear cached models
+
+## Performance Expectations
+
+| Pattern | First Request | Subsequent |
+|---------|---------------|------------|
+| tools | 5-10s | 3-5s |
+| hybrid | 30-45s | 25-35s |
+| validated | 45-60s | 35-50s |
+| compete | 60-90s | 50-70s |
+
+## Direct API Access
+
+You can also use MageAgent directly without the router:
+
+```bash
+curl -X POST http://localhost:3457/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "mageagent:hybrid",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+## Memory Requirements
+
+For full MageAgent capability, you need:
+
+| Pattern | Peak Memory |
+|---------|-------------|
+| tools only | ~9 GB |
+| validator only | ~5 GB |
+| primary only | ~77 GB |
+| hybrid | ~86 GB |
+| validated | ~86 GB |
+| compete | ~100 GB |
+
+Recommended: 128GB unified memory for best experience.
+
+---
+
+*Made with care by [Adverant](https://github.com/adverant)*

package/docs/assets/mageagent-logo.svg

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   viewBox="84.67 462.67 1164 141.2"
+   height="141.2"
+   width="1164"
+   xml:space="preserve"
+   id="svg2"
+   version="1.1"><metadata
+     id="metadata8"><rdf:RDF><cc:Work
+         rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs
+     id="defs6" /><g
+     transform="matrix(1.3333333,0,0,-1.3333333,0,1066.6667)"
+     id="g10"><g
+       transform="scale(0.1)"
+       id="g12"><path
+         id="path16"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="M 1185.5,4439.73 715.215,3563.72 h 221.086 l 345.529,669.45 345.53,-669.45 h 222.51 l -472.94,876.01 H 1185.5" /><path
+         id="path18"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 2747.08,4150.21 c 0,38.92 -6.2,64.75 -18.6,77.49 -12.4,12.73 -35.09,19.1 -68.06,19.1 h -534.64 v -491.38 h 534.64 c 33.95,0 56.88,6.12 68.79,18.38 11.92,12.26 17.87,37.9 17.87,76.94 z m -816.7,-586.49 v 876.01 h 730.04 c 52.77,0 97.33,-4.82 133.7,-14.46 36.35,-9.64 65.47,-26.3 87.35,-49.98 21.87,-23.67 37.31,-53.69 46.29,-90.07 8.99,-36.37 13.49,-80.95 13.49,-133.75 v -299.46 c 0,-52.89 -4.5,-97.78 -13.49,-134.63 -8.98,-36.87 -24.43,-66.91 -46.33,-90.13 -21.9,-23.23 -50.91,-39.62 -87.01,-49.19 -36.1,-9.57 -80.77,-14.34 -134,-14.34 h -730.04" /><path
+         id="path20"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 3456.12,3563.72 -470.29,876.01 h 221.09 l 345.53,-669.45 345.53,669.45 h 222.51 l -472.94,-876.01 h -191.43" /><path
+         id="path22"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 4205.08,3563.72 v 876.01 h 845.05 V 4246.8 h -650.89 v -163.46 h 632.32 v -162 h -632.32 v -165.92 h 650.89 v -191.7 h -845.05" /><path
+         id="path24"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 5948.49,4135.38 c 0,39.43 -4,67.66 -11.99,84.67 -7.98,17.02 -27.12,25.52 -57.39,25.52 h -508.64 v -238.95 h 508.64 c 25.35,0 43.24,6.06 53.7,18.19 10.45,12.14 15.68,35.38 15.68,69.74 z m -34.4,-571.66 -294.5,278.43 h -249.12 v -278.43 h -195.39 v 876.01 h 708.96 c 46.69,0 86.5,-5.05 119.43,-15.15 32.93,-10.11 59.64,-26.28 80.11,-48.52 20.48,-22.23 35.24,-51.01 44.28,-86.31 9.03,-35.31 13.56,-77.28 13.56,-125.91 v -52 c 0,-53.23 -5.41,-97.15 -16.22,-131.75 -10.82,-34.6 -28.74,-62.17 -53.77,-82.71 -25.03,-20.54 -56.49,-34.47 -94.35,-41.79 -37.86,-7.31 -79.19,-10.98 -124,-10.98 l 315.56,-280.89 h -254.55" /><path
+         id="path26"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="M 6675.48,4439.73 6205.2,3563.72 h 221.08 l 345.54,669.45 345.52,-669.45 h 222.51 l -472.94,876.01 h -191.43" /><path
+         id="path28"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 8780.03,3563.72 v 683.08 h -310.61 v 192.93 h 815.37 V 4246.8 h -310.6 v -683.08 h -194.16" /><path
+         id="path30"
+         style="fill:#4faeca;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 8153.9,4448.96 h 179.58 c 46.81,0 84.5,-37.69 84.5,-84.51 v -179.57 c 0,-46.82 -37.69,-84.51 -84.5,-84.51 H 8153.9 c -46.82,0 -84.51,37.69 -84.51,84.51 v 179.57 c 0,46.81 37.69,84.51 84.51,84.51" /><path
+         id="path32"
+         style="fill:#4faeca;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 7497.38,3899.62 h 179.58 c 46.82,0 84.5,-37.68 84.5,-84.5 v -179.58 c 0,-46.81 -37.68,-84.5 -84.5,-84.5 h -179.58 c -46.81,0 -84.5,37.69 -84.5,84.5 v 179.58 c 0,46.82 37.69,84.5 84.5,84.5" /><path
+         id="path34"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 7497.38,4448.96 h 179.58 c 46.82,0 84.5,-37.69 84.5,-84.51 v -179.57 c 0,-46.81 -37.68,-84.51 -84.5,-84.51 h -179.58 c -46.81,0 -84.5,37.7 -84.5,84.51 v 179.57 c 0,46.82 37.69,84.51 84.5,84.51 v 0" /><path
+         id="path36"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 8153.9,3899.62 h 179.58 c 46.81,0 84.5,-37.68 84.5,-84.5 v -179.58 c 0,-46.81 -37.69,-84.5 -84.5,-84.5 H 8153.9 c -46.82,0 -84.51,37.69 -84.51,84.5 v 179.58 c 0,46.82 37.69,84.5 84.51,84.5" /><path
+         id="path38"
+         style="fill:#5e6061;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="m 7761.46,4364.45 c 52.96,-323.25 265.94,-450.93 572.02,-464.83 l -264.09,-264.08 c -104.49,236.06 -231.81,450.63 -572.01,464.83 l 264.08,264.08" /></g></g></svg>