claude-relay: Instructions file for Codex

AGENTS.md — Agent Relay

What this is

Drop-in OpenAI & Anthropic API-compatible server that routes requests through claude -p CLI.

Quick setup

Prerequisites: claude CLI installed and on PATH, Python 3.10+, uv

# Install and run
uvx agent-relay serve

# Or from source
git clone https://github.com/npow/claude-relay.git
cd claude-relay && uv sync && uv run agent-relay serve

Default: http://0.0.0.0:8082. Override with --host / --port.

Configuring clients

OpenAI SDK (Python):

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8082/v1", api_key="unused")
response = client.chat.completions.create(
    model="sonnet", messages=[{"role": "user", "content": "Hello"}], stream=True
)

Anthropic SDK (Python):

from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:8082", api_key="unused")
response = client.messages.create(
    model="sonnet", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}]
)

LangChain:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(base_url="http://localhost:8082/v1", api_key="unused", model="sonnet")

curl:

curl http://localhost:8082/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"sonnet","messages":[{"role":"user","content":"Hello"}]}'

API endpoints

Method	Path	Description
GET	/health	Server + CLI status
GET	/v1/models	List available models
POST	/v1/chat/completions	OpenAI-compatible chat
POST	/v1/messages	Anthropic-compatible messages

All endpoints also available without /v1 prefix (e.g. /models, /chat/completions, /messages).

Models

Model	Notes
opus	Most capable
sonnet	Default if omitted
haiku	Fastest

Passed directly to claude --model.

Ignored parameters

These are silently discarded — Claude Code CLI does not expose them: