Documentation

Installation

TailStats is a native macOS menu bar app that displays real-time metrics from multiple data sources.

Card Configuration

Every card requires basic configuration regardless of which data method you use.

Data Sources

TailStats supports four ways to get data into cards:

Authentication

TailStats supports multiple authentication methods for accessing protected APIs.

Three Ways to Display Data

TailStats supports three methods for getting data into cards:

Simple Value

The simplest method — whatever your endpoint returns is displayed directly as the card value. No parsing, no extraction.

Structured Response

Build an API endpoint that returns data in TailStats format for full control over the display.

{
  "items": [ ... ],
  "columns": 2
}

{ "title": "Status", "type": "string", "value": "Online" }

{ "title": "Users", "type": "number", "value": 1234 }

{ "title": "Traffic", "type": "array", "value": [10, 25, 15, 30, 20] }

{ "title": "Storage", "type": "progress", "value": 0.75 }

Card Types (15)

TailStats supports 15 different card types for displaying your data.

{ "type": "image", "value": "https://example.com/avatar.png" }

{ "type": "message", "value": "Hello!", "displayMode": "received" }

{ "type": "map", "value": { "markers": [{ "lat": 37.7, "lng": -122.4, "label": "SF" }] } }

Display Rules

Conditional formatting engine that transforms card values based on rules. Up to 10 rules per card, 5 conditions per rule.

{
  "conditions": [
    { "source": "extractedValue", "op": "greaterThan", "value": "80" }
  ],
  "conditionMode": "all",
  "action": {
    "overrideValue": "Critical",
    "overrideColor": "red",
    "overrideIcon": "exclamationmark.triangle.fill"
  },
  "enabled": true
}

JSONPath Extraction

Extract specific values from any JSON API using JSONPath expressions. No API modifications required.

{
  "data": {
    "users": 1250,
    "revenue": 45000
  }
}

Value Formatting

Control how numeric values are displayed using format strings.

type:option:modifier

Icons

Two icon options for cross-platform support.

Common SF Symbols

Full list: SF Symbols App

Colors

Color fields (color, iconColor, menuBarBackground) accept hex colors or named colors.

Menu Bar Display macOS only

Set menuBar: true on one item to display its value in the macOS menu bar.

{
  "title": "Active Users",
  "type": "number",
  "value": 42,
  "menuBar": true,
  "menuBarBackground": "green"
}

Only the first item with menuBar: true is displayed in the menu bar.

CLI Tool

Push data to TailStats cards from the command line, scripts, or automation.

curl -fsSL https://www.tailstats.com/install | sh

tailstats push <card-id> [options]

tailstats notify --message "Hello" [options]

Local Push Server

Three ways to push data to TailStats from local scripts and services.

POST http://localhost:9876/push/<card-id>
Content-Type: application/json

{"items": [{"title": "Status", "type": "string", "value": "OK"}]}

File Watch Cards

Monitor local files and display their contents as live cards.

AI Agent Tracking

Built-in monitoring for AI coding assistants. Track usage, sessions, and costs.

MCP Support

TailStats supports the Model Context Protocol (MCP), enabling AI assistants like Claude to directly interact with your dashboard cards.

Error Handling

TailStats handles errors gracefully to keep your dashboard running.

Requirements

TailStats is a native macOS app built with SwiftUI.

Examples

{
  "items": [
    {
      "title": "Revenue",
      "subtitle": "This month",
      "type": "number",
      "value": 12450.00,
      "icon": "dollarsign.circle",
      "emoji": "💰",
      "format": "currency:USD",
      "color": "green",
      "menuBar": true
    },
    {
      "title": "Users",
      "subtitle": "Active now",
      "type": "number",
      "value": 1234,
      "icon": "person.fill",
      "emoji": "👤",
      "format": "number"
    },
    {
      "title": "CPU Usage",
      "type": "progress",
      "value": 0.65,
      "icon": "cpu",
      "emoji": "💻"
    },
    {
      "title": "Traffic",
      "subtitle": "Last 7 days",
      "type": "array",
      "value": [120, 150, 180, 140, 200, 220, 190],
      "icon": "chart.line.uptrend.xyaxis",
      "emoji": "📈"
    }
  ],
  "columns": 2
}