← Plugins

Paseo Tray

See every running, finished, and needs-input Paseo agent in your macOS menu bar, and jump straight to the one that needs you.

$ paseo plugin add romejiang/paseo-tray
Report a bug
romejiangSidebar15installs6a7be658be5bSource
Paseo Tray screenshot 1Paseo Tray screenshot 2Paseo Tray screenshot 3Paseo Tray screenshot 4Paseo Tray screenshot 5

Paseo Tray puts your Paseo agents in the macOS menu bar, so you can see what is running, what finished, and what is waiting for you without switching windows. It has two parts:

  • A native menu bar app (separate Swift application, signed and notarized) that connects to your local Paseo daemon and shows live counts.
  • This plugin, which mirrors the same information inside Paseo: a sidebar entry, a full agent screen, and the settings the tray app reads.

The tray app works without the plugin. The plugin adds the in-app view and a place to configure the tray.

What the menu bar shows

The menu bar title is the summary:

TitleMeaning
▶ nAgents currently running
✓ nFinished agents you have not looked at yet
! nAgents that need input or failed (shown in red)
–Offline, password required, or unsupported connection (icon dimmed)
Icon onlyNothing running, finished, or waiting

Click the icon to open a menu grouped into 需要你处理 (Needs you) → 失败 (Failed) → 运行中 (Running) → 已完成 (Finished). Every row is one agent with its title and how long it has been in that state. Clicking a row opens that exact agent in Paseo. The menu also has 打开 Paseo (Open Paseo), 登录时启动 (Launch at login), 托盘设置… (Tray settings…), and 退出 (Quit).

The menu bar app and the plugin screens currently use Simplified Chinese UI labels; this page translates them in parentheses.

While Paseo is not frontmost, new finished, failed, and permission events flash the menu bar icon even when macOS notifications are off, so you notice them without allowing banners.

What the plugin adds inside Paseo

  • Sidebar entry — a Paseo Tray ▶2 ✓1 !1 row at the bottom of Paseo's sidebar. Click it to open the agent screen.
  • Agents screen — the same grouping as the menu, with clickable rows that jump to each agent.
  • Settings screen — every tray option in one place, with the shared config file path and the last write result.
  • Command Center actions — Open Paseo Tray agents and Configure Paseo Tray.
  • Install detection — if the menu bar app is not installed on this Mac, the agent screen and settings show a download link.

Setup

Paseo Tray requires macOS 13 or later and Paseo 0.14.0 or later.

  1. Install the Paseo Tray macOS app from the project's GitHub Releases, and move it to /Applications or ~/Applications.
  2. The menu bar icon appears as soon as the app launches. Allow notifications only if you want system banners; the flashing icon works without them.

Launch at login is optional and uses the macOS login item API. The app asks for notification permission only when you enable a notification switch.

Settings

The settings screen writes one shared file: ~/Library/Application Support/PaseoTray/config.json.

SettingDefaultEffect
显示运行中数量 (Show running count)onShow ▶ n in the menu bar title
显示已完成数量 (Show finished count)onShow ✓ n in the menu bar title
包含子 agent (Include subagents)offShow agents labeled paseo.parent-agent-id
完成时通知 (Notify on finish)offPost a macOS notification when an agent finishes
出错时通知 (Notify on error)offPost a notification when an agent fails
需要权限时通知 (Notify on permission)offPost a notification when an agent needs permission
播放声音 (Play sound)offAdd the default notification sound

Notification switches are off by default because Paseo already sends its own notifications. When one is on, the tray stays silent while Paseo is frontmost.

The plugin writes the file with a temporary file and an atomic rename; the tray watches the folder and usually applies a change in under a second. If the plugin is disabled, the tray keeps using the last saved settings.

Data and privacy

  • The tray connects directly to the local Paseo daemon over its WebSocket API. Nothing goes through a cloud service.
  • It reads the existing ~/.paseo/local-credential file for authentication and never writes it. The token stays in memory and is not logged.
  • The plugin writes one non-sensitive JSON file (the settings above) and reads the local daemon. It does not send data anywhere.
  • The tray and plugin never modify /Applications/Paseo.app or Paseo's own config.

Limits

  • Only a local daemon advertised as host:port in paseo.pid or config.json is supported. Unix socket and pipe endpoints are reported as unsupported.
  • The tray only manages the Mac it runs on. It cannot install or start a native app on another machine.
  • If the daemon requires a password and the stored credential is invalid, the tray shows “Password required” and offers to open Paseo.
  • The menu bar item follows the active display. Multi-display setups and menu bar managers such as Hidden Bar may move it into a hidden section.

Paseo Tray is an unofficial companion project. The Paseo name and logo belong to their owners.