ProcessBeacon

Monitor long-running terminal processes from your macOS menu bar. Get notified when builds, tests, or deploys finish.

Why

I start a cargo build or npm test that takes 10 minutes, switch to something else, and forget to check. ProcessBeacon watches any process I care about and sends a macOS notification when it exits. No more Alt-Tabbing back to check if the build finished.

Features

• Antenna icon in menu bar (animated when watching processes)
• Watched process count badge in menu bar
• Process list sorted by runtime (longest first)
• Category auto-detection: Build, Test, JS/TS, Runtime, Infra, Dev Tool
• Color-coded category icons
• Click eye icon to watch/unwatch any process
• macOS notification when a watched process exits
• Completed processes log with timestamps
• Search/filter by name, PID, or category
• Hover to see full command path
• High CPU indicator (red badge at 5%+)
• Smart filtering hides system daemons, Chrome helpers, etc.
• Auto-refresh every 5 seconds

Install

Using the build script (recommended):

cd ProcessBeacon
chmod +x build.sh
./build.sh
open ProcessBeacon.app

Or compile manually:

cd ProcessBeacon
swiftc -parse-as-library -o ProcessBeacon ProcessBeacon.swift
./ProcessBeacon

Or build a .app bundle manually (no dock icon, notifications work):

cd ProcessBeacon
swiftc -parse-as-library -o ProcessBeacon ProcessBeacon.swift
mkdir -p ProcessBeacon.app/Contents/MacOS
cp ProcessBeacon ProcessBeacon.app/Contents/MacOS/
cp Info.plist ProcessBeacon.app/Contents/
open ProcessBeacon.app

Quickstart

1. Build and launch: swiftc -parse-as-library -o ProcessBeacon ProcessBeacon.swift && ./ProcessBeacon
2. Look for the antenna icon in your menu bar
3. Click to see all running user processes
4. Click the eye icon next to a long-running build/test to watch it
5. Switch to other work — you'll get a notification when it finishes

Examples

Watch a Rust build:

• Start cargo build --release in your terminal
• Open ProcessBeacon, find "cargo" in the list
• Click the eye icon to watch it
• Continue working — notification appears when build completes

Watch multiple processes:

• Watch a Docker build, npm install, and pytest run simultaneously
• Badge in menu bar shows "3" for 3 watched processes
• Each one triggers a separate notification on completion

Filter by category:

• Use the search bar to type "Build" or "Test"
• Only processes matching that category appear
• Useful when you have dozens of processes running and need to find a specific build

Spot high-CPU processes:

• Processes using more than 5% CPU show a red badge
• Helps you notice a runaway build or stuck test runner without opening Activity Monitor

Testing

ProcessBeacon has no automated test suite (single-file SwiftUI app). Verify correctness manually:

1. Compile check -- swiftc -parse-as-library -o ProcessBeacon ProcessBeacon.swift should complete with zero errors and zero warnings.
2. Launch check -- run ./ProcessBeacon or open ProcessBeacon.app. An antenna icon should appear in the menu bar.
3. Process list -- click the menu bar icon. You should see user-launched processes sorted by runtime. System daemons should be filtered out.
4. Watch a process -- start a long-running command in Terminal (e.g., sleep 120). Find it in the list and click the eye icon. The menu bar badge should increment.
5. Notification on exit -- kill the watched process (kill <PID> or let it finish). A macOS notification should appear saying the process has completed.
6. Completed log -- after a watched process exits, it should appear in the "Completed" section at the bottom of the popup with a timestamp.
7. Search/filter -- type a process name or PID into the search bar. The list should filter to matching results.
8. Category detection -- verify that cargo, swift, or gcc processes show as "Build", pytest or jest as "Test", node or bun as "JS/TS".
9. Background-only -- verify no dock icon appears. On macOS, run: osascript -e 'tell application "System Events" to get name of every process whose background only is true' and confirm ProcessBeacon is in the list.

Troubleshooting

• No processes showing — ProcessBeacon filters out system daemons by default. Only user-launched processes appear.
• Notification permission — macOS will prompt for notification permission on first launch. Allow it for completion alerts to work.
• Process not in list — Use the search bar to filter by name or PID. Some short-lived processes may exit between refreshes.

Requirements

• macOS 14.0+ (Sonoma or later)
• Swift 6.0+ compiler
• Notification permission (prompted on first launch)

License

MIT