--- name: glance description: "Create, update, and manage Glance dashboard widgets. Use when user wants to: add something to their dashboard, create a widget, track data visually, show metrics/stats, display API data, or monitor usage." metadata: openclaw: emoji: "🖥️" homepage: "https://github.com/acfranzen/glance" requires: env: ["GLANCE_URL"] bins: ["curl"] primaryEnv: GLANCE_URL ---

Glance

AI-extensible personal dashboard. Create custom widgets with natural language — the AI handles data collection.

Features

• Custom Widgets — Create widgets via AI with auto-generated JSX
• Agent Refresh — AI collects data on schedule and pushes to cache
• Dashboard Export/Import — Share widget configurations
• Credential Management — Secure API key storage
• Real-time Updates — Webhook-triggered instant refreshes

Quick Start

# Navigate to skill directory (if installed via ClawHub)
cd "$(clawhub list | grep glance | awk '{print $2}')"

# Or clone directly
git clone https://github.com/acfranzen/glance ~/.glance
cd ~/.glance

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your settings

# Start development server
npm run dev

# Or build and start production
npm run build && npm start

Dashboard runs at http://localhost:3333

Configuration

Edit .env.local:

# Server
PORT=3333
AUTH_TOKEN=your-secret-token        # Optional: Bearer token auth

# OpenClaw Integration (for instant widget refresh)
OPENCLAW_GATEWAY_URL=https://localhost:18789
OPENCLAW_TOKEN=your-gateway-token

# Database
DATABASE_PATH=./data/glance.db      # SQLite database location

Service Installation (macOS)

# Create launchd plist
cat > ~/Library/LaunchAgents/com.glance.dashboard.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.glance.dashboard</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/npm</string>
        <string>run</string>
        <string>dev</string>
    </array>
    <key>WorkingDirectory</key>
    <string>~/.glance</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>~/.glance/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>~/.glance/logs/stderr.log</string>
</dict>
</plist>
EOF

# Load service
mkdir -p ~/.glance/logs
launchctl load ~/Library/LaunchAgents/com.glance.dashboard.plist

# Service commands
launchctl start com.glance.dashboard
launchctl stop com.glance.dashboard
launchctl unload ~/Library/LaunchAgents/com.glance.dashboard.plist

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 3333 | | AUTH_TOKEN | Bearer token for API auth | — | | DATABASE_PATH | SQLite database path | ./data/glance.db | | OPENCLAW_GATEWAY_URL | OpenClaw gateway for webhooks | — | | OPENCLAW_TOKEN | OpenClaw auth token | — |

Requirements

• Node.js 20+
• npm or pnpm
• SQLite (bundled)

---

Widget Skill

Create and manage dashboard widgets. Most widgets use agent_refresh — you collect the data.

Quick Start

# Check Glance is running (list widgets)
curl -s -H "Origin: $GLANCE_URL" "$GLANCE_URL/api/widgets" | jq '.custom_widgets[].slug'

# Auth note: Local requests with Origin header bypass Bearer token auth
# For external access, use: -H "Authorization: Bearer $GLANCE_TOKEN"

# Refresh a widget (look up instructions, collect data, POST to cache)
sqlite3 $GLANCE_DATA/glance.db "SELECT json_extract(fetch, '$.instructions') FROM custom_widgets WHERE slug = 'my-widget'"
# Follow the instructions, then:
curl -X POST "$GLANCE_URL/api/widgets/my-widget/cache" \
  -H "Content-Type: application/json" \
  -H "Origin: $GLANCE_URL" \
  -d '{"data": {"value": 42, "fetchedAt": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}}'

# Verify in browser
browser action:open targetUrl:"$GLANCE_URL"

AI Structured Output Generation (REQUIRED)

When generating widget definitions, use the JSON Schema at docs/schemas/widget-schema.json with your AI model's structured output mode:

• Anthropic: Use tool_use with the schema
• OpenAI: Use response_format: { type: "json_schema", schema }

The schema enforces all required fields at generation time — malformed widgets cannot be produced.

Required Fields Checklist

Every widget MUST have these fields (the schema enforces them):

| Field | Type | Notes | |-------|------|-------| | name | string | Non-empty, human-readable | | slug | string | Lowercase kebab-case (my-widget) | | source_code | string | Valid JSX with Widget function | | default_size | { w: 1-12, h: 1-20 } | Grid units | | min_size | { w: 1-12, h: 1-20 } | Cannot resize smaller | | fetch.type | enum | "server_code" \| "webhook" \| "agent_refresh" | | fetch.instructions | string | REQUIRED if type is agent_refresh | | fetch.schedule | string | REQUIRED if type is agent_refresh (cron) | | data_schema.type | "object" | Always object | | data_schema.properties | object | Define each field | | data_schema.required | array | MUST include "fetchedAt" | | credentials | array | Use [] if none needed |

Example: Minimal Valid Widget

{
  "name": "My Widget",
  "slug": "my-widget",
  "source_code": "function Widget({ serverData }) { return <div>{serverData?.value}</div>; }",
  "default_size": { "w": 2, "h": 2 },
  "min_size": { "w": 1, "h": 1 },
  "fetch": {
    "type": "agent_refresh",
    "schedule": "*/15 * * * *",
    "instructions": "## Data Collection\nCollect the data...\n\n## Cache Update\nPOST to /api/widgets/my-widget/cache"
  },
  "data_schema": {
    "type": "object",
    "properties": {
      "value": { "type": "number" },
      "fetchedAt": { "type": "string", "format": "date-time" }
    },
    "required": ["value", "fetchedAt"]
  },
  "credentials": []
}

---

⚠️ Widget Creation Checklist (MANDATORY)

Every widget must complete ALL steps before being considered done:

□ Step 1: Create widget definition (POST /api/widgets)
    - source_code with Widget function
    - data_schema (REQUIRED for validation)
    - fetch config (type + instructions for agent_refresh)
    
□ Step 2: Add to dashboard (POST /api/widgets/instances)
    - custom_widget_id matches definition
    - title and config set
    
□ Step 3: Populate cache (for agent_refresh widgets)
    - Data matches data_schema exactly
    - Includes fetchedAt timestamp
    
□ Step 4: Set up cron job (for agent_refresh widgets)
    - Simple message: "⚡ WIDGET REFRESH: {slug}"
    - Appropriate schedule (*/15 or */30 typically)
    
□ Step 5: BROWSER VERIFICATION (MANDATORY)
    - Open http://localhost:3333
    - Widget is visible on dashboard
    - Shows actual data (not loading spinner)
    - Data values match what was cached
    - No errors or broken layouts
    
⛔ DO NOT report widget as complete until Step 5 passes!

Quick Reference

• Full SDK docs: See docs/widget-sdk.md in the Glance repo
• Component list: See references/components.md

Widget Package Structure

Widget Package
├── meta (name, slug, description, author, version)
├── widget (source_code, default_size, min_size)
├── fetch (server_code | webhook | agent_refresh)
├── dataSchema? (JSON Schema for cached data - validates on POST)
├── cache (ttl, staleness, fallback)
├── credentials[] (API keys, local software requirements)
├── config_schema? (user options)
└── error? (retry, fallback, timeout)

Fetch Type Decision Tree

...