playbooks

home / skills / freekmurze / dotfiles / ray-skill

ray-skill skill

/config/claude/skills/ray-skill

This skill sends data to Ray for debugging and visualization by formatting and dispatching payloads to the local Ray server.

npx playbooks add skill freekmurze/dotfiles --skill ray-skill

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
7.5 KB
---
name: ray-skill
description: Use when user says "send to Ray," "show in Ray," "debug in Ray," "log to Ray," "display in Ray," or wants to visualize data, debug output, or show diagrams in the Ray desktop application.
metadata:
  author: Spatie
  tags:
    - debugging
    - logging
    - visualization
    - ray
---

# Ray Skill

## Overview

Ray is Spatie's desktop debugging application for developers. Send data directly to Ray by making HTTP requests to its local server. This is what the `ray()` PHP function does under the hood.

## Connection Details

| Setting | Default | Environment Variable |
|---------|---------|---------------------|
| Host | `localhost` | `RAY_HOST` |
| Port | `23517` | `RAY_PORT` |
| URL | `http://localhost:23517/` | - |

## Request Format

**Method:** POST
**Content-Type:** `application/json`
**User-Agent:** `Ray 1.0`

### Basic Request Structure

```json
{
  "uuid": "unique-identifier-for-this-ray-instance",
  "payloads": [
    {
      "type": "log",
      "content": { },
      "origin": {
        "file": "/path/to/file.php",
        "line_number": 42,
        "hostname": "my-machine"
      }
    }
  ],
  "meta": {
    "ray_package_version": "1.0.0"
  }
}
```

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | Unique identifier for this Ray instance. Reuse the same UUID to update an existing entry. |
| `payloads` | array | Array of payload objects to send |
| `meta` | object | Optional metadata (ray_package_version, project_name, php_version) |

### Origin Object

Every payload includes origin information:

```json
{
  "file": "/Users/dev/project/app/Controller.php",
  "line_number": 42,
  "hostname": "dev-machine"
}
```

## Payload Types

### Log (Send Values)

```json
{
  "type": "log",
  "content": {
    "values": ["Hello World", 42, {"key": "value"}]
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Custom (HTML/Text Content)

```json
{
  "type": "custom",
  "content": {
    "content": "<h1>HTML Content</h1><p>With formatting</p>",
    "label": "My Label"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Table

```json
{
  "type": "table",
  "content": {
    "values": {"name": "John", "email": "[email protected]", "age": 30},
    "label": "User Data"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Color

Set the color of the preceding log entry:

```json
{
  "type": "color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

**Available colors:** `green`, `orange`, `red`, `purple`, `blue`, `gray`

### Screen Color

Set the background color of the screen:

```json
{
  "type": "screen_color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Label

Add a label to the entry:

```json
{
  "type": "label",
  "content": {
    "label": "Important"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Size

Set the size of the entry:

```json
{
  "type": "size",
  "content": {
    "size": "lg"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

**Available sizes:** `sm`, `lg`

### Notify (Desktop Notification)

```json
{
  "type": "notify",
  "content": {
    "value": "Task completed!"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### New Screen

```json
{
  "type": "new_screen",
  "content": {
    "name": "Debug Session"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

### Measure (Timing)

```json
{
  "type": "measure",
  "content": {
    "name": "my-timer",
    "is_new_timer": true,
    "total_time": 0,
    "time_since_last_call": 0,
    "max_memory_usage_during_total_time": 0,
    "max_memory_usage_since_last_call": 0
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

For subsequent measurements, set `is_new_timer: false` and provide actual timing values.

### Simple Payloads (No Content)

These payloads only need a `type` and empty `content`:

```json
{
  "type": "separator",
  "content": {},
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
```

| Type | Purpose |
|------|---------|
| `separator` | Add visual divider |
| `clear_all` | Clear all entries |
| `hide` | Hide this entry |
| `remove` | Remove this entry |
| `confetti` | Show confetti animation |
| `show_app` | Bring Ray to foreground |
| `hide_app` | Hide Ray window |

## Combining Multiple Payloads

Send multiple payloads in one request. Use the same `uuid` to apply modifiers (color, label, size) to a log entry:

```json
{
  "uuid": "abc-123",
  "payloads": [
    {
      "type": "log",
      "content": { "values": ["Important message"] },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "color",
      "content": { "color": "red" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "label",
      "content": { "label": "ERROR" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "size",
      "content": { "size": "lg" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    }
  ],
  "meta": {}
}
```

## Example: Complete Request

Send a green, labeled log message:

```bash
curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -H "User-Agent: Ray 1.0" \
  -d '{
    "uuid": "my-unique-id-123",
    "payloads": [
      {
        "type": "log",
        "content": {
          "values": ["User logged in", {"user_id": 42, "name": "John"}]
        },
        "origin": {
          "file": "/app/AuthController.php",
          "line_number": 55,
          "hostname": "dev-server"
        }
      },
      {
        "type": "color",
        "content": { "color": "green" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      },
      {
        "type": "label",
        "content": { "label": "Auth" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      }
    ],
    "meta": {
      "project_name": "my-app"
    }
  }'
```

## Availability Check

Before sending data, you can check if Ray is running:

```
GET http://localhost:23517/_availability_check
```

Ray responds with HTTP 404 when available (the endpoint doesn't exist, but the server is running).

## Payload Type Reference

| Type | Content Fields | Purpose |
|------|----------------|---------|
| `log` | `values` (array) | Send values to Ray |
| `custom` | `content`, `label` | HTML or text content |
| `table` | `values`, `label` | Display as table |
| `color` | `color` | Set entry color |
| `screen_color` | `color` | Set screen background |
| `label` | `label` | Add label to entry |
| `size` | `size` | Set entry size (sm/lg) |
| `notify` | `value` | Desktop notification |
| `new_screen` | `name` | Create new screen |
| `measure` | `name`, `is_new_timer`, timing fields | Performance timing |
| `separator` | (empty) | Visual divider |
| `clear_all` | (empty) | Clear all entries |
| `hide` | (empty) | Hide entry |
| `remove` | (empty) | Remove entry |
| `confetti` | (empty) | Confetti animation |
| `show_app` | (empty) | Show Ray window |
| `hide_app` | (empty) | Hide Ray window |

Overview

This skill sends structured debug and visualization payloads to the Ray desktop app so you can inspect values, diagrams, and timing information outside the terminal. It provides the HTTP request format, payload types, and usage patterns needed to push logs, tables, custom HTML, and UI modifiers to Ray. Use it when you want immediate visual feedback during development or to separate debugging output from standard logs.

How this skill works

The skill constructs POST requests to Ray's local server (default http://localhost:23517/) with a JSON body containing a uuid, an array of payloads, and optional meta data. Each payload includes a type, content, and origin object (file, line_number, hostname). Modifiers such as color, label, size, and screen actions can be sent alongside logs by reusing the same uuid to modify the most recent entry.

When to use it

  • Quickly surface variable values, objects, or arrays while developing locally
  • Visualize structured data as tables or custom HTML during debugging
  • Send timed measurements and performance data to Ray for profiling
  • Mark important entries with colors, labels, or size modifiers
  • Trigger desktop notifications, confetti, or change screen background for visual alerts

Best practices

  • Reuse the same uuid to group a log entry with its modifiers (color, label, size)
  • Include origin (file, line_number, hostname) for traceability when inspecting items
  • Check Ray availability with GET /_availability_check before sending payloads
  • Batch multiple payloads in a single POST to reduce network overhead and keep related entries together
  • Use simple payload types (separator, clear_all) to manage screens and keep the UI tidy

Example use cases

  • Send a user object and mark it green with a label 'Auth' after a successful login
  • Push a table of query results to Ray for quick inspection instead of printing to console
  • Start a new debug screen for a request and measure timing across middleware using measure payloads
  • Display formatted HTML or diagrams with a custom payload to preview rich debug content
  • Trigger a desktop notify when a long-running background task finishes

FAQ

How do I change the Ray host or port?

Set RAY_HOST or RAY_PORT environment variables or target the desired host/port in the request URL (default http://localhost:23517/).

How do I apply a color and label to a log entry?

Send multiple payloads with the same uuid: first a log payload, then color, label, and optional size payloads; Ray will apply modifiers to the previous entry.

How can I confirm Ray is running before sending data?

Request GET http://localhost:23517/_availability_check; a running Ray server responds (commonly with HTTP 404) indicating the service is available.