Runtime Radar

Local ports, tmux sessions, and dev workers in your menu bar.

Tiny macOS menu bar app for answering the daily local-dev question:

What is running on this machine, where is it, and what does it belong to?

Runtime Radar discovers local listening ports, probes likely web endpoints, connects ports to tmux panes when possible, groups services by project, and keeps expected services visible when they go offline.

Why

• Stop guessing which local server owns port 3000, 4173, or 8080.
• See project runtimes first, with noisy macOS/system listeners tucked away.
• Catch expected services that quietly stopped listening.
• Understand tmux-backed workers without attaching to every session.
• Release old expected ports manually when you are done with them.

Install

Requirements

• macOS 13+
• lsof
• tmux for tmux enrichment

GitHub Releases

Download: https://github.com/omribz156/RuntimeRadar/releases

One-line installer

curl -fsSL https://raw.githubusercontent.com/omribz156/RuntimeRadar/main/script/install.sh | bash

The installer downloads the latest release zip, installs Runtime Radar.app into ~/Applications, registers it with macOS Launch Services, and opens the menu bar app.

Runtime Radar is currently ad-hoc signed, not notarized. macOS may show a first run warning until Developer ID signing and notarization are added.

First Run

• Open Runtime Radar from Spotlight, Raycast, Finder, or the installer.
• Click the menu bar icon.
• Expand a port row to label it with a friendly name and project.
• Offline labeled ports stay visible until you click Release.

Features

• Project-first menu bar view with nested Ports and tmux sections.
• live, local, and offline status for local services.
• HTTP probing for loopback web endpoints.
• tmux pane/session enrichment for matching ports.
• Codex, Claude, Gemini, and similar tmux worker detection.
• Attached/detached tmux state.
• Git project grouping and dirty-state summaries.
• Dev, All, and System filters to keep OS/tool noise out of the way.
• Manual project reorder and hide controls.
• Local labels for important ports, including expected offline services.
• Background refresh while the popover is closed.
• CLI output for table, JSON, and project-first snapshots.

CLI

swift run runtime-radar
swift run runtime-radar --json
swift run runtime-radar --snapshot

The default table output is meant for humans. --json and --snapshot are stable enough for local scripts and tests.

Local Data

Labels are stored in:

~/Library/Application Support/Runtime Radar/labels.json

Project order is stored in:

~/Library/Application Support/Runtime Radar/project-order.json

Hidden projects are stored in:

~/Library/Application Support/Runtime Radar/hidden-projects.json

Privacy Note

Runtime Radar is local-first and read-only.

• It scans local listening TCP ports with lsof.
• It probes loopback HTTP endpoints.
• It reads tmux pane metadata when tmux is available.
• It reads git roots only for paths already reported by tmux/process metadata.
• It stores labels locally in your Application Support folder.

It does not send telemetry, phone home, or store API keys.

Docs

• Architecture: docs/architecture.md
• Testing: docs/testing.md
• Release packaging: docs/release.md
• Development: docs/development.md
• Changelog: CHANGELOG.md

Build From Source

Requires macOS 13+ and Swift 5.10+.

./script/build_and_run.sh

Install into ~/Applications:

./script/build_and_run.sh --install

Package a release zip:

./script/package_release.sh

Run checks:

swift test
RUNTIME_RADAR_TEST_PORT=auto ./script/live_port_hold_test.sh
./script/check_repo_ready.sh

Credits

Inspired by the quiet usefulness of small macOS menu bar tools like CodexBar.

License

MIT. See LICENSE.