wp-agentic-writer/downloads/README.md

# Agentic Writer Local Backend

Run unlimited AI content generation on your own machine using your Claude CLI + Z.ai/Anthropic account.

## Prerequisites

Before starting, ensure you have:

- ✅ **Claude CLI** installed and configured
  - Get it: [https://claude.ai/code](https://claude.ai/code) or [https://z.ai](https://z.ai)
  - Verify: `claude --version` or `which claude`
- ✅ **Node.js 18+** installed
  - Download: [https://nodejs.org](https://nodejs.org)
  - Verify: `node --version`
- ✅ **Z.ai Coding Plan** or **Anthropic API key** configured in Claude CLI

## Quick Start

### 1. Extract Package

```bash
unzip agentic-writer-local-backend.zip
cd agentic-writer-local-backend
```

### 2. Start the Proxy

```bash
chmod +x *.sh
./start-proxy.sh
```

You'll see:

```
═══════════════════════════════════════════════════
✅ Local Backend Running!
═══════════════════════════════════════════════════

Your Configuration:
  Base URL: http://192.168.1.105:8080
  API Key:  dummy
  Model:    claude-local
```

### 3. Configure WordPress Plugin

1. Open **WP Admin** → **Agentic Writer** → **Settings** → **Local Backend**
2. Paste the **Base URL** shown above
3. API Key: `dummy`
4. Click **Test Connection** → should show ✅
5. Start generating content!

## Commands

```bash
./start-proxy.sh       # Start proxy (runs in background)
./stop-proxy.sh        # Stop proxy
./test-connection.sh   # Test if proxy responds
./get-local-ip.sh      # Find your local IP address
tail -f proxy.log      # View real-time logs
```

## Firewall Setup

The proxy needs to accept connections from your WordPress site.

### macOS

1. **System Settings** → **Network** → **Firewall**
2. Click **Options** → **Add** → Select `node`
3. Set to **Allow incoming connections**

### Linux (ufw)

```bash
sudo ufw allow 8080/tcp
sudo ufw reload
```

### Windows

1. **Windows Defender Firewall** → **Advanced Settings**
2. **Inbound Rules** → **New Rule**
3. **Port** → TCP **8080** → **Allow**

## How It Works

```
WordPress Plugin → HTTP POST → Local Proxy (port 8080)
                                     ↓
                               Spawns Claude CLI
                                     ↓
                            Returns AI Response
```

**Benefits:**
- 🆓 **Free**: Uses your existing Z.ai/Anthropic subscription
- 🔒 **Private**: Content never leaves your network
- ⚡ **Fast**: LAN latency (~50-200ms)
- 🚀 **Unlimited**: No rate limits, no token counting

## Troubleshooting

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.

### Quick Fixes

**"Connection failed" in plugin:**
```bash
# Check proxy is running
ps aux | grep claude-proxy

# Restart if needed
./stop-proxy.sh && ./start-proxy.sh
```

**"Claude CLI not found":**
```bash
# Verify Claude is installed
which claude
claude --version

# Test Claude works
echo "Hello" | claude
```

**"Wrong IP address":**
```bash
# Find your correct IP
./get-local-ip.sh

# Or manually:
# macOS:   ipconfig getifaddr en0
# Linux:   ip route get 1 | awk '{print $7}'
```

**Port 8080 already in use:**
```bash
# Find what's using it
lsof -i :8080

# Change port (edit claude-proxy.js)
PORT=9000 node claude-proxy.js
# Update plugin Base URL to: http://your-ip:9000
```

## Security Notes

- Proxy binds to `0.0.0.0` (all network interfaces) for LAN access
- No authentication by design (LAN trust model)
- All request prompts are logged to `proxy.log`
- For internet exposure, use ngrok/reverse proxy with authentication

## Environment Variables

```bash
# Use different port (default: 8080)
PORT=9000 ./start-proxy.sh

# Production mode
NODE_ENV=production

# Brave Search API (for web search capability)
export BRAVE_SEARCH_API_KEY="your-brave-api-key"
```

### Enabling Web Search (Brave Search)

To enable web search in your AI responses:

1. **Get a Brave Search API key** from [https://brave.com/search/api/](https://brave.com/search/api/)

2. **Configure it in one of these ways:**

**Option 1: Add to `.env` file (recommended for this proxy)**
```bash
echo 'BRAVE_SEARCH_API_KEY="BSA03Yj-your-key-here"' > .env
```

**Option 2: Add to Claude Code settings**
Add to `~/.claude/settings.json`:
```json
{
  "env": {
    "BRAVE_SEARCH_API_KEY": "your-key-here"
  }
}
```

**Option 3: Add to shell profile**
```bash
export BRAVE_SEARCH_API_KEY="your-key-here"
```

3. **Restart the proxy**:
```bash
./stop-proxy.sh && ./start-proxy.sh
```

When the proxy starts, you should see:
```
Brave Search:
  API Key:      CONFIGURED
```

**Note:** Web search must also be enabled in the WordPress plugin settings (Agentic Writer → Settings → General → Search → Enable). The plugin will automatically use search results when planning or researching topics.

## Support

- **Documentation**: [Plugin Docs](https://github.com/your/plugin)
- **Issues**: [GitHub Issues](https://github.com/your/plugin/issues)
- **Community**: [Discord](https://discord.gg/your-server)

## License

GPL-2.0+ - Same as WP Agentic Writer plugin