Documentation / Build Your First Dashboard
Build Your First Dashboard
Describe a dashboard to your agent or the browser Playground and get a .bar file that runs in your menu bar.
Overview
The dashboards you build are the ones that fit your work. You don't need to write the code yourself: describe what you want, review the design, and your agent writes, checks, and installs the .bar file. Choose one of two paths:
- With your agent: Claude Code, Codex, or Cursor works against the installed app, with real data and every desktop capability.
- In the Playground: try the idea in your browser with sample data, no installation needed, then download the
.barfile.
With your agent
1. Install the app and the Skill
Install Metrix.Bar and launch it. Then add the Agent Skill in your terminal or your agent's working directory:
npx skills add https://metrix.bar
If the app isn't installed yet, the Skill can help your agent pick, verify, and install the right package.
2. Connect
In Metrix.Bar, open Agent, turn on Enable local API, click Copy Prompt, and send the prompt to your agent. It carries the local address and token the agent needs. See the Agent guide for details.
3. Describe what you want
Say what to show, where the data comes from, how often it changes, and where it should appear. For example:
Put my GitHub repository's stars, open issues, and latest release in the menu bar, and show recent pull requests in the panel.
Show today's revenue from Stripe in the notch, with a chart of the last 30 days in the panel. Read the API key from a secret setting.
Make a Pomodoro timer for the menu bar: 25-minute focus, 5-minute break, a notification at each switch, and a history of today's sessions.
Include an API documentation link or a sample response when the service is less common.
4. Review the design
Before writing code, the agent reads the format reference and similar official dashboards, then proposes the menu bar value, panel layout, interactions, and empty and error states. Adjust it until it matches what you want, then confirm.
5. Let the agent build and install it
The agent writes the .bar file, validates it, runs an isolated check, installs it, and refreshes it. When the dashboard asks for a token, enter it yourself in the dashboard's settings form; it goes straight to the system credential store.
6. Keep refining
Ask for changes in plain language: "add a weekly chart", "turn red above 80%", "add a widget", "show it in the notch". The agent updates the same installation in place.
In the Playground
- Open the Playground and describe your dashboard to the built-in fx agent. It uses a default model; switch to your own OpenAI-compatible model under Custom model if you prefer.
- Review the preview. The agent edits the
.barsource andfixture.json, the sample data the preview runs on. - Edit the source yourself if you like, and click Run preview to see the change.
- Click Download .bar, then import the file in Metrix.Bar with Import .bar… and fill in its settings to use real data.
The Playground runs in a browser sandbox, so desktop capabilities such as files, Bluetooth, and notifications only work once the dashboard runs in the app.
What you can build
A dashboard is more than a number. It can call any API you allow, keep data in SQLite or IndexedDB, run WebAssembly, read system metrics and media playback, send notifications, receive email and webhooks through Inbox, and draw charts, tables, and editors as native UI. See the .bar format and components references for everything available.
Share it
Export the .bar file to share it; your secrets are never included. To publish updates for others, host a registry or share an install link.
Next steps
- Dashboard development: components, state, and libraries.
- Local API: the endpoints your agent uses.
- .bar format and components: the complete reference.