Documentation Index
Fetch the complete documentation index at: https://docs.raysurfer.com/llms.txt
Use this file to discover all available pages before exploring further.
Give your AI agent a persistent workspace scoped per user and org. Files, state, and context are automatically saved and restored — no setup needed.
How It Works
- You call
chat() with a query, user ID, and org ID
- Raysurfer restores the workspace — all files from prior calls for that user+org are mounted automatically
- Claude executes the task with full tool access (Read, Write, Bash, etc.)
- Raysurfer persists the workspace — any files created or modified are saved for next time
Usage
from raysurfer import AsyncRaySurfer
rs = AsyncRaySurfer()
# First call — agent creates files from scratch
response = await rs.chat(
"Create hello.py with a greet(name) function",
user="user-123",
org="acme-corp",
)
print(response.output)
print(response.changed_files) # ["hello.py"]
# Second call — agent sees hello.py already in its workspace
response = await rs.chat(
"Import greet from hello.py and create main.py",
user="user-123",
org="acme-corp",
)
print(response.workspace_files) # ["hello.py", "main.py"]
Parameters
| Parameter | Type | Default | Description |
|---|
query | string | required | The task or question |
user | string | required | User identifier (scopes the workspace) |
org | string | required | Organization identifier (scopes the workspace) |
model | string | "sonnet" | Claude model to use |
max_turns | int | 8 | Maximum agent turns per request |
Response
response = await rs.chat("Create a Flask app", user="dev-1", org="startup")
response.success # True
response.output # "I created app.py with a Flask app..."
response.changed_files # ["app.py"]
response.workspace_files # ["app.py"]
response.duration_ms # 4200
response.session_id # "sess_abc123"
Workspace Scoping
Workspaces are scoped by (org, user):
- Same user + same org = same workspace (state persists)
- Different user or different org = separate workspace
Use this to give each of your end users their own persistent agent workspace.
Multi-Turn Example
from raysurfer import AsyncRaySurfer
rs = AsyncRaySurfer()
# Turn 1: Create a project
await rs.chat("Create a Flask app with a /health endpoint",
user="dev-1", org="startup")
# Turn 2: Agent sees app.py from turn 1
await rs.chat("Add a /users endpoint that returns a list of users",
user="dev-1", org="startup")
# Turn 3: Agent sees both endpoints
await rs.chat("Add tests for all endpoints",
user="dev-1", org="startup")
Skill Document
AI agents can read the full API reference at:
https://api.raysurfer.com/skill.md
