Skip to main content

​
Installation

pip install raysurfer

​
Set Your API Key

Get your API key from the dashboard and set it as an environment variable: 
export RAYSURFER_API_KEY=your_api_key_here

​
Drop-in Replacement

Raysurfer wraps the Claude Agent SDK. Swap your client and method names: 
# Before
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options) as client:
    await client.query("Generate quarterly report")
    async for msg in client.receive_response():
        print(msg)

# After
from raysurfer import RaysurferClient
from claude_agent_sdk import ClaudeAgentOptions  # Options come from Claude SDK

async with RaysurferClient(options) as client:
    await client.raysurfer_query("Generate quarterly report")
    async for msg in client.raysurfer_response():
        print(msg)

​
Key Differences

Claude SDKRaysurfer
ClaudeSDKClientRaysurferClient
client.query()client.raysurfer_query()
client.receive_response()client.raysurfer_response()
Options (ClaudeAgentOptions) come directly from claude_agent_sdk — no Raysurfer-specific options needed.

​
Verifying It Works

The simplest way to verify Raysurfer is working:
  1. First run: Execute a unique input - this generates and caches the output
  2. Second run: Run the same input again - it should return instantly from cache
The speedup vs running the same agent via Claude SDK should be significant (~30x) since pulling cached code is much faster than regenerating tokens.
1

Run your agent once

The first execution generates output normally and caches it automatically.
2

Run the same query again

The second execution retrieves from cache almost instantly.
3

Compare the times

You should see a dramatic speedup on the cached run.

​
What Gets Cached?

Raysurfer caches:
  • Code outputs from agent tool calls
  • Generated reports, templates, and documents
  • API response patterns
  • Any structured output your agent produces
Raysurfer automatically verifies and stores successful code snippets from your runs for future reuse.

​
Next Steps

Python SDK

Full Python SDK reference and examples

TypeScript SDK

Full TypeScript SDK reference and examples

How It Works

Learn about semantic matching and verified snippets