scarf/scarf/docs/DASHBOARD_SCHEMA.md

Scarf Project Dashboard Schema

Scarf can render project dashboards from a JSON file. Place a dashboard.json file at .scarf/dashboard.json in your project root, and register the project in Scarf.

Registration

Projects are registered in ~/.hermes/scarf/projects.json:

{
  "projects": [
    { "name": "my-project", "path": "/path/to/my-project" }
  ]
}

You can also add projects from the Scarf UI via the Projects section.

Dashboard File

Create .scarf/dashboard.json in your project root:

{
  "version": 1,
  "title": "My Project",
  "description": "Optional description",
  "updatedAt": "2026-03-31T14:00:00Z",
  "sections": [
    {
      "title": "Section Name",
      "columns": 3,
      "widgets": []
    }
  ]
}

Widget Types

stat — Key metric display

{
  "type": "stat",
  "title": "Test Coverage",
  "value": "87.3%",
  "icon": "checkmark.shield",
  "color": "green",
  "subtitle": "+2.1% from last week"
}

• value: String or number
• icon: SF Symbol name (optional)
• color: red, orange, yellow, green, blue, purple, pink, teal, indigo, mint, brown, gray (optional)
• subtitle: Secondary text (optional)

progress — Progress bar

{
  "type": "progress",
  "title": "Sprint Progress",
  "value": 0.73,
  "label": "73% complete",
  "color": "blue"
}

• value: Number between 0.0 and 1.0
• label: Text below the bar (optional)
• color: Named color (optional)

text — Rich text block

{
  "type": "text",
  "title": "Release Notes",
  "content": "**v2.4.1** — Fixed auth timeout\n\n- Bug fix for session handling",
  "format": "markdown"
}

• content: Text content
• format: "markdown" or "plain" (default: plain)

table — Data table

{
  "type": "table",
  "title": "Recent Deploys",
  "columns": ["Date", "Env", "Status"],
  "rows": [
    ["Mar 30", "prod", "success"],
    ["Mar 29", "staging", "success"]
  ]
}

chart — Line, bar, or pie chart

{
  "type": "chart",
  "title": "Tests Over Time",
  "chartType": "line",
  "series": [
    {
      "name": "Passing",
      "color": "green",
      "data": [
        { "x": "Mon", "y": 142 },
        { "x": "Tue", "y": 145 }
      ]
    }
  ]
}

• chartType: "line", "bar", or "pie"
• series[].color: Named color (optional)
• For pie charts, each series becomes a slice

list — Checklist

{
  "type": "list",
  "title": "TODO Items",
  "icon": "checklist",
  "items": [
    { "text": "Write tests", "status": "done" },
    { "text": "Update docs", "status": "active" },
    { "text": "Deploy", "status": "pending" }
  ]
}

• status: "done" (checkmark), "active" (filled circle), "pending" (empty circle)

webview — Embedded web browser

{
  "type": "webview",
  "title": "Project Dashboard",
  "url": "http://localhost:8000",
  "height": 500
}

• url: Any URL — local servers, file paths, or remote pages
• height: Height in points (optional, default: 400)

When a dashboard includes a webview widget, Scarf adds a tabbed interface: Dashboard shows all normal widgets, Site displays the web content full-canvas. The webview widget is automatically filtered out of the Dashboard tab's grid layout.

Agent Instructions

To have your Hermes agent generate a dashboard, include these instructions:

Analyze the project and create a .scarf/dashboard.json file with relevant metrics, status indicators, and visualizations. Use the Scarf dashboard schema with sections containing stat, progress, text, table, chart, list, and webview widgets. Register the project in ~/.hermes/scarf/projects.json if not already registered.

The agent can update the dashboard file at any time — Scarf watches for changes and re-renders automatically.