---
name: render
description: Render rich, interactive UIs in the browser. Use when displaying data tables, lists, or any structured data with more than 3 items. Supports buttons and table actions with real-time event streaming.
user-invocable: true
argument-hint: "[description of what to render]"
---

# AGUI - Agentic Graphical User Interface

You are an AI agent with the ability to render rich, interactive UIs in the user's browser and receive user interactions back.

## Overview

Instead of outputting ASCII tables or markdown lists, you render data visually using a component-based schema and can respond to user clicks in real-time via Server-Sent Events.

## Setup

Before rendering any UI, ensure the server is running and a browser tab is open. Use the `agui:setup` skill or run:

```bash
cd ${CLAUDE_PLUGIN_ROOT}/server && pnpm start
open http://localhost:24991/ui
```

The browser will show a loading state until you render content.

---

## MCP Tools

Use the MCP tools provided by the `agui` plugin:

### Tool: `agui-render_ui`

Renders a UI using the component schema and returns immediately. Use when you don't need user interaction.

**Input Schema:**
```json
{
  "template": "string - identifier for this view",
  "components": "array of ComponentNode"
}
```

**Component Types:**

```typescript
// Row - horizontal container
{ "type": "row", "props": { "justify": "start|center|end" }, "children": [...] }

// Button - clickable button
{ "type": "button", "props": { "id": "unique-id", "label": "Display Text" } }

// Table - data table with optional row actions
{ "type": "table", "props": { "id": "unique-id", "columns": [...], "rows": [...], "actions": [...] } }
```

**Example:**
```json
{
  "template": "user-list",
  "components": [
    {
      "type": "row",
      "props": { "justify": "end" },
      "children": [
        { "type": "button", "props": { "id": "refresh", "label": "Refresh" } }
      ]
    },
    {
      "type": "table",
      "props": {
        "id": "users",
        "columns": ["ID", "Name", "Email"],
        "rows": [
          ["1", "Alice", "alice@example.com"],
          ["2", "Bob", "bob@example.com"]
        ],
        "actions": ["Edit", "Delete"]
      }
    }
  ]
}
```

---

### Tool: `agui-render_ui_and_listen`

Renders a UI and starts listening for user interactions. **Returns immediately** - use `agui-wait_for_event` to receive events.

**Input Schema:**
```json
{
  "sessionId": "string - unique session ID",
  "buttons": [{ "id": "string", "label": "string" }],
  "table": {
    "id": "string",
    "columns": ["string"],
    "rows": [["any"]],
    "actions": ["string"]
  }
}
```

**Response:**
```json
{
  "status": "listening",
  "sessionId": "abc123",
  "message": "UI rendered. Use agui-wait_for_event to receive user interactions."
}
```

---

### Tool: `agui-wait_for_event`

Waits for the next user interaction from an active session. Call this after `agui-render_ui_and_listen`.

**Input Schema:**
```json
{
  "sessionId": "string - session ID from render_ui_and_listen",
  "timeoutMs": "number - optional, default 60000 (1 minute)"
}
```

**Response (on click):**
```json
{
  "status": "event_received",
  "event": {
    "id": "table.users.row.1.action.edit",
    "type": "click",
    "data": { "rowId": "1" }
  }
}
```

**Response (on timeout):**
```json
{
  "status": "timeout",
  "message": "No event received within 60000ms"
}
```

---

## Event ID Patterns

| Element | Pattern | Example |
|---------|---------|---------|
| Button | `btn.<id>` | `btn.refresh` |
| Table Action | `table.<tableId>.row.<rowId>.action.<action>` | `table.users.row.1.action.edit` |

---

## Interaction Flow

### Simple Render (No Interaction)
1. Call `agui-render_ui` with component schema
2. Tell user "I've displayed the data in your browser"

### Interactive Flow (Wait for User Action)
1. Call `agui-render_ui_and_listen` with a unique `sessionId`
2. Tell user "I've opened an interactive view. Click an action when ready."
3. Call `agui-wait_for_event` with the same `sessionId`
4. Parse the returned event to determine what was clicked
5. Respond accordingly
6. Optionally call `agui-wait_for_event` again for more interactions
7. Call `agui-close_session` when done

---

## Guidelines

1. **No ASCII Tables** - Always use `agui-render_ui` for data with more than 3 items
2. **Component Schema** - Build UIs by composing `row`, `button`, and `table` nodes
3. **Unique IDs** - Always provide unique `id` values for buttons and tables
4. **Session Management** - Generate unique `sessionId` for each `render_ui_and_listen` call
5. **Row as Container** - Use `row` with `children` to layout multiple components horizontally

---

## Session Cleanup

**Important:** Before ending a session or when the user is done with AGUI, you MUST ask:

> "Would you like me to stop the AGUI server running on port 24991?"

If the user confirms, terminate the server:

```bash
lsof -ti :24991 | xargs kill -9 2>/dev/null && echo "AGUI server stopped" || echo "No server running on port 24991"
```

This prevents orphaned server processes from accumulating across sessions.