Skip to main content

​
Installation

pip 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 claude_agent_sdk: 
# Before
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# After
from raysurfer import RaysurferClient
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    system_prompt="You are a helpful assistant.",
)

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

​
Method Mapping

Claude SDKRaysurfer
ClaudeSDKClient(options)RaysurferClient(options)
await client.query(prompt)await client.raysurfer_query(prompt)
client.receive_response()client.raysurfer_response()

​
Options

Options are passed through directly from claude_agent_sdk.ClaudeAgentOptions. All standard options work: 
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    system_prompt="You are a helpful assistant.",
    model="claude-sonnet-4-20250514",
    max_turns=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 asyncio
import os
from raysurfer import RaysurferClient
from claude_agent_sdk import ClaudeAgentOptions

os.environ["RAYSURFER_API_KEY"] = "your_api_key"

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        system_prompt="You are a helpful assistant.",
    )

    async with RaysurferClient(options) as client:
        # First run: generates and caches code
        await client.raysurfer_query("Fetch GitHub trending repos")
        async for msg in client.raysurfer_response():
            print(msg)

        # Second run: retrieves from cache (instant)
        await client.raysurfer_query("Fetch GitHub trending repos")
        async for msg in client.raysurfer_response():
            print(msg)

asyncio.run(main())

​
Without Caching

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