https://github.com/jedisct1/pingbar
Lightweight network and DNS monitoring at a glance, right from your Mac menu bar.
https://github.com/jedisct1/pingbar
bar dns dnscrypt-proxy lightweight mac macos menu menubar native osx ping swift
Last synced: about 1 month ago
JSON representation
Lightweight network and DNS monitoring at a glance, right from your Mac menu bar.
- Host: GitHub
- URL: https://github.com/jedisct1/pingbar
- Owner: jedisct1
- License: mit
- Created: 2025-06-04T06:22:41.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-03-14T19:12:10.000Z (about 1 month ago)
- Last Synced: 2026-03-15T05:23:30.018Z (about 1 month ago)
- Topics: bar, dns, dnscrypt-proxy, lightweight, mac, macos, menu, menubar, native, osx, ping, swift
- Language: Swift
- Homepage:
- Size: 1.66 MB
- Stars: 55
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PingBar
[](LICENSE)
[](https://www.apple.com/macos/)
[](https://swift.org)
PingBar is a lightweight, modern, non-intrusive, native macOS menu bar app that continuously monitors network latency, packet loss, and DNS settings.
It provides real-time ping statistics, packet loss monitoring, network interface information, and **one-click DNS management including dnscrypt-proxy control**, all from your menu bar with minimal system resource usage.
## Screenshots
### Main Menu
The main menu shows real-time network status with:
- Current ping time and status
- Sparkline graph with ping statistics (avg/min/max)
- Packet loss percentage and collection progress
- Active network interfaces with IP addresses
- Current DNS resolver information
- Quick access to DNS management and preferences
### Preferences Window
The preferences window allows you to configure:
- Ping interval and target host
- High ping threshold for warnings
- Passive or active packet loss measurement
- Packet loss thresholds, window size, and active probe cadence
- DNS auto-revert behavior for captive portals
- Launch at login option
## Features
- **Live Network Status**: Pings a configurable host (default: Google) and shows latency and packet loss together in a single menu bar icon.
- **Packet Loss Monitoring**: Measures loss passively from the regular ping stream or actively with configurable burst probes.
- **Historical Ping Graph**: Unicode sparkline graph and statistics (avg/min/max) for recent pings.
- **Network Interface Info**: Displays active local IP addresses with interface names.
- **DNS Resolver Display**: Shows current DNS resolvers for your default interface.
- **DNS Management**: Change DNS for your default interface with one click (System Default, Cloudflare, Google, Quad9, 114DNS, dnscrypt-proxy, etc.). **Perfect for controlling dnscrypt-proxy usage from the menu bar.**
- **Captive Portal Detection**: Detects captive portals and can auto-revert DNS to default, restoring your custom DNS after login.
- **Preferences Dialog**: Configure ping interval, target host, high ping threshold, packet loss mode, packet loss thresholds, DNS auto-revert, and launch at login.
- **Auto-Start**: Optionally launch PingBar at login using a LaunchAgent.
- **Lightweight & Native**: Built with Swift, AppKit, and SwiftPM. No Python or Electron, no bloat. Minimal memory footprint.
## Installation
### Homebrew (Recommended)
Install PingBar using Homebrew Cask:
```bash
git clone https://github.com/jedisct1/pingbar.git
cd pingbar
brew install --cask ./Casks/pingbar.rb
open /Applications/PingBar.app
```
### Download
Download the latest release from the [Releases](https://github.com/jedisct1/pingbar/releases) page. Pre-built binaries are available for both Intel and Apple Silicon Macs.
### Build from Source
#### Requirements
- macOS 12.0+ (Monterey) recommended
- Xcode 14+ or Swift 6.1+
- Command line tools: `swift`, `codesign` (for signing)
#### Quick Start
```sh
git clone https://github.com/jedisct1/pingbar.git
cd pingbar
make bundle
make install
```
See [INSTALL.md](INSTALL.md) for detailed installation instructions.
### Uninstall
#### Homebrew Installation
```bash
brew uninstall --cask pingbar
```
#### Manual Installation
To completely remove PingBar from your system:
1. **Quit PingBar**: Click the menu bar icon → "Quit PingBar"
2. **Remove the app**: Drag `PingBar.app` to Trash (usually in `/Applications/` or wherever you placed it)
3. **Remove launch agent** (if enabled):
```sh
rm ~/Library/LaunchAgents/com.pingbar.app.plist
```
4. **Remove preferences** (optional):
```sh
defaults delete com.pingbar.app
```
That's it! PingBar stores minimal data and leaves no background processes running.
#### Development
```sh
# Clone the repository
git clone https://github.com/jedisct1/pingbar.git
cd pingbar
# Build debug version
swift build
# Build release version
swift build -c release
# Run tests
swift test
# Create app bundle
./bundle_pingbar_app.sh
```
## Usage
### Getting Started
1. **Launch PingBar**: Double-click `PingBar.app` or run from the command line
2. **Menu Bar Icon**: Look for the ring icon in your menu bar. The center shows latency; the ring shows packet loss.
3. **Click the Icon**: View network status, ping statistics, and current settings
4. **Configure Settings**: Select "Preferences…" to customize behavior
### Menu Overview
- **Network Status**: Current ping time and connection status
- **Ping Graph**: Visual sparkline showing recent ping history with statistics
- **Packet Loss**: Current packet loss percentage, mode, and collection progress
- **Network Interfaces**: List of active network interfaces and their IP addresses
- **DNS Servers**: Current DNS resolvers for your default interface
- **DNS Management**: Quick access to change DNS settings
- **Preferences**: Configure all app settings
### DNS Management
PingBar provides one-click DNS switching for your default network interface:
- **System Default**: Use your network's default DNS
- **Cloudflare (1.1.1.1)**: Fast, privacy-focused DNS
- **Google (8.8.8.8)**: Reliable public DNS
- **Quad9 (9.9.9.9)**: Security-focused DNS with malware blocking
- **114DNS (114.114.114.114)**: Popular DNS service in China
- **dnscrypt-proxy (127.0.0.1)**: **Local encrypted DNS proxy - easily toggle dnscrypt-proxy on/off from the menu bar**
⚠️ **Note**: DNS changes require administrator privileges. You'll be prompted for your password.
## Configuration
Access preferences via the menu bar icon → "Preferences…"
### Settings
| Setting | Description | Default |
| ----------------------- | -------------------------------------------------------- | ---------------------- |
| **Ping Interval** | How often to ping the target (seconds) | 5.0 |
| **Target Host** | URL or IP to ping | https://www.google.com |
| **High Ping Threshold** | Latency threshold for warning state (ms) | 200 |
| **Packet Loss Mode** | Use the main ping stream (`Passive`) or active bursts (`Active`) for loss measurement | Passive |
| **Active Probe Interval** | How often active packet loss bursts run (seconds) | 30.0 |
| **Active Burst Size** | Number of HEAD requests per active loss burst | 5 |
| **Packet Loss Window** | Number of recent results kept for packet loss | 50 |
| **Loss Warning Threshold** | Packet loss percentage for yellow ring | 3.0 |
| **Loss Bad Threshold** | Packet loss percentage for red ring | 10.0 |
| **DNS Auto-Revert** | Revert DNS to system default when network is unreachable | false |
| **Restore Custom DNS** | Restore custom DNS after captive portal login | false |
| **Launch at Login** | Auto-start PingBar when you log in | false |
### Status Icons
PingBar now uses a combined icon instead of a single four-state dot:
- **Center fill**: latency state
- **Outer ring**: packet loss state
| Element | State | Meaning |
| ------- | ----- | ------- |
| Center fill | Green → Yellow → Orange → Red | Increasing latency severity |
| Center fill | Purple | Captive portal detected |
| Center fill | Dark gray | Network unavailable |
| Outer ring | Green | Packet loss below warning threshold |
| Outer ring | Yellow | Packet loss above warning threshold |
| Outer ring | Red | Packet loss above bad threshold |
| Outer ring | Gray | Still collecting enough packet-loss samples |
### Packet Loss Modes
- **Passive**: Uses only the normal scheduled ping results. This adds no extra traffic.
- **Active**: Runs additional HEAD request bursts to the same host for faster packet loss sampling.
Captive portal detections are excluded from packet loss accounting.
### Captive Portal Handling
When enabled, PingBar can automatically:
1. **Detect** captive portals (hotel/airport WiFi login pages)
2. **Revert** your custom DNS to system default to allow portal access
3. **Restore** your custom DNS after successful login
This ensures seamless connectivity while preserving your DNS preferences.
### Testing
```sh
# Run all tests
swift test
# Run specific test
swift test --filter TestName
```
## Troubleshooting
### Common Issues
**PingBar doesn't appear in menu bar**
- Ensure macOS 12.0+ is installed
- Check that the app has accessibility permissions if needed
- Try relaunching the app
**DNS changes don't work**
- Verify you have administrator privileges
- Check that `networksetup` command line tool is available
- Ensure your network interface is active
**App won't launch**
- Check Console.app for error messages
- Verify code signing if you built from source
- Try removing and reinstalling
### Performance Tips
- Use a reliable, fast target host for pinging
- Set reasonable ping intervals (5-10 seconds recommended)
- Use `Passive` packet loss mode if you want zero additional background traffic
- Use `Active` mode only when you need faster or denser packet loss sampling; low intervals and high burst sizes can create substantial traffic
- Enable launch at login for continuous monitoring
## Security
PingBar follows security best practices:
- **Minimal Permissions**: Only requests necessary system access
- **No Data Collection**: All data stays local on your device
- **Open Source**: Code is publicly auditable
- **Code Signing**: Release builds are signed and notarized
### Privacy
PingBar does not:
- Collect or transmit personal data
- Track your browsing habits
- Store sensitive information
- Connect to external services (except for ping tests)
## System Requirements
- **macOS**: 12.0 (Monterey) or later
- **Architecture**: Intel x64 or Apple Silicon (Universal Binary)
- **Memory**: 50MB RAM typical usage
- **Permissions**: Administrator access for DNS changes (optional)
## License
PingBar is released under the [MIT License](LICENSE).
## Acknowledgments
- Inspired by classic menu bar network tools like MenuMeters and iStat Menus
- Uses [Apple's AppKit](https://developer.apple.com/documentation/appkit) for native UI
- Built with [Swift Package Manager](https://swift.org/package-manager/)
- DNS management via `networksetup` and AppleScript
- Unicode sparkline graphs for visual ping history
---
**PingBar** — Network and DNS monitoring at a glance, right from your Mac menu bar. 🌐