From 48df14521abbcb6307c87101cba808d475d09728 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 07:13:05 +0000 Subject: [PATCH] docs: add menu bar tray guide and stable screenpipe path --- docs.json | 1 + guides/dashboard.mdx | 4 ++ guides/menu-bar.mdx | 102 ++++++++++++++++++++++++++++++++++ quickstart.mdx | 14 ++++- reference/cli.mdx | 14 ++++- reference/troubleshooting.mdx | 12 +++- 6 files changed, 143 insertions(+), 4 deletions(-) create mode 100644 guides/menu-bar.mdx diff --git a/docs.json b/docs.json index 2645d1b..9c489cb 100644 --- a/docs.json +++ b/docs.json @@ -43,6 +43,7 @@ "guides/github-linear", "guides/mcp-setup", "guides/dashboard", + "guides/menu-bar", "guides/querying-data" ] }, diff --git a/guides/dashboard.mdx b/guides/dashboard.mdx index 67630c8..c0e6998 100644 --- a/guides/dashboard.mdx +++ b/guides/dashboard.mdx @@ -16,6 +16,10 @@ http://localhost:3000 Any browser works. You can keep it open as a background tab while you work. + + Prefer not to keep the dashboard open? Meridian also ships a macOS [menu bar tray app](/guides/menu-bar) that shows daemon health and your top app for the day directly from the system tray. + + ## Dashboard views The dashboard has three main views accessible from the navigation bar. diff --git a/guides/menu-bar.mdx b/guides/menu-bar.mdx new file mode 100644 index 0000000..aef2f11 --- /dev/null +++ b/guides/menu-bar.mdx @@ -0,0 +1,102 @@ +--- +title: "Use the Meridian Menu Bar Tray App" +sidebarTitle: "Menu bar" +description: "Check daemon health, see your top app for the day, and trigger a worklog draft from the macOS menu bar — without opening the dashboard." +--- + +Meridian ships with a lightweight macOS menu bar tray app that lives in your system tray and gives you an at-a-glance view of whether the background daemons are healthy and what you've been working on today. It's designed for the times you don't want to context-switch to the full dashboard — a quick glance at the menu bar is enough to confirm Meridian is recording and to spot when something has stopped working. + + +The tray app is **macOS only**. The Linux and Windows builds of Meridian do not include it. + + +## What the tray shows + +The tray icon reflects daemon health in real time. Open the popover to see: + +- **Daemon status** — whether the Rust ETL daemon is running, derived from the `daemon_running` field on `/api/health` (a launchd probe with a 3-second timeout). +- **Accessibility helper status** — whether the a11y helper is currently trusted by macOS. An untrusted helper means window titles aren't being captured. +- **Today's top app** — the app you've spent the most focused time in so far today, with elapsed time. +- **Pending worklog drafts** — a count of drafts waiting on your review. + +From the popover you can also: + +- Open the full dashboard at `http://localhost:3000`. +- Trigger a worklog draft for today without leaving the menu bar. +- Pause or resume the daemon. + +The tray polls `/api/health` and the activity endpoints every 60 seconds. When the daemon goes down — or comes back online — you get a macOS notification so you don't silently lose recording time. + +## Installation and auto-start + +The tray app is installed automatically by `./install.sh` and `meridian update`. It's registered as a LaunchAgent (`com.meridiona.tray`) so it starts on login alongside the rest of the stack — there's no separate command to run. + +You can verify it's loaded with: + +```bash +launchctl list | grep com.meridiona.tray +``` + +If you want to start, stop, or restart the tray independently of the other daemons: + +```bash +# Stop the tray +launchctl stop com.meridiona.tray + +# Start it again +launchctl start com.meridiona.tray +``` + +Logs are written to `~/.meridian/logs/tray.log` and `~/.meridian/logs/tray-error.log`. + +## When to use it + +Reach for the tray when you want to: + +- Confirm Meridian is still recording without breaking flow to open a browser. +- Get notified the moment the daemon stops (for example after a system update or permission revocation). +- Kick off a worklog draft quickly at the end of the day or after a focused session. + +For deeper analysis — timelines, per-session detail, the apps view — open the dashboard. The tray is intentionally minimal. + +## Troubleshooting + + + + Check that the LaunchAgent is registered and running: + + ```bash + launchctl list | grep com.meridiona.tray + ``` + + If it's missing, re-run the installer or reinstall just the tray daemon: + + ```bash + bash scripts/install-tray-daemon.sh + ``` + + Then tail the log to confirm it started: + + ```bash + tail -f ~/.meridian/logs/tray.log + ``` + + + The tray reads `daemon_running` from `/api/health`, which probes launchd for `com.meridiona.daemon`. If the UI service is down or unreachable on `http://localhost:3000`, the tray can't fetch health and falls back to a stopped state. Confirm the UI is up: + + ```bash + meridian status + curl -s http://localhost:3000/api/health + ``` + + Restart the stack with `meridian restart` if the UI service isn't running. + + + The tray polls every 60 seconds. If the popover shows stale numbers for longer than that, check the tray log for errors and confirm the dashboard is reachable: + + ```bash + tail -f ~/.meridian/logs/tray.log + curl -s http://localhost:3000/api/health | jq + ``` + + diff --git a/quickstart.mdx b/quickstart.mdx index 01272c7..992e1c5 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -45,9 +45,21 @@ This guide walks you through getting Meridian running on your machine for the fi - **Accessibility** — to read window titles and accessibility tree events - **Microphone** — to transcribe audio (optional but recommended for meeting context) + The screenpipe binary lives at a stable, user-visible path so the grants survive Node upgrades and the System Settings file picker can navigate to it without traversing hidden directories: + + ``` + ~/.meridian/bin/screenpipe + ``` + + `meridian permissions` prints this path for you. To grant Screen Recording or Accessibility, open the relevant System Settings pane, click **+**, press **⌘⇧G**, paste the path above, click **Open**, and toggle the entry on. + - For Screen Recording and Accessibility, click the **+** button in the System Settings pane, navigate to the screenpipe binary, and toggle it on. The Microphone pane works differently — screenpipe will appear there automatically after it first requests mic access. If it isn't listed yet, grant Screen Recording first, then check back. + The Microphone pane works differently — screenpipe appears there automatically after it first requests mic access. If it isn't listed yet, grant Screen Recording first, then check back. + + + **Upgrading from an older install?** Updates preserve whatever screenpipe path your launchd plist already points at, so your existing TCC grant for Screen Recording and Accessibility stays valid. Fresh installs land at `~/.meridian/bin/screenpipe`. + Immediately after the build, the installer prompts you for credentials grouped by service. Press **Enter** on any prompt to skip that variable — you can always add it later. diff --git a/reference/cli.mdx b/reference/cli.mdx index db9553e..2a1fb79 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -173,14 +173,24 @@ EDITOR=code meridian config edit meridian permissions ``` -Walks you interactively through the three macOS privacy panes that screenpipe requires: +Walks you interactively through the three macOS privacy panes that screenpipe requires. The command first prints the stable binary path you need to grant access to: -1. **Screen Recording** — opens the System Settings pane; click `+`, navigate to the screenpipe binary, add it, and toggle it on. +``` +~/.meridian/bin/screenpipe +``` + +Then it opens each pane in sequence: + +1. **Screen Recording** — opens the System Settings pane; click `+`, press `⌘⇧G`, paste the path above, click **Open**, and toggle the entry on. 2. **Accessibility** — same steps. 3. **Microphone** — screenpipe appears here only after it first requests mic access. Grant Screen Recording first if screenpipe is not listed yet. After each step the script waits for you to press Enter. Run `meridian restart` afterwards so screenpipe picks up the newly granted permissions. + +Updates preserve whatever screenpipe path your existing launchd plist points at so the macOS TCC grant stays valid. The `~/.meridian/bin/screenpipe` path is used for fresh installs and when no plist exists yet. + + Without Screen Recording permission, screenpipe cannot capture frames and Meridian will have no data to process. diff --git a/reference/troubleshooting.mdx b/reference/troubleshooting.mdx index e7a0a64..0fe2f5f 100644 --- a/reference/troubleshooting.mdx +++ b/reference/troubleshooting.mdx @@ -277,7 +277,13 @@ Run the guided permissions walkthrough: meridian permissions ``` -The command opens the Screen Recording, Accessibility, and Microphone System Settings panes in sequence and waits for you to confirm each one. After granting access, restart the stack: +The command prints the stable binary path you need to grant access to and opens the Screen Recording, Accessibility, and Microphone System Settings panes in sequence. Grant access to: + +``` +~/.meridian/bin/screenpipe +``` + +In each pane, click **+**, press **⌘⇧G**, paste that path, click **Open**, and toggle the entry on. After granting access, restart the stack: ```bash meridian restart @@ -287,6 +293,10 @@ meridian restart You must restart screenpipe after granting Screen Recording permission. The permission change does not take effect for a running process. + +Updates never rewrite the screenpipe path in your launchd plist — if you previously granted access against an older path (for example an `nvm`-versioned npm path), the existing TCC grant is preserved. Only fresh installs land at `~/.meridian/bin/screenpipe`. + +