Skip to main content

​
Installation

npm install raysurfer

​
Setup

Set your API key: 
export RAYSURFER_API_KEY=your_api_key_here
Get your key from the dashboard.

​
Usage

Swap your client class and method names. Options come directly from @anthropic-ai/claude-agent-sdk: 
// Before
import { ClaudeSDKClient, ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

// After
import { RaysurferClient } from "raysurfer";
import { ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

const options: ClaudeAgentOptions = {
  allowedTools: ["Read", "Write", "Bash"],
  systemPrompt: "You are a helpful assistant.",
};

const client = new RaysurferClient(options);

for await (const msg of client.raysurferQuery("Generate quarterly report")) {
  console.log(msg);
}

​
Method Mapping

Claude SDKRaysurfer
new ClaudeSDKClient(options)new RaysurferClient(options)
client.query(prompt)client.raysurferQuery(prompt)

​
Options

Options are passed through directly from @anthropic-ai/claude-agent-sdk. All standard options work: 
import { ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

const options: ClaudeAgentOptions = {
  allowedTools: ["Read", "Write", "Bash"],
  systemPrompt: "You are a helpful assistant.",
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  cwd: "/path/to/working/dir",
  // ... all other ClaudeAgentOptions fields
};
No Raysurfer-specific options are needed. Caching is enabled automatically when RAYSURFER_API_KEY is set.

​
Full Example

import { RaysurferClient } from "raysurfer";
import { ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

process.env.RAYSURFER_API_KEY = "your_api_key";

const options: ClaudeAgentOptions = {
  allowedTools: ["Read", "Write", "Bash"],
  systemPrompt: "You are a helpful assistant.",
};

const client = new RaysurferClient(options);

// First run: generates and caches code
for await (const msg of client.raysurferQuery("Fetch GitHub trending repos")) {
  console.log(msg);
}

// Second run: retrieves from cache (instant)
for await (const msg of client.raysurferQuery("Fetch GitHub trending repos")) {
  console.log(msg);
}

​
Without Caching

If RAYSURFER_API_KEY is not set, RaysurferClient behaves exactly like ClaudeSDKClient — no caching, just a pass-through wrapper.