Skill: lucal6/claw-insights-snapshot (version 1.0.0)

--- name: claw-insights-snapshot description: 'Generate visual status cards for your OpenClaw agent as PNG, SVG, or JSON. The rendered cards are designed for social sharing and mobile-friendly channels — cute, compact, and informative at a glance. Use when pushing agent status to Slack, Telegram, Discord, WhatsApp, or any chat channel, generating visual reports of token usage and session activity, extracting metrics programmatically, or scheduling periodic status updates via cron.' --- # Snapshot Status Cards **Announce at start:** "I'm generating a visual status card for your OpenClaw agent." ## What is a Snapshot? A snapshot is a server-rendered visual status card — not a browser screenshot. Powered by Satori, it renders in ~200ms with no browser dependency. The output is designed to look great in chat: compact, readable on mobile, and visually appealing enough to share. It shows token usage, session activity, error counts, and gateway health in a single glance. Formats: PNG (default), SVG, or raw JSON for programmatic use. ## REST API ```bash curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"standard","range":"6h","theme":"dark"}' \ -o snapshot.png ``` No-auth mode: start with `claw-insights start --no-auth`, then omit the Authorization header. Response includes `Content-Disposition` header with timestamped filename. ## CLI ```bash claw-insights snapshot # Save to ~/.claw-insights/snapshots/ claw-insights snapshot --quick -o status.png # Compact mobile snapshot claw-insights snapshot --format json | jq . # JSON to stdout claw-insights snapshot --dry-run # Preview parameters only ``` CLI flags: `--format`, `--detail`, `--range`, `--theme`, `--lang`, `-o <path>`, `-t <token>`, `--port`, `--quick`, `--dry-run`. Run `claw-insights snapshot --help` for full usage. ## Parameters | Field | Default (REST / CLI) | Options | Description | | -------- | ------------------------- | ----------------------------------- | ---------------------- | | `detail` | `standard` | `compact` / `standard` / `full` | Detail level | | `format` | `png` | `png` / `svg` / `json` | Output format | | `range` | `24h` (REST) / `6h` (CLI) | `30m` / `1h` / `6h` / `12h` / `24h` | Time range for metrics | | `theme` | `dark` | `dark` / `light` | Color theme | | `lang` | `en` | `en` / `zh` | Language | > **Note:** REST API and CLI have different default `range` values. REST defaults to `24h` (full day overview), CLI defaults to `6h` (quick status check). Both accept the same set of values. ### Which detail level? - **compact** — Summary numbers only (session count, total tokens, error count). Best for embedding in chat messages. - **standard** — Session list + metrics charts. Default for most use cases. - **full** — Everything: session list, all charts, event log. Best for reports and archival. ## Common Workflows ### Push status card to a channel Works with any messaging channel — Slack, Telegram, Discord, WhatsApp, etc. ```bash # 1. Generate a compact status card curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"compact","range":"6h"}' \ -o /tmp/status.png # 2. Send via your channel's tool or API # The compact detail level is optimized for mobile chat bubbles. ``` **Tips:** - `compact` — best for chat messages (summary numbers only, small image) - `standard` — best for daily check-ins (session list + charts) - `full` — best for reports and archival ### Scheduled status report ```bash # Full snapshot with 24h range curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"full","range":"24h"}' \ -o /tmp/daily-report.png ``` ### Programmatic metrics extraction ```bash # Get raw data as JSON curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"format":"json","range":"6h"}' \ -o metrics.json ``` JSON schema: See [references/json-schema.md](references/json-schema.md) ## Error Handling | Status | Cause | Fix | | ------------------ | ---------------------------- | ------------------------------------------- | | `401` | Missing or invalid token | Check Bearer token, or use `--no-auth` mode | | `502` | OpenClaw gateway not running | `openclaw gateway start` | | `500` | Internal server error | Check logs: `~/.claw-insights/logs/` | | Connection refused | claw-insights not running | `claw-insights start` |

path: references/json-schema.md
content: # Snapshot JSON Schema

When using `format: "json"`, the API returns a `SnapshotData` object instead of an image.

## SnapshotData

```typescript
interface SnapshotData {
  gateway: {
    status: 'up' | 'down' | 'connecting';
    version: string;
    uptime: string;
    cpu: number;
    memoryMB: number;
  } | null;

  channels: Array<{
    name: string | null;
    provider: string;
    connected: boolean;
    latencyMs: number | null;
  }> | null;

  timestamp: string; // ISO 8601
  range: string; // e.g. "6h"
  time: string; // Human-readable time string
  hostname: string;

  summary: {
    activeSessions: number;
    totalSessions: number;
    tokens: number;
    tokensDisplay: string; // e.g. "42.1k"
    errors: number;
    warnings: number;
    uptimePercent: number;
    totalMessages: number;
  } | null;

  tokensByModel: Array<{
    model: string; // e.g. "anthropic/claude-opus-4-5"
    modelDisplay: string; // e.g. "Claude Opus 4.5"
    tokensK: number;
    percent: number;
  }> | null;

  tokensTrend?: string; // e.g. "↑12%" or "↓5%" (⚠️ prefix when >100%)

  buckets?: Array<{
    sessions?: number;
    tokensK?: number;
    tokens?: number;
    errors?: number;
    warnings?: number;
    uptimePercent?: number;
  }> | null;

  sessions?: Array<{
    name: string;
    status: string;
    model: string;
    modelDisplay: string;
    channel: string;
    totalTokens: number;
    totalTokensDisplay: string;
    usagePercent: number;
    updatedAt: string;
    turnCount: number;
    subAgentCount: number;
    subAgents?: Array<{
      name: string;
      status: string;
      completed: boolean;
      updatedAt: string;
    }>;
  }> | null;

  recentErrors?: Array<{
    timestamp: string;
    type: string;
    module: string;
    message: string;
  }> | null;

  companionDays: number | null;
  totalConversations: number | null;

  _meta?: {
    degradedSources: string[]; // Sources that failed to load
  };
}
```

## Field Notes

| Field           | When null              | Notes                                                                                                                                           |
| --------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `gateway`       | Gateway unreachable    | `version` is the Claw Insights app version (not gateway CLI version). Includes CPU/memory of the gateway process.                               |
| `channels`      | No channels configured | Provider names: telegram, discord, slack, etc.                                                                                                  |
| `summary`       | No data for range      | `tokensDisplay` is pre-formatted (e.g. "1.2k")                                                                                                  |
| `tokensByModel` | No token data          | Sorted by usage descending, `percent` sums to 100                                                                                               |
| `sessions`      | No active sessions     | Includes sub-agent tree when `detail=full`                                                                                                      |
| `recentErrors`  | No errors in range     | Only present when `detail=standard` or `full`                                                                                                   |
| `buckets`       | No metrics data        | Time-series bins for charts. All fields optional: `sessions` (peak), `tokensK`/`tokens` (sum), `errors`/`warnings` (sum), `uptimePercent` (min) |
| `_meta`         | All sources healthy    | Lists degraded data sources for transparency                                                                                                    |

## Example Response

```json
{
  "gateway": {
    "status": "up",
    "version": "1.2.3",
    "uptime": "3d 14h",
    "cpu": 2.4,
    "memoryMB": 128
  },
  "channels": [{ "name": "main", "provider": "telegram", "connected": true, "latencyMs": 45 }],
  "timestamp": "2026-03-13T15:30:00.000Z",
  "range": "6h",
  "time": "Mar 13, 15:30",
  "hostname": "my-server",
  "summary": {
    "activeSessions": 3,
    "totalSessions": 12,
    "tokens": 42100,
    "tokensDisplay": "42.1k",
    "errors": 2,
    "warnings": 5,
    "uptimePercent": 99.8,
    "totalMessages": 156
  },
  "tokensByModel": [
    { "model": "anthropic/claude-opus-4-5", "modelDisplay": "Claude Opus 4.5", "tokensK": 28.3, "percent": 67 },
    { "model": "anthropic/claude-sonnet-4", "modelDisplay": "Claude Sonnet 4", "tokensK": 13.8, "percent": 33 }
  ],
  "tokensTrend": "↑12%",
  "companionDays": 42,
  "totalConversations": 1580
}
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)