# Relay

Relay is an MCP server that plugs into Claude Code (and Cursor/CodeX). It lets your AI delegate boilerplate, first drafts, tests, and mechanical refactors to free LLM providers (Groq, Gemini, OpenRouter, and more), saving your Claude tokens and running independent tasks in parallel.

**Honesty note:** This is not "unlimited free Claude." Savings depend on the task. Savings numbers are always estimated and labeled as such — never fabricated.

## Quick Start (New Interactive Wizard)

We've made setup incredibly easy. You don't even need to touch the command line.

### 1. Run the Setup Wizard
- **Windows**: Double-click on `setup.bat`
- **Mac / Linux**: Double-click on `setup.sh` (or run `./setup.sh` in terminal)

### 2. Follow the Prompts
The wizard will automatically install dependencies, compile the project, and then ask you for your API keys one by one.
- If you don't have a key for a specific provider, just press **Enter** to skip it.
- Your keys are saved securely to a local `.env` file and are never shared.

Get free API keys from:
- **Groq**: https://console.groq.com/keys (models: llama-3.1-8b-instant, llama-3.3-70b-versatile)
- **Gemini**: https://aistudio.google.com/apikey (model: gemini-2.0-flash)
- **OpenRouter**: https://openrouter.ai/keys (free models with the `:free` suffix)

### 3. Connect to your Editor
At the end of the wizard, it will print out the exact command you need to connect Relay to Claude Code or Cursor. Just copy and paste it!

## Manual / Advanced Usage

If you prefer doing things manually:

```bash
npm install          # Automatically installs and builds
npx relay init       # Starts the interactive setup wizard
```

Add keys manually:
```bash
npx relay add-api groq <YOUR_GROQ_KEY>
npx relay add-api gemini <YOUR_GEMINI_KEY>
```

Check health and diagnostics:
```bash
npx relay doctor
npx relay check
npx relay status
```

**No API key yet?** Test the whole pipeline offline with dry-run — set `RELAY_DRY_RUN=1` in `.env`, or ask Claude to call `delegate` with `dryRun: true`. It returns a clearly-labeled synthetic response without any network call.

## Troubleshooting

- **`node dist/src/index.js` fails on Windows**: Make sure you are using Node >= 20.12.0.
- **Tools don't show up in Claude**: Ensure you've run the setup wizard or `npm install` so the code is compiled.
- **Tasks fail with `ALL_MODELS_EXHAUSTED`**: Run `npx relay doctor` and `npx relay check` to see if your API keys are valid and providers are online.

## Available Tools

| Tool | Description |
|------|-------------|
| `delegate` | Send one task to a free LLM worker |
| `delegate_parallel` | Run several independent tasks concurrently |
| `delegate_chain` | Run dependent steps; each step gets the previous output as context |
| `list_models` | Show available models, health, and power scores |
| `status` | Health table (traffic lights + power + latency) + session summary |

All delegation tools accept `dryRun: true` for keyless testing.

## CLI Commands

```bash
npx relay init               # Interactive setup wizard
npx relay doctor             # Diagnose environment issues
npx relay add-api <p> <key>  # Save a provider key securely
npx relay status             # Show health & keys
npx relay check              # Live health ping
npx relay agents             # List agent roles
npx relay skills             # List skills
```

## How It Works

1. Claude splits a task into independent pieces
2. For each piece, Relay selects a healthy free model (preferring the strongest)
3. The `delegate` tool calls the provider's OpenAI-compatible API
4. Claude receives the output, reviews it, and integrates it

Claude does NOT blindly trust worker output — it always reviews before using.

## Configuration

- `relay.config.json` — provider URLs, model lists, and pre-measured power scores. You can also configure `maxTokens` here.
- `.env` — API keys (never logged, never committed)

## Development

```bash
npm run dev       # watch mode
npm run build     # compile
npm run start     # run MCP server
npm test          # build + run network-free unit tests
```