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:

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

Add keys manually:

npx relay add-api groq <YOUR_GROQ_KEY>
npx relay add-api gemini <YOUR_GEMINI_KEY>

Check health and diagnostics:

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

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

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