Using Dashboards

Overview

In Metrix.Bar, all monitoring capabilities are organized into Dashboards. A Dashboard brings together your data queries, business logic, menu bar indicators, and flyout panels. There is no tedious manual canvas construction: each dashboard is fully self-contained.

Choosing a Dashboard

When you launch Metrix.Bar, the app lists your active dashboards alongside the official registry catalog, grouped by category. The app ships with the GitHub Repository dashboard built in; the other 13 official dashboards install on demand from the official registry.

• AI: Claude Code usage, Codex usage.
• Analytics: Umami, Plausible, PostHog, Rybbit, Dub short links, Sink.
• Development: GitHub repository.
• Weather: Weather.
• Finance: Crypto Price, Crypto Wallet, Stocks & ETFs.

The full index is published at metrix.bar/dashboards/index.json and browsable in the Gallery. You can also import any .bar dashboard file shared by colleagues or generated by AI agents.

Configuring Inputs

Each dashboard declares the parameters it needs to operate. When you open a dashboard that requires setup, Metrix.Bar presents a structured form:

If any required input is missing, the dashboard enters a Configuration Required state, preventing failed network calls.

The GitHub repository dashboard reads the GitHub REST API directly. Public repositories work without a token on the anonymous quota of 60 requests per hour, which covers one repository refreshed every 10 minutes; a token raises the limit and unlocks private repositories. Failed refreshes keep the last successful data and offer Retry.

For Umami, set the API endpoint and either an API key or a self-hosted Umami 2 username and password. API keys take priority; Umami Cloud requires an API key.

For Rybbit, enter https://app.rybbit.io or your self-hosted domain and a personal API key with analytics:read access. Accessible websites across your organizations load automatically; select a website in the list to view its details.

Umami and Rybbit can send system notifications when the live visitor total for visible websites exceeds a configurable threshold. In Settings → Notifications, enable alerts and enter a non-negative whole number (default: 100); press Enter or Save to apply it. Alerts are off by default. A complete fresh sample triggers one alert while the total stays above the threshold; after a complete sample falls to the threshold or below, a later rise can alert again. Invalid or failed live counts do not trigger or reset alerts. Live counts refresh every minute even while the panel is closed. Restarting the dashboard resets alert deduplication.

Managing Credentials

When entering API tokens in secret fields:

• Secrets are saved immediately into your system's secure credential store under the dashboard's ID.
• Plaintext secrets are never stored in plain configuration files or exported into .bar files.
• You can overwrite or clear a secret at any time from the dashboard configuration sheet.

Previewing Dashboards

Preview a dashboard before choosing its entrances:

• Live Data: Metrix.Bar executes the dashboard Worker and renders panels using native UI components.
• Diagnostics: If an API endpoint fails or returns unexpected data, error indicators appear directly inside the affected card without crashing the rest of the application.

Dashboard Entrances and Opening Modes

In dashboard settings, configure visual entrances, keyboard shortcuts, and opening modes independently:

• Independent Toggles & Opening Modes: Each of the five trigger sources—Menu Bar, Left Sidebar, Right Sidebar, Bottom Sidebar, and Keyboard Shortcut—has an independent toggle switch and opening mode selector (Flyout or Dialog) in dashboard settings. For example, you can configure Menu Bar to open a Flyout while Keyboard Shortcut and Right Sidebar open a Dialog. Disabling an entrance or clearing a shortcut retains its configured opening mode.
• Independent Shortcut: Keyboard Shortcut provides an independent toggle switch and opening mode selector in settings, while a dedicated Shortcut row handles key binding capture (Record) and cancellation. It operates even when all menu bar and sidebar entrances are disabled, and remains editable in error states.

Screen Sidebars are separate from the main window's navigation sidebar:

• Single Rail Expanded at a Time: Dwelling on an outer edge expands only that triggered side's rail (at most one screen and one direction rail at any time); moving to another side removes the previous rail before opening the target rail.
• Edge Trigger & Slide Motion: Screen Sidebars are dark capsules docked against the screen edge (fixed dark appearance that does not follow system light mode). Sidebars stay completely hidden until triggered flush against an edge: touching flush against the right or bottom edge (activation zones span between 25% and 75% of the display height on the left or right, or between 25% and 75% of the display width along the bottom, each 2 DIP thick) with ~100 ms dwell expands the rail. Shared seams between displays do not trigger them. Expanding slides in from the screen edge and collapsing slides out, switching instantly without animation under Reduce Motion. Dwelling anywhere within the activation hotzone on the active display and side keeps the rail open without flickering, even if the pointer is outside the short rail itself. The rail hides 300 ms after leaving the combined interactive area (activation zone, rail, tooltip, panel, connector, or entrance menu). Sidebar edge triggering and icon hover tooltips operate even when the app is in the background.
• Appearance & Content: A Sidebar shows icons only. The bottom Sidebar arranges them horizontally, scrolls horizontally when they overflow, and shows tooltips above the icons. Hover tooltips display a single line showing the core metric value, using tray title (tray.title), tray tooltip (tray.tooltip), or dashboard name in that order, without a title header line. Icons use the tray icon, dashboard icon, or a generic dashboard glyph in that order. The dashboard controls metric formatting. Sidebar windows request to appear above system bars, so the bottom Sidebar may occupy the same area as the Dock or taskbar.
• Icon Drag Reordering & Menu Bar Sync: Drag icons within any screen Sidebar while holding the primary platform modifier (Cmd on macOS, Ctrl on Windows and Linux) to reorder dashboards directly. This writes to the global dashboard order, which the home page, other Sidebars, and each category group in the main window sidebar follow. Dragging adjusts relative positions only among visible dashboards in that rail; release the modifier before letting go, or drag the icon back, to cancel. On macOS, dragging Metrix.Bar icons in the menu bar with Cmd held updates dashboard order the next time you expand a Sidebar or refresh the main window (one-way; Windows and Linux tray order is determined by the system and does not synchronize).

Dialog and Flyout presentation:

• Flyout: Opens from the entrance toward the screen interior, and upward from the bottom Sidebar. Opening a Flyout from a Sidebar icon on macOS presents a native Popover with an arrow pointing to the clicked icon (left sidebar arrow points right, right sidebar arrow points left, bottom sidebar arrow points up), keeping the sidebar expanded while the Flyout is open. Windows and Linux use arrowless flyouts.
• Translucent Scrim & Centered Presentation: Dialog covers the current display's full Bounds with a ~12% black high-transparency scrim (~40% black in High Contrast mode) and centers the dashboard content without entering a system fullscreen Space. The content card has rounded corners and shadow.
• No Close Button & 10% Margins: There is no close ("X") button. The requested content size comes from the dashboard, defaulting to 320×480 DIP. Left and right margins are each at least 10% of the display width; top and bottom margins are each at least 10% of the display height. The content area is limited to 80% of the display width and height, with oversized content scrolling internally. Dynamic content sizes do not shrink the backdrop.
• Interaction & Dismissal: Click outside the content or press Esc to close; clicks inside stay within the dashboard. If an inner overlay is open, Esc dismisses it first. Dialog hides the Sidebar; leave the edge activation area before returning to reveal it again.

Multiple entrances share the same dashboard data and panel state. A configured, available Sidebar keeps refreshing while hidden. With no available entrance, preview, or open panel, the dashboard becomes idle until needed. You can still open it from the main window or its shortcut. Right-click an entrance for actions such as refresh and settings; removing the menu bar entrance leaves any Sidebar entrances enabled.

Platform Availability

Linux support targets X11 and Wayland sessions with a working gtk-layer-shell library and protocol. On native GNOME Wayland, or where missing libraries or protocols prevent native screen positioning, Sidebar is disabled with an explanation. Dialog also requires native screen positioning and reports unavailability instead of opening as an ordinary floating window. Real-device GUI validation on Windows and Linux desktop remains pending.

Local API Automation

Metrix.Bar provides a loopback HTTP API on port 6387 for automation and agent workflows:

• Refresh: POST /v0/dashboards/:id/refresh forces an immediate data refresh cycle.
• Events: POST /v0/dashboards/:id/events/:name dispatches custom events to the dashboard Worker.
• Snapshot: GET /v0/dashboards/:id returns the live state and view tree.

Importing and Exporting .bar Files

Dashboards are stored and shared as .bar files:

• Import: Place .bar files in your Dashboards folder or create them via the local HTTP API.
• Export: Exported .bar files contain all permissions (network origins and file paths), input schemas, and JavaScript Worker code, omitting sensitive secrets to ensure safe sharing.