Glance

---

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'




    Label
    com.glance.dashboard
    ProgramArguments
    
        /opt/homebrew/bin/npm
        run
        dev
    
    WorkingDirectory
    ~/.glance
    RunAtLoad
    
    KeepAlive
    
    StandardOutPath
    ~/.glance/logs/stdout.log
    StandardErrorPath
    ~/.glance/logs/stderr.log


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 
{serverData?.value}
; }",
  "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

Is data available via API that the widget can call?
├── YES → Use server_code
└── NO → Does an external service push data?
    ├── YES → Use webhook
    └── NO → Use agent_refresh (YOU collect it)

| Scenario | Fetch Type | Who Collects Data? | |----------|-----------|-------------------| | Public/authenticated API | server_code | Widget calls API at render | | External service pushes data | webhook | External service POSTs to cache | | Local CLI tools | agent_refresh | YOU (the agent) via PTY/exec | | Interactive terminals | agent_refresh | YOU (the agent) via PTY | | Computed/aggregated data | agent_refresh | YOU (the agent) on a schedule |

⚠️ agent_refresh means YOU are the data source. You set up a cron to remind yourself, then YOU collect the data using your tools (exec, PTY, browser, etc.) and POST it to the cache.

API Endpoints

Widget Definitions

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/widgets | Create widget definition | | GET | /api/widgets | List all definitions | | GET | /api/widgets/:slug | Get single definition | | PATCH | /api/widgets/:slug | Update definition | | DELETE | /api/widgets/:slug | Delete definition |

Widget Instances (Dashboard)

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/widgets/instances | Add widget to dashboard | | GET | /api/widgets/instances | List dashboard widgets | | PATCH | /api/widgets/instances/:id | Update instance (config, position) | | DELETE | /api/widgets/instances/:id | Remove from dashboard |

Credentials

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/credentials | List credentials + status | | POST | /api/credentials | Store credential | | DELETE | /api/credentials/:id | Delete credential |

Creating a Widget

Full Widget Package Structure

{
  "name": "GitHub PRs",
  "slug": "github-prs",
  "description": "Shows open pull requests",
  
  "source_code": "function Widget({ serverData }) { ... }",
  "default_size": { "w": 2, "h": 2 },
  "min_size": { "w": 1, "h": 1 },
  "refresh_interval": 300,
  
  "credentials": [
    {
      "id": "github",
      "type": "api_key",
      "name": "GitHub Personal Access Token",
      "description": "Token with repo scope",
      "obtain_url": "https://github.com/settings/tokens"
    }
  ],
  
  "fetch": {
    "type": "agent_refresh",
    "schedule": "*/5 * * * *",
    "instructions": "Fetch open PRs from GitHub API and POST to cache endpoint",
    "expected_freshness_seconds": 300,
    "max_staleness_seconds": 900
  },
  
  "cache": {
    "ttl_seconds": 300,
    "max_staleness_seconds": 900,
    "storage": "sqlite",
    "on_error": "use_stale"
  },
  
  "setup": {
    "description": "Configure GitHub token",
    "agent_skill": "Store GitHub PAT via /api/credentials",
    "verification": {
      "type": "cache_populated",
      "target": "github-prs"
    },
    "idempotent": true
  }
}

Fetch Types

| Type | When to Use | Data Flow | |------|-------------|-----------| | server_code | Widget can call API directly | Widget → server_code → API | | agent_refresh | Agent must fetch/compute data | Agent → POST /cache → Widget reads | | webhook | External service pushes data | External → POST /cache → Widget reads |

Most widgets should use agent_refresh — the agent fetches data on a schedule and pushes to the cache endpoint.

Step 1: Create Widget Definition

POST /api/widgets
Content-Type: application/json
{
  "name": "GitHub PRs",
  "slug": "github-prs",
  "description": "Shows open pull requests",
  "source_code": "function Widget({ serverData }) { ... }",
  "default_size": { "w": 2, "h": 2 },
  "credentials": [...],
  "fetch": { "type": "agent_refresh", "schedule": "*/5 * * * *", ... },
  "data_schema": {
    "type": "object",
    "properties": {
      "prs": { "type": "array", "description": "List of PR objects" },
      "fetchedAt": { "type": "string", "format": "date-time" }
    },
    "required": ["prs", "fetchedAt"]
  },
  "cache": { "ttl_seconds": 300, ... }
}

data_schema (REQUIRED) defines the data contract between the fetcher and the widget. Cache POSTs are validated against it — malformed data returns 400.

> ⚠️ Always include data_schema when creating widgets. This ensures: > 1. Data validation on cache POSTs (400 on schema mismatch) > 2. Clear documentation of expected data structure > 3. AI agents know the exact format to produce

Step 2: Add to Dashboard

POST /api/widgets/instances
Content-Type: application/json
{
  "type": "custom",
  "title": "GitHub PRs",
  "custom_widget_id": "cw_abc123",
  "config": { "owner": "acfranzen", "repo": "libra" }
}

Step 3: Populate Cache (for agent_refresh)

POST /api/widgets/github-prs/cache
Content-Type: application/json
{
  "data": {
    "prs": [...],
    "fetchedAt": "2026-02-03T14:00:00Z"
  }
}

⚠️ If the widget has a dataSchema, the cache endpoint validates your data against it. Bad data returns 400 with details. Always check the widget's schema before POSTing:

GET /api/widgets/github-prs
Response includes dataSchema showing required fields and types

Step 4: Browser Verification (REQUIRED)

⚠️ MANDATORY: Every widget creation and refresh MUST end with browser verification.

Never consider a widget "done" until you've visually confirmed it renders correctly on the dashboard.

// REQUIRED: Open dashboard and verify widget renders
browser({ 
  action: 'open', 
  targetUrl: 'http://localhost:3333',
  profile: 'openclaw'
});
// Take a snapshot and check the widget
browser({ action: 'snapshot' });
// Look for:
// 1. Widget is visible on the dashboard
// 2. Shows actual data, NOT "Waiting for data..." or loading spinner
// 3. Data values match what was pushed to cache
// 4. No error messages displayed
// 5. Layout looks correct (not broken/overlapping)

Verification checklist (must ALL be true):

[ ] Widget visible on dashboard grid

[ ] Title displays correctly

[ ] Data renders (not stuck on loading)

[ ] Values match cached data

[ ] No error states or broken layouts

[ ] "Updated X ago" footer shows recent timestamp

Common issues and fixes: | Symptom | Cause | Fix | |---------|-------|-----| | "Waiting for data..." | Cache empty | POST data to /api/widgets/{slug}/cache | | Widget not visible | Not added to dashboard | POST /api/widgets/instances | | Wrong/old data | Slug mismatch | Check slug matches between definition and cache POST | | Broken layout | Bad JSX in source_code | Check widget code for syntax errors | | "No data" after POST | Schema validation failed | Check data matches data_schema |

If verification fails, fix the issue before reporting success.

Widget Code Template (agent_refresh)

For agent_refresh widgets, use serverData prop (NOT useData hook):

function Widget({ serverData }) {
  const data = serverData;
  const loading = !serverData;
  const error = serverData?.error;
  
  if (loading) return ;
  if (error) return ;
  
  // NOTE: Do NOT wrap in  - the framework wrapper (CustomWidgetWrapper) 
  // already provides the outer card with title, refresh button, and footer.
  // Just render your content directly.
  return (
    

       ({
        title: pr.title,
        subtitle: #${pr.number} by ${pr.author},
        badge: pr.state
      })) || []} />
    
  );
}

Important: The widget wrapper (CustomWidgetWrapper) provides:

Outer container with header (widget title)

Refresh button and "Updated X ago" footer

Loading/error states

Your widget code should just render the content — no Card, no CardHeader, no footer.

Key difference: agent_refresh widgets receive data via serverData prop, NOT by calling useData(). The agent pushes data to /api/widgets/{slug}/cache.

Server Code (Legacy Alternative)

Prefer agent_refresh over server_code. Only use server_code when the widget MUST execute code at render time (rare).

// Only for fetch.type = "server_code" widgets
const token = await getCredential('github');
const response = await fetch('https://api.github.com/repos/owner/repo/pulls', {
  headers: { 'Authorization': Bearer ${token} }
});
return await response.json();

Available: fetch, getCredential(provider), params, console Blocked: require, eval, fs, process, global

Agent Refresh Contract

⚠️ CRITICAL: For agent_refresh widgets, YOU (the OpenClaw agent) are the data collector.

This is NOT an external API or service. YOU must: 1. Set up a cron job to remind yourself to collect data on a schedule 2. Use your own tools (PTY, exec, browser, etc.) to gather the data 3. Parse the output into structured JSON 4. POST to the cache endpoint so the widget can display it

The Pattern

┌─────────────────────────────────────────────────────────────┐
│  Cron fires → Agent wakes up → Agent collects data →        │
│  Agent POSTs to /cache → Widget displays fresh data         │
└─────────────────────────────────────────────────────────────┘

Step-by-Step for agent_refresh Widgets

1. Create the widget with fetch.type = "agent_refresh" and detailed fetch.instructions 2. Set up a cron job targeting YOUR main session (message is just the slug):

   cron.add({
     name: "Widget: My Data Refresh",
     schedule: { kind: "cron", expr: "*/15 * * * *" },
     payload: { 
       kind: "systemEvent", 
       text: "⚡ WIDGET REFRESH: my-widget"  // Just the slug!
     },
     sessionTarget: "main"  // Reminds YOU, not an isolated session
   })
   

3. When you receive the refresh message, look up fetch.instructions from the DB and spawn a subagent:

   // Parse slug from message
   const slug = message.replace('⚡ WIDGET REFRESH:', '').trim();
   // Query widget's fetch.instructions
   const widget = db.query('SELECT fetch FROM custom_widgets WHERE slug = ?', slug);
   // Spawn subagent with the instructions
   sessions_spawn({ task: widget.fetch.instructions, model: 'haiku' });
   

4. The subagent collects the data using your tools: - exec for shell commands - PTY for interactive CLI tools (like claude /status) - browser for web scraping - API calls via web_fetch 4. POST the data to the cache:

   POST /api/widgets/{slug}/cache
   Content-Type: application/json
   
   {
     "data": {
       "myValue": 42,
       "fetchedAt": "2026-02-03T18:30:00.000Z"
     }
   }
   

Writing Excellent fetch.instructions

The fetch.instructions field is the single source of truth for how to collect widget data. Write them clearly so any subagent can follow them.

Required sections:

## Data Collection
Exact commands to run with full paths and flags.
Include PTY requirements if interactive.
Data Transformation
Exact JSON structure expected.
Include field descriptions and examples.
Cache Update
Full URL, required headers, body format.
Browser Verification
Confirm the widget renders correctly.

Good example:

## Data Collection

bash gog gmail search "in:inbox" --json

Data Transformation
Take first 5-8 emails, generate AI summary (3-5 words) for each:

json { "emails": [{"id": "...", "from": "...", "subject": "...", "summary": "AI summary here", "unread": true}], "fetchedAt": "ISO timestamp" }

Cache Update
POST to: http://localhost:3333/api/widgets/recent-emails/cache
Header: Origin: http://localhost:3333
Body: { "data":