# Troubleshooting Guide

Common issues and solutions for Agentic Writer Local Backend.

## Connection Issues

### "Connection timeout" in Plugin

**Symptoms:**
- Plugin shows "Connection timeout" error
- Test connection fails

**Solutions:**

1. **Check proxy is running:**
   ```bash
   ps aux | grep claude-proxy
   ```
   
2. **Restart proxy:**
   ```bash
   ./stop-proxy.sh
   ./start-proxy.sh
   ```

3. **Check logs:**
   ```bash
   tail -f proxy.log
   ```

4. **Verify IP address:**
   ```bash
   ./get-local-ip.sh
   ```

### "Connection refused"

**Cause:** Proxy not running or wrong IP

**Solutions:**

1. **Start proxy:**
   ```bash
   ./start-proxy.sh
   ```

2. **Check firewall:**
   - macOS: System Settings → Network → Firewall → Allow Node.js
   - Linux: `sudo ufw allow 8080/tcp`
   - Windows: Defender Firewall → Allow port 8080

3. **Test locally first:**
   ```bash
   curl http://localhost:8080/ping
   # Should return: pong
   ```

## Claude CLI Issues

### "Claude CLI not found"

**Verify installation:**
```bash
which claude
# macOS: /opt/homebrew/bin/claude or /usr/local/bin/claude
# Linux: ~/.local/bin/claude or /usr/bin/claude
```

**Fix PATH:**
```bash
# Add to ~/.zshrc or ~/.bashrc
export PATH="/opt/homebrew/bin:$PATH"
source ~/.zshrc
```

**Reinstall Claude CLI:**
- Visit: [https://claude.ai/code](https://claude.ai/code)
- Follow installation instructions

### "No response from Claude"

**Test Claude manually:**
```bash
echo "Hello, reply with: Test successful" | claude
```

**Check authentication:**
```bash
claude --version
# Should show version and auth status
```

**Reconfigure Claude:**
- Check Z.ai account: [https://z.ai](https://z.ai)
- Or Anthropic API key setup

## Network Issues

### Wrong IP Address Detected

**Find correct IP:**
```bash
# macOS
ipconfig getifaddr en0    # WiFi
ipconfig getifaddr en1    # Ethernet

# Linux
ip route get 1 | awk '{print $7}'
hostname -I

# Windows
ipconfig
# Look for "IPv4 Address" under active adapter
```

**Update plugin settings:**
- Use the correct IP in Base URL: `http://CORRECT-IP:8080`

### Port 8080 Already in Use

**Find what's using it:**
```bash
lsof -i :8080
# or
netstat -anp | grep 8080
```

**Change port:**

1. Edit `claude-proxy.js`:
   ```javascript
   const PORT = process.env.PORT || 9000; // Change 8080 to 9000
   ```

2. Restart proxy:
   ```bash
   ./stop-proxy.sh
   PORT=9000 ./start-proxy.sh
   ```

3. Update plugin Base URL: `http://your-ip:9000`

## Performance Issues

### Slow Response Times

**Normal latency:**
- Local network: 50-200ms
- Claude CLI processing: 2-30 seconds depending on prompt

**If consistently slow:**

1. **Check network:**
   ```bash
   ping 192.168.1.105  # Your proxy IP
   ```

2. **Monitor logs:**
   ```bash
   tail -f proxy.log
   ```

3. **Check machine resources:**
   - CPU usage: Claude CLI is CPU-intensive
   - Memory: Ensure sufficient RAM available

### Proxy Crashes

**Check logs:**
```bash
cat proxy.log | tail -50
```

**Common causes:**
- Out of memory: Close other applications
- Claude CLI timeout: Increase timeout in `claude-proxy.js`
- Malformed requests: Check plugin version compatibility

**Restart with clean state:**
```bash
./stop-proxy.sh
rm proxy.log
./start-proxy.sh
```

## Plugin Integration Issues

### "Invalid response format"

**Cause:** Claude response doesn't match expected JSON format

**Debug:**
1. Check `proxy.log` for actual Claude output
2. Test manually:
   ```bash
   curl -X POST http://localhost:8080/v1/messages \
     -H "Content-Type: application/json" \
     -d '{"messages":[{"role":"user","content":"Hello"}]}'
   ```

3. Update Claude CLI if outdated:
   ```bash
   claude --version
   # Upgrade if needed
   ```

### Cost Tracking Shows $0

**Expected behavior:** Local backend is free, plugin should show `$0.00 (Local)`

**If concerned:**
- This is correct - local backend has no API costs
- Dashboard should show "X requests local (free)"

## Advanced Troubleshooting

### Enable Debug Logging

Edit `claude-proxy.js`:
```javascript
const DEBUG = true; // Add at top of file

// In /v1/messages handler:
if (DEBUG) {
    console.log('Full request:', JSON.stringify(req.body, null, 2));
    console.log('Full response:', output);
}
```

### Test with curl

**Ping:**
```bash
curl http://localhost:8080/ping
# Expected: pong
```

**Inference:**
```bash
curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Reply with: Test successful"}
    ]
  }'
```

**Expected response:**
```json
{
  "id": "local-1234567890",
  "object": "chat.completion",
  "model": "claude-local",
  "choices": [{
    "message": {
      "content": "Test successful"
    }
  }]
}
```

### Permissions Issues (macOS)

**Make scripts executable:**
```bash
chmod +x start-proxy.sh stop-proxy.sh test-connection.sh get-local-ip.sh
```

**If "permission denied":**
```bash
# Check file permissions
ls -la *.sh

# Reset if needed
chmod 755 *.sh
```

## Still Having Issues?

1. **Check system requirements:**
   - Node.js 18+: `node --version`
   - Claude CLI installed: `which claude`
   - Sufficient disk space: `df -h`

2. **Collect diagnostic info:**
   ```bash
   echo "Node version:" $(node --version)
   echo "Claude path:" $(which claude)
   echo "Local IP:" $(./get-local-ip.sh)
   echo "Proxy status:" $(ps aux | grep claude-proxy)
   tail -20 proxy.log
   ```

3. **Reset everything:**
   ```bash
   ./stop-proxy.sh
   rm -rf node_modules proxy.log proxy.pid
   npm install
   ./start-proxy.sh
   ```

4. **Get help:**
   - GitHub Issues: [Report Bug](https://github.com/your/plugin/issues)
   - Discord Community: [Join Chat](https://discord.gg/your-server)
   - Include: OS, Node version, Claude CLI version, error logs

## Environment-Specific Notes

### macOS

- Default Claude path: `/opt/homebrew/bin/claude`
- Firewall: System Settings → Network → Firewall
- IP detection: `ipconfig getifaddr en0`

### Linux

- Default Claude path: `~/.local/bin/claude`
- Firewall: `sudo ufw allow 8080/tcp`
- IP detection: `ip route get 1 | awk '{print $7}'`

### Windows

- Claude path varies, check `where claude`
- Firewall: Windows Defender → Allow port 8080
- IP detection: `ipconfig` (look for IPv4)
- Scripts: Use Git Bash or WSL to run `.sh` scripts

## Security Best Practices

1. **LAN only:** Don't expose proxy to internet without authentication
2. **Firewall:** Restrict to specific IPs if on shared network
3. **Logs:** `proxy.log` contains all prompts - review periodically
4. **Updates:** Keep Node.js and Claude CLI updated

---

**Last Updated:** 2025-02-27  
**Version:** 1.0.0