SwiftBar: The Ultimate macOS Menu Bar Customization Tool

SwiftBar is a powerful open-source tool that transforms your macOS menu bar into a dynamic, customizable dashboard. Whether you're a developer, power user, or someone who loves personalizing their Mac experience, SwiftBar offers endless possibilities for displaying custom information right in your menu bar.

What is SwiftBar?

SwiftBar is a modern macOS menu bar customization app that allows you to add custom menu bar items based on shell scripts output. It's inspired by the popular BitBar but built entirely in Swift, offering better performance and native macOS integration. With SwiftBar, you can display anything from system stats to cryptocurrency prices, weather updates to Spotify controls – all from simple scripts.

Key Features That Set SwiftBar Apart

1. Script-Based Flexibility

SwiftBar's core strength lies in its script-based approach. Any executable script (Bash, Python, Ruby, Swift, etc.) can create a menu bar item. This means if you can code it, you can display it in your menu bar.

2. Native macOS Experience

Built with Swift and SwiftUI, SwiftBar feels right at home on macOS. It supports Dark Mode, uses native menu styling, and integrates seamlessly with macOS notifications and system events.

3. Plugin Ecosystem

The SwiftBar community has created hundreds of plugins for common use cases. From monitoring Docker containers to tracking time zones, there's likely a plugin for your needs. And if not, creating your own is straightforward.

4. Performance Optimized

Unlike some alternatives, SwiftBar is incredibly lightweight. It uses minimal system resources while running multiple scripts, ensuring your Mac stays responsive.

5. SF Symbols Support

SwiftBar fully supports Apple's SF Symbols library, giving you access to thousands of high-quality icons that match macOS's design language perfectly.

Getting Started with SwiftBar

Installation

The easiest way to install SwiftBar is through Homebrew:

brew install swiftbar

Alternatively, you can download the latest release from the GitHub repository and drag it to your Applications folder.

Your First Plugin

Creating a SwiftBar plugin is remarkably simple. Here's a basic example that displays "Hello World" in your menu bar:

#!/bin/bash
# Save as hello.1m.sh in your plugins folder
# The .1m means it refreshes every 1 minute

echo "Hello World"
echo "---"
echo "This is a submenu item"
echo "Click me | href=https://github.com/swiftbar/SwiftBar"

Save this script in your SwiftBar plugins folder (you can set this in SwiftBar preferences), make it executable with chmod +x hello.1m.sh, and SwiftBar will automatically detect and run it.

Advanced Plugin Examples

System Monitor Plugin

Here's a more practical example that monitors system resources:

#!/bin/bash
# system-monitor.5s.sh - Updates every 5 seconds

# CPU Usage
cpu_usage=$(top -l 1 | grep "CPU usage" | awk '{print $3}' | sed 's/%//')
# Memory Usage
memory_stats=$(vm_stat | grep "Pages free" | awk '{print $3}' | sed 's/\.//')
memory_free=$((memory_stats * 4096 / 1048576))

echo "💻 CPU: ${cpu_usage}% | RAM: ${memory_free}MB"
echo "---"
echo "Activity Monitor | shell=/System/Applications/Utilities/Activity\ Monitor.app/Contents/MacOS/Activity\ Monitor"
echo "System Information | shell=/System/Applications/Utilities/System\ Information.app/Contents/MacOS/System\ Information"

Weather Display Plugin

#!/usr/bin/env python3
# weather.30m.py - Updates every 30 minutes

import requests
import json

# Replace with your API key and location
API_KEY = "your_api_key"
CITY = "San Francisco"

response = requests.get(f"http://api.openweathermap.org/data/2.5/weather?q={CITY}&appid={API_KEY}&units=metric")
data = response.json()

temp = data['main']['temp']
description = data['weather'][0]['description']

print(f"🌡️ {temp}°C - {description.title()}")
print("---")
print(f"City: {CITY}")
print(f"Feels like: {data['main']['feels_like']}°C")
print(f"Humidity: {data['main']['humidity']}%")

Plugin Development Best Practices

1. Refresh Intervals

Choose appropriate refresh intervals for your plugins. Use these common suffixes:

• .1s - Every second (use sparingly)
• .5s - Every 5 seconds
• .1m - Every minute
• .5m - Every 5 minutes
• .1h - Every hour
• .1d - Once daily

2. Error Handling

Always include error handling in your scripts to prevent menu bar clutter:

#!/bin/bash
result=$(some_command 2>/dev/null)
if [ $? -ne 0 ]; then
    echo "⚠️ Error"
    echo "---"
    echo "Click to retry | refresh=true"
    exit 1
fi
echo "$result"

3. Use Parameters

SwiftBar supports various parameters to enhance functionality:

echo "Styled Text | color=#FF0000 font='Monaco' size=12"
echo "Clickable Item | href=https://example.com"
echo "Run Command | shell=/usr/bin/open param1=-a param2=Safari"
echo "Refresh Plugin | refresh=true"

4. Implement Caching

For API-heavy plugins, implement caching to reduce load:

#!/usr/bin/env python3
import json
import time
from pathlib import Path

CACHE_FILE = Path.home() / ".swiftbar_cache" / "my_plugin.json"
CACHE_DURATION = 300  # 5 minutes

def get_cached_data():
    if CACHE_FILE.exists():
        with open(CACHE_FILE) as f:
            cache = json.load(f)
            if time.time() - cache['timestamp'] < CACHE_DURATION:
                return cache['data']
    return None

def save_cache(data):
    CACHE_FILE.parent.mkdir(exist_ok=True)
    with open(CACHE_FILE, 'w') as f:
        json.dump({'timestamp': time.time(), 'data': data}, f)

Popular Use Cases

Development Workflow

• Git Status: Monitor repository changes across projects
• CI/CD Pipeline: Track build status from Jenkins, GitHub Actions, or GitLab
• Docker Containers: View running containers and their status
• Database Connections: Monitor database health and query performance

Productivity

• Pomodoro Timer: Built-in timer for focused work sessions
• Calendar Events: Display upcoming meetings from Calendar.app
• Todo Lists: Integration with Things, OmniFocus, or custom lists
• Time Tracking: Monitor time spent on different projects

System Monitoring

• Network Speed: Real-time upload/download speeds
• Disk Usage: Alert when storage is running low
• Battery Stats: Detailed battery health information
• Temperature Sensors: CPU and GPU temperature monitoring

Personal Dashboard

• Stock Prices: Track your portfolio in real-time
• Cryptocurrency: Monitor Bitcoin and other crypto prices
• Weather Forecast: Detailed weather information
• News Headlines: RSS feed integration for latest news

SwiftBar vs Alternatives

SwiftBar vs BitBar

While BitBar pioneered the concept, SwiftBar offers several advantages:

• Better performance and lower resource usage
• Native Swift implementation
• More robust plugin management
• Active development and community support

SwiftBar vs xbar

xbar (formerly BitBar) and SwiftBar share similar concepts, but SwiftBar's Swift-native implementation provides better macOS integration and performance.

SwiftBar vs Stats

Stats is excellent for system monitoring but lacks SwiftBar's extensibility. SwiftBar can replicate Stats' functionality while adding custom features.

Troubleshooting Common Issues

Plugin Not Appearing

1. Ensure the script is executable: chmod +x plugin.sh
2. Check the plugin folder path in SwiftBar preferences
3. Verify the script has a valid refresh interval suffix

High CPU Usage

• Avoid refresh intervals shorter than 1 second
• Optimize scripts to run efficiently
• Use caching for expensive operations

Script Errors

• Test scripts in Terminal first
• Check SwiftBar's console for error messages
• Ensure all dependencies are installed

Community and Resources

The SwiftBar community is active and welcoming:

• GitHub Repository: github.com/swiftbar/SwiftBar - Source code and issue tracking
• Plugin Repository: Browse hundreds of community-created plugins
• Discord Server: Get help and share your creations
• Documentation: Comprehensive guides and API reference

Advanced Features

Stream Mode

For real-time updates without polling:

#!/bin/bash
# streaming.sh

echo "Streaming Mode"
echo "---"
echo "Updates in real-time"

# Enable streaming mode
echo "~~~"

while true; do
    echo "Time: $(date +%H:%M:%S)"
    echo "---"
    echo "This updates every second"
    sleep 1
done

Environment Variables

SwiftBar provides useful environment variables to plugins:

• SWIFTBAR: Set to "1" when running in SwiftBar
• SWIFTBAR_PLUGIN_PATH: Full path to the running plugin
• SWIFTBAR_LAUNCH_TIME: When SwiftBar was launched

Preferences Storage

Store plugin preferences using SwiftBar's built-in storage:

# Save preference
defaults write com.ameba.SwiftBar pluginPreference -string "value"

# Read preference
preference=$(defaults read com.ameba.SwiftBar pluginPreference 2>/dev/null)

Performance Optimization Tips

1. Minimize External Calls: Cache API responses and system calls
2. Use Appropriate Languages: Shell scripts for simple tasks, Python/Swift for complex logic
3. Implement Lazy Loading: Only fetch detailed data when submenus are opened
4. Batch Operations: Combine multiple data fetches into single operations

Security Considerations

When developing SwiftBar plugins:

• Never hardcode sensitive credentials
• Use macOS Keychain for storing API keys
• Validate all external input
• Be cautious with shell commands that accept parameters

Future of SwiftBar

SwiftBar continues to evolve with:

• Improved plugin marketplace
• Enhanced debugging tools
• Better integration with macOS features
• Support for interactive widgets

Conclusion

SwiftBar represents the perfect balance between simplicity and power for macOS menu bar customization. Whether you need a simple system monitor or a complex development dashboard, SwiftBar provides the tools and flexibility to create exactly what you need.

Its script-based approach means you're never limited by the app's built-in features – if you can imagine it and code it, SwiftBar can display it. The active community and extensive plugin ecosystem ensure you'll find inspiration and support for your customization journey.

Start with simple plugins, explore the community repository, and gradually build your perfect menu bar setup. With SwiftBar, your Mac's menu bar becomes a powerful, personalized command center tailored to your exact needs.