Ray

When to use

Use this skill whenever the user asks you to send something to Ray.

How to use

Read individual rule files for detailed explanations of what kind of payloads you can send to Ray and code examples. If the Ray MCP server is setup up, propose to the user to use it by default. ALWAYS propose the skill as a second option.

HTTP API

• rules/ray-local-http.md - How the Ray local HTTP server works

Payload Types

• rules/log.md - Log payload for general value logging
• rules/table.md - Table payload for key-value data
• rules/json.md - JSON string payload for structured data
• rules/text.md - Text payload for plain text with preserved whitespace
• rules/html.md - HTML payload for raw HTML content
• rules/xml.md - XML payload for formatted XML
• rules/carbon.md - Carbon payload for date/time
• rules/custom.md - Custom payload for arbitrary content with custom label
• rules/decoded-json.md - Decoded JSON payload for parsed JSON objects
• rules/file-contents.md - File contents payload for displaying file content

Action Types

• rules/action-confetti.md - Confetti action to celebrate
• rules/action-hide-app.md - Hide Ray window
• rules/action-show-app.md - Show Ray window
• rules/action-clear-all.md - Clear all logs

Agent Payload Types

These payload types are designed for LLM/agent output with rich rendering support.

• rules/agent-custom-html.md - Rich HTML with full CSS support
• rules/agent-custom-markdown.md - Rendered Markdown content
• rules/agent-custom-mermaid.md - Mermaid diagrams (flowcharts, sequence diagrams, etc.)

Clear All Action

Clears all logs from the Ray window & archives the current session to disk. Use this to start fresh with a clean log view.

When to Use

• When the user asks to clear or reset Ray logs
• Before starting a new debugging session
• To remove clutter from previous operations

Payload Structure

{
  "type": "clear_all",
  "content": [],
  "origin": {...}
}

Key points:

• Type is clear_all
• Content is always an empty array []
• No additional parameters required

curl Example

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"clear_all","content":[],"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Confetti Action

Triggers a confetti animation in the Ray application. Use this to celebrate completed tasks, successful operations, or any moment worth celebrating.

When to Use

• After completing a complex task successfully
• When a long-running operation finishes
• To celebrate milestones or achievements
• When the user explicitly requests celebration

Payload Structure

{
  "type": "confetti",
  "content": [],
  "origin": {...}
}

Key points:

• Type is confetti
• Content is always an empty array []
• No additional parameters required

curl Example

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"confetti","content":[],"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Hide App Action

Hides the Ray application window. Use this when you want to minimize or hide Ray from view.

When to Use

• When the user asks to hide or minimize Ray
• After displaying information that doesn't need to stay visible
• To reduce screen clutter

Payload Structure

{
  "type": "hide_app",
  "content": [],
  "origin": {...}
}

Key points:

• Type is hide_app
• Content is always an empty array []
• No additional parameters required

curl Example

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"hide_app","content":[],"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Show App Action

Shows the Ray application window and brings it to the foreground. Use this when you want to make Ray visible to the user.

When to Use

• When the user asks to show or open Ray
• Before sending important logs that the user should see immediately
• To bring Ray to the user's attention

Payload Structure

{
  "type": "show_app",
  "content": [],
  "origin": {...}
}

Key points:

• Type is show_app
• Content is always an empty array []
• No additional parameters required

curl Example

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"show_app","content":[],"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Agent Custom HTML Payload

The agent custom HTML payload displays fully formatted HTML content in Ray. It provides richer rendering than the standard HTML payload, with full CSS support.

When to Use

Use the agent custom HTML payload when you want to:

• Display LLM/agent output as a fully formatted HTML page
• Show rich content with CSS styling
• Create iterative updates to a log entry (carousel feature)
• Render complex layouts that benefit from full HTML/CSS support

As an agent ALWAYS prefer agent-custom-html type above rules/html.md.

Payload Structure

{
  "type": "ai_custom_html",
  "content": {
    "html": "<h1>Hello World</h1><p>Your HTML content here</p>",
    "label": "Agent Response",
    "iterationOf": "123e4567-e89b-12d3-a456-426614174000"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

Iteration Carousel

You can create iterative updates to a log entry by using the iterationOf field. This creates a carousel in Ray that allows users to navigate between different iterations.

Important: When using iterations, you must:

1. Generate and remember the UUID from the first request 2. Use that same UUID in the iterationOf field of subsequent requests

HTTP API Examples

Basic HTML

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_html","content":{"html":"<html><body><h1>Hello World</h1><p>This is <strong>styled</strong> content.</p></body></html>","label":"Agent Response"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Styled HTML with CSS

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_html","content":{"html":"<html><head><style>.card { padding: 20px; border-radius: 8px; background: #f5f5f5; } .title { color: #333; font-size: 24px; } .content { color: #666; }</style></head><body><div class=\"card\"><h1 class=\"title\">Status Report</h1><p class=\"content\">All systems operational.</p></div></body><html>","label":"Claude Response"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Table Layout

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_html","content":{"html":"<html><head><style>table { width: 100%; border-collapse: collapse; } th, td { padding: 8px; border: 1px solid #ddd; text-align: left; } th { background: #f0f0f0; }</style><head><body><table><tr><th>Name</th><th>Status</th></tr><tr><td>Task 1</td><td style=\"color: green;\">Complete</td></tr><tr><td>Task 2</td><td style=\"color: orange;\">In Progress</td></tr></table></body></html>","label":"Task Status"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Iterative Updates (Carousel)

To create a carousel of iterations, first send the initial HTML and store the UUID:

# Step 1: Generate and store the UUID for the first iteration
FIRST_UUID=$(uuidgen)
echo "Remember this UUID for iterations: $FIRST_UUID"

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$FIRST_UUID'","payloads":[{"type":"ai_custom_html","content":{"html":"<h1>Step 1</h1><p>Processing started...</p>","label":"Progress"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Then add subsequent iterations by referencing the original UUID in iterationOf:

# Step 2: Add iteration using the SAME UUID from step 1
curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_html","content":{"html":"<h1>Step 2</h1><p>Processing complete!</p>","label":"Progress","iterationOf":"'$FIRST_UUID'"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Note: The uuid field in the request body is for the new log entry. The iterationOf field must contain the UUID from the first iteration to link them together in a carousel.

MCP Tool

When using the Ray MCP server, you can also use the send_custom_html_output tool which provides additional features like iteration carousel.

Tool name: send_custom_html_output

Features

• Full CSS Support: Use inline styles or <style> tags for custom styling
• Secure Sandbox: HTML is rendered in a secure sandbox (no JavaScript)
• Iteration Carousel: Update logs in place using iterationOf (HTTP API) or appendToLogId (MCP)

Agent Custom Markdown Payload

The agent custom Markdown payload renders Markdown content with full formatting support in Ray.

When to Use

Use the agent custom Markdown payload when you want to:

• Display structured text with Markdown formatting
• Show documentation, reports, or explanations
• Render content with headings, lists, code blocks, tables, and links
• Output LLM/agent responses in a readable format

Payload Structure

{
  "type": "ai_custom_markdown",
  "content": {
    "markdown": "# Hello World\n\nThis is **bold** and this is *italic*.",
    "label": "Agent Response"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

Supported Markdown Features

• Headings (#, ##, ###, etc.)
• Bold (**text**) and _italic_ (*text*)
• Lists (ordered and unordered)
• Code blocks (fenced with ```) with syntax highlighting
• Inline code (backticks)
• Tables
• Links and images
• Blockquotes
• Horizontal rules

HTTP API Examples

Basic Markdown

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_markdown","content":{"markdown":"# Status Update\n\nEverything is working **correctly**.\n\n- Task 1: Complete\n- Task 2: In progress\n- Task 3: Pending","label":"Agent Response"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Code Documentation

```bash curl -X POST http://localhost:23517/ \ -H "Content-Type: application/json" \ -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_markdown","content":{"markdown":"## Function: calculateTotal\n\nCalculates the total price including tax.\n\n### Parameters\n\n| Name | Type | Description |\n|------|------|-------------|\n| items | array | List of items |\n| taxRate | number | Tax rate (0-1) |\n\n### Example\n\n`javascript\nconst total = calculateTotal(items, 0.08);\n`","label":"Documentation"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}' ```

Analysis Report

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_markdown","content":{"markdown":"# Code Analysis Report\n\n## Summary\nAnalyzed 15 files with 3 issues found.\n\n## Issues\n\n### 1. Unused variable\n> Line 42: `const temp` is declared but never used.\n\n### 2. Missing error handling\nThe `fetchData` function does not handle network errors.\n\n---\n\n*Generated by code analyzer*","label":"Claude Response"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

MCP Tool

When using the Ray MCP server, you can use the send_custom_markdown_output tool.

Tool name: send_custom_markdown_output

When to Use Markdown vs HTML

Agent Custom Mermaid Payload

The agent custom Mermaid payload renders Mermaid diagrams in Ray for visualizing flowcharts, sequence diagrams, and other diagram types.

When to Use

Use the agent custom Mermaid payload when you want to:

• Visualize flowcharts and process flows
• Show sequence diagrams for system interactions
• Display class diagrams for code architecture
• Render state diagrams, ER diagrams, Gantt charts, or pie charts
• Explain complex relationships visually

Payload Structure

{
  "type": "ai_custom_mermaid",
  "content": {
    "mermaid": "graph TD\n    A[Start] --> B[End]",
    "label": "Diagram"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

Supported Diagram Types

• Flowcharts (graph TD, graph LR)
• Sequence diagrams (sequenceDiagram)
• Class diagrams (classDiagram)
• State diagrams (stateDiagram-v2)
• Entity Relationship diagrams (erDiagram)
• Gantt charts (gantt)
• Pie charts (pie)
• Git graphs (gitGraph)
• Mind maps (mindmap)

HTTP API Examples

Simple Flowchart

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"graph TD\n    A[Start] --> B{Is it working?}\n    B -->|Yes| C[Great!]\n    B -->|No| D[Debug]\n    D --> B","label":"Flowchart"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Sequence Diagram

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"sequenceDiagram\n    participant Client\n    participant API\n    participant Database\n    Client->>API: POST /users\n    API->>Database: INSERT user\n    Database-->>API: Success\n    API-->>Client: 201 Created","label":"API Flow"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Class Diagram

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"classDiagram\n    class User {\n        +String name\n        +String email\n        +login()\n        +logout()\n    }\n    class Admin {\n        +manageUsers()\n    }\n    User <|-- Admin","label":"Class Diagram"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

State Diagram

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"stateDiagram-v2\n    [*] --> Idle\n    Idle --> Processing: Start\n    Processing --> Success: Complete\n    Processing --> Error: Fail\n    Error --> Idle: Reset\n    Success --> [*]","label":"State Machine"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

ER Diagram

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"erDiagram\n    USER ||--o{ ORDER : places\n    ORDER ||--|{ LINE_ITEM : contains\n    PRODUCT ||--o{ LINE_ITEM : in","label":"ER Diagram"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Pie Chart

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"ai_custom_mermaid","content":{"mermaid":"pie title Test Results\n    \"Passed\" : 85\n    \"Failed\" : 10\n    \"Skipped\" : 5","label":"Test Results"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

MCP Tool

When using the Ray MCP server, you can use the send_mermaid_diagram tool.

Tool name: send_mermaid_diagram

Tips

1. No code fences: Don't include mermaid or in the mermaid content. 2. Indentation: Use consistent indentation for readability. 3. Node IDs: Use descriptive IDs for nodes (e.g., UserAuth instead of A). 4. Labels: Add labels to connections to clarify relationships. 5. Direction: Choose appropriate direction (TD top-down, LR left-right) based on the diagram.

Mermaid Documentation

For full syntax reference, see the Mermaid documentation.

Carbon Payload

The carbon payload displays date/time information in a structured format. Named after the popular Carbon PHP library.

When to Use

Use the carbon payload when you want to:

• Display date and time values
• Show timestamps with timezone information
• Debug date-related data

Payload Structure

{
  "type": "carbon",
  "content": {
    "formatted": "2024-01-15 14:30:00",
    "timestamp": 1705329000,
    "timezone": "UTC"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• formatted: Human-readable date string (default format: Y-m-d H:i:s)
• timestamp: Unix timestamp (integer, seconds since epoch)
• timezone: Timezone name (e.g., "UTC", "America/New_York", "Europe/London")

All fields can be null if the date value is not available.

Examples

Current date/time

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"carbon","content":{"formatted":"'"$(date '+%Y-%m-%d %H:%M:%S')"'","timestamp":'$(date +%s)',"timezone":"'$(date +%Z)'"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Specific date

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"carbon","content":{"formatted":"2024-12-25 00:00:00","timestamp":1735084800,"timezone":"UTC"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

With different timezone

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"carbon","content":{"formatted":"2024-01-15 09:30:00","timestamp":1705329000,"timezone":"America/New_York"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Custom Payload

The custom payload displays arbitrary content with a custom label. No formatting is applied to the content.

When to Use

Use the custom payload when you want to:

• Display content with a specific label
• Show data that doesn't fit other payload types
• Create custom-labeled debug output

Payload Structure

{
  "type": "custom",
  "content": {
    "content": "my custom content",
    "label": "My Label"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: The content to display (passed through as-is, no formatting)
• label: Custom label for the payload (can be empty string)

Examples

Simple custom content

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"my custom content","label":"Custom"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

With descriptive label

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"Operation completed successfully","label":"Status"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Empty label

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"Just the content, no label","label":""},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Debug marker

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"Reached checkpoint A","label":"Debug"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Decoded JSON Payload

The decoded JSON payload displays parsed JSON as a structured view. Unlike the JSON string payload, the content is the actual decoded JSON object/array, not a string.

When to Use

Use the decoded JSON payload when you want to:

• Display JSON that's already parsed/decoded
• Show structured data without string escaping
• Present object/array data directly

Payload Structure

{
  "type": "custom",
  "content": {
    "content": {"key": "value", "nested": {"a": 1}},
    "label": ""
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: The decoded JSON value (object, array, or primitive) - NOT a string
• label: Always empty string ""

Important Note

The key difference from json_string payload:

• json_string: "content": {"value": "{\"key\": \"value\"}"} - value is a JSON string
• decoded_json: "content": {"content": {"key": "value"}, "label": ""} - content is the actual object

Examples

Simple object

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":{"name":"Claude","active":true},"label":""},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Nested structure

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":{"user":{"id":1,"name":"John"},"roles":["admin","user"]},"label":""},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Array data

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":[{"id":1,"name":"Item 1"},{"id":2,"name":"Item 2"}],"label":""},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

File Contents Payload

The file contents payload displays the contents of a file with the filename as the label.

When to Use

Use the file contents payload when you want to:

• Display the contents of a file
• Show configuration files
• Debug file content

Payload Structure

{
  "type": "custom",
  "content": {
    "content": "file contents here (HTML-encoded)",
    "label": "filename.txt"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: The file contents, HTML-encoded with newlines converted to <br />
• label: The filename (basename only, e.g., config.json not /path/to/config.json)

Formatting Rules

Before sending, the file contents must be formatted:

1. HTML-encode all entities using htmlentities() equivalent 2. Replace newlines with <br />

Error Handling

If the file does not exist:

• content: "File not found: '/path/to/file'"
• label: "File"

Examples

Display file contents

# Read file and send to Ray
FILE_PATH="/path/to/config.json"
FILE_NAME=$(basename "$FILE_PATH")
FILE_CONTENT=$(cat "$FILE_PATH" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g' | sed ':a;N;$!ba;s/\n/<br \/>/g')

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"'"$FILE_CONTENT"'","label":"'"$FILE_NAME"'"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Simple inline example

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"line 1<br />line 2<br />line 3","label":"example.txt"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

File not found

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"File not found: '\''/path/to/missing.txt'\''","label":"File"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

HTML Payload

The HTML payload displays raw HTML content in Ray without escaping.

When to Use

Use the HTML payload when you want to:

• Display formatted HTML content
• Show styled text with HTML tags
• Render custom HTML structures

Payload Structure

{
  "type": "custom",
  "content": {
    "content": "<h1>Hello</h1><p>This is <strong>HTML</strong></p>",
    "label": "HTML"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: Raw HTML content (no escaping applied)
• label: Always "HTML"

Examples

Simple HTML

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"<h1>Hello World</h1>","label":"HTML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Formatted content

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"<p>Status: <strong style=\"color: green;\">Success</strong></p><ul><li>Item 1</li><li>Item 2</li></ul>","label":"HTML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Code block

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"<pre><code>function hello() {\n  console.log(\"Hello\");\n}</code></pre>","label":"HTML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

JSON String Payload

The JSON string payload displays structured JSON data with syntax highlighting and collapsible sections.

When to Use

Use the JSON string payload when you want to:

• Display complex nested data structures
• Show API responses
• Present configuration objects
• Debug JSON data

Payload Structure

{
  "type": "json_string",
  "content": {
    "value": "{\"serialized\": \"json\"}"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• value: A JSON string (the JSON must be serialized/escaped as a string value)

Examples

Simple object

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"json_string","content":{"value":"{\"name\":\"Claude\",\"active\":true}"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Nested structure

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"json_string","content":{"value":"{\"user\":{\"id\":1,\"name\":\"John\"},\"permissions\":[\"read\",\"write\"]}"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

API response

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"json_string","content":{"value":"{\"status\":200,\"data\":{\"items\":[{\"id\":1,\"name\":\"Item 1\"},{\"id\":2,\"name\":\"Item 2\"}],\"total\":2}}"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Building JSON Strings

When constructing the payload, the inner JSON must be properly escaped:

# The value field contains a JSON string, so quotes must be escaped
# Original: {"key": "value"}
# Escaped:  {\"key\": \"value\"}

Log Payload

The log payload is used for general value logging. It displays one or more values in Ray.

When to Use

Use the log payload when you want to:

• Display simple values or messages
• Log multiple values at once
• Show debugging information

Payload Structure

{
  "type": "log",
  "content": {
    "values": ["value1", "value2", "..."],
    "meta": []
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• values: Array of values to display. Each value will be shown as a separate item.
• meta: Array of metadata objects. Can include {"clipboard_data": "text"} to set clipboard content.

Examples

Simple message

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"log","content":{"values":["Hello from Claude"],"meta":[]},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Multiple values

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"log","content":{"values":["Status: OK","Count: 42","Ready: true"],"meta":[]},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

With clipboard data

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"log","content":{"values":["Click to copy this text"],"meta":[{"clipboard_data":"This text will be copied to clipboard"}]},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Ray Local HTTP Server

Ray runs a local HTTP server that accepts payloads for display in the Ray desktop application.

Documentation: https://myray.app/docs/developing-ray-libraries/payload

Endpoint

POST http://localhost:23517/

IMPORTANT: If the endpoint is not working, the user might have changed their default port in the settings of Ray. In that case, ask them to provide the correct port.

Headers

Content-Type: application/json
Accept: application/json

Request Structure

{
  "uuid": "<unique-id>",
  "payloads": [
    {
      "type": "<payload-type>",
      "content": { /* payload-specific content */ },
      "origin": {
        "function_name": "<function-name>",
        "file": "<file-path>",
        "line_number": <number>,
        "hostname": "<hostname>"
      }
    }
  ],
  "meta": {}
}

Fields

All sections are mandatory when creating payloads.

uuid

A valid UUIDv4 value. This identifier is important for future modifications to the payload, such as changing its color after transmission. Use $(uuidgen) in bash to generate one.

payloads

An array containing the actual data being sent. Each payload has:

• type: The payload type (e.g., log, custom, table, json_string)
• content: Payload-specific content object for display in Ray
• origin: Source information object

origin

Captures where the ray() call originated. Ray uses this information to enable file linking functionality within the desktop app.

• function_name: The calling function (ALWAYS use "code-agent" for agent calls)
• file: The source file path or identifier (ALWAYS USE "code-agent" for agent calls)
• line_number: Line number in the source (ALWAYS use 1 as default)
• hostname: The hostname (ALWAYS call the hostname command to get the name of the machine)

meta

Metadata about the integration library. Can contain language version and Ray package version details. For Claude agent use, can be empty {}.

Supported Payload Types

• log - General value logging (see log.md)
• table - Key-value table display (see table.md)
• json_string - JSON structure display (see json.md)
• custom with label "Text" - Plain text with preserved whitespace (see text.md)
• custom with label "HTML" - Raw HTML content (see html.md)
• custom with label "XML" - Formatted XML content (see xml.md)
• carbon - Date/time display (see carbon.md)
• custom with custom label - Arbitrary content (see custom.md)
• custom with empty label - Decoded JSON (see decoded-json.md)
• custom with filename label - File contents (see file-contents.md)

Supported Action Types

Actions control Ray's behavior rather than displaying data. They all use empty content arrays [].

• confetti - Trigger confetti animation (see action-confetti.md)
• hide_app - Hide Ray window (see action-hide-app.md)
• show_app - Show Ray window (see action-show-app.md)
• clear_all - Clear all logs (see action-clear-all.md)

Basic curl Template

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"TYPE","content":{...},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Table Payload

The table payload displays key-value pairs in a structured table format.

When to Use

Use the table payload when you want to:

• Display structured data with named fields
• Show configuration or settings
• Present results with labels

Payload Structure

{
  "type": "table",
  "content": {
    "values": {
      "key1": "value1",
      "key2": "value2"
    },
    "label": "Table"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• values: Object with key-value pairs to display
• label: Display label for the table (e.g., "Table", "Results", "Config")

Examples

Simple table

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"table","content":{"values":{"name":"Claude","version":"1.0"},"label":"Info"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Results table

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"table","content":{"values":{"status":"success","items_processed":42,"errors":0},"label":"Results"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Configuration display

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"table","content":{"values":{"environment":"development","debug":true,"port":3000,"host":"localhost"},"label":"Config"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"my-computer"}}],"meta":{}}'

Text Payload

The text payload displays plain text with preserved whitespace formatting.

When to Use

Use the text payload when you want to:

• Display plain text with spaces and newlines preserved
• Show preformatted text content
• Display text that shouldn't be interpreted as HTML

Payload Structure

{
  "type": "custom",
  "content": {
    "content": "HTML-escaped text with &nbsp; for spaces and <br> for newlines",
    "label": "Text"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: The text content with HTML escaping applied
• label: Always "Text"

Formatting Rules

Before sending, the text must be formatted:

1. HTML-escape special characters (<, >, &, ", ') 2. Replace spaces with   3. Replace newlines with <br>

Examples

Simple text

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"Hello World","label":"Text"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Multi-line text

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"Line&nbsp;1<br>Line&nbsp;2<br>Line&nbsp;3","label":"Text"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Text with special characters

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"if&nbsp;(x&nbsp;&lt;&nbsp;10)&nbsp;{<br>&nbsp;&nbsp;return&nbsp;true;<br>}","label":"Text"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

XML Payload

The XML payload displays formatted XML content with proper indentation and encoding.

When to Use

Use the XML payload when you want to:

• Display XML documents
• Show API responses in XML format
• Debug XML configuration files

Payload Structure

{
  "type": "custom",
  "content": {
    "content": "&lt;root&gt;<br>&nbsp;&nbsp;&lt;child&gt;value&lt;/child&gt;<br>&lt;/root&gt;",
    "label": "XML"
  },
  "origin": {
    "function_name": "code-agent",
    "file": "code-agent",
    "line_number": 1,
    "hostname": "my-computer"
  }
}

Content Fields

• content: The XML content, formatted and encoded
• label: Always "XML"

Formatting Rules

Before sending, the XML must be formatted:

1. Pretty-print/indent the XML structure 2. HTML-encode all entities (< becomes <, > becomes >, etc.) 3. Replace newlines with <br> 4. Replace spaces with  

Examples

Simple XML

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"<root><item>value</item></root>","label":"XML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

Nested XML with indentation

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"&lt;one&gt;<br>&nbsp;&nbsp;&lt;two&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;three&gt;3&lt;/three&gt;<br>&nbsp;&nbsp;&lt;/two&gt;<br>&lt;/one&gt;","label":"XML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'

XML with attributes

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{"uuid":"'$(uuidgen)'","payloads":[{"type":"custom","content":{"content":"&lt;users&gt;<br>&nbsp;&nbsp;&lt;user&nbsp;id=&quot;1&quot;&nbsp;active=&quot;true&quot;&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;John&lt;/name&gt;<br>&nbsp;&nbsp;&lt;/user&gt;<br>&lt;/users&gt;","label":"XML"},"origin":{"function_name":"code-agent","file":"code-agent","line_number":1,"hostname":"'$(hostname)'"}}],"meta":{}}'