Add custom menu bar programs on macOS in three easy steps:
- Write a shell script
- Add it to SwiftBar
- … there is no 3rd step!
You can get plugins from awesome BitBar repository, or in SwiftBar itself using the
Get Plugins... menu item.
How to get SwiftBar
Download from GitHub Releases
or Install with Homebrew
brew install swiftbar
Runs on macOS Catalina (10.15) and up.
…or build it from source
- Clone or download a copy of this repository
- Press play
SwiftBar is bundled with a Plugin Repository. You can access it at Swiftbar → Get Plugins…
If you want to add\remove plugin or have other questions about repository content please refer to this issue.
To add a new plugin to SwiftBar, you need to create an executable script following the required format (see below) and put it into
With the first launch, Swiftbar will ask you to set the
Plugin Folder. SwiftBar will try to import every file in this folder as a plugin.
- hidden folders are ignored
- nested folders are traversed by SwiftBar, including symlinks
Plugin files must adopt the following format:
- name – Anything you want.
- time – Refresh interval (optional). Should be a number + duration modifier (see below)
- ext – File extension.
- ms – milliseconds, e.g. 1ms – refresh every millisecond
- s – seconds, e.g. 1s – refresh every second
- m – minute, e.g. 10m – refresh every ten minutes
- h – hour, e.g. 3h – refresh every three hours
- d – day, e.g. 1d – refresh every day
Plugin is an executable script in the language of your choice. When SwiftBar detects a new file in
Plugin Folder it makes this file executable if needed and runs it.
Script should produce output (
STDOUT) in the required format (see next chapter). Script errors should be redirected to
Plugin API is adopted from the BitBar, which means that SwiftBar can run any existing BitBar plugin.
When parsing plugin output SwiftBar recognizes the following blocks:
- Header: responsible for what you see in the menu bar
- Body: responsible for dropdown menu contents
Header is everything before first
--- after the first one will be interpreted as a menu separator.
You have one or more lines in the header.
The simplest plugin looks like this:
echo "This is Menu Title"
If you provide multiple titles, the provided titles will be cycled in the menu bar and shown in the dropdown menu:
echo "This is a primary Menu Title" echo "This is a secondary Menu Title" echo "This is a n-th Menu Title" echo "---" echo "This is not a Menu Title, this will be showed in the drop-down menu only"
Script output for both header and body is split by line (
\n). Each line must follow this format:
<Item Title> | [param = ...]
- “Item Title” can be any string, this will be used as a menu item title.
- [param = …] is an optional set of parameters\modificators. Each parameter is a key-value separated by
|to separate parameters from the title.
Title line in
Header section supports multiline, use
\\n to separate lines, i.e.:
echo "Line 1 \\n Line2 | size=8"
||CSS color or HEX,
||Sets item text color. If only one color is provided, it is used for both light and dark appearance.|
||CSS color or HEX,
||Sets SF Symbol color. If only one color is provided, it is used for both light and dark appearance.|
||macOS font name||Sets font name to use in item text|
||Number||Sets item text size|
||Number||Trims item text to a provided number of characters. The full title will be displayed in a tooltip.|
||True||Trims whitespace characters|
||True||Enables support of ANSI color codes. Conflicts with:
||False||Disables parsing of GitHub style Emojis (e.g.,
||False||Disables parsing of SF Symbols (e.g.,
||False||Only applicable to items in
||True||Marks a line as an alternative to the previous one for when the Option key (⌥) is pressed in the dropdown.|
||Image encoded in Base64||Sets an image for item.|
||Image encoded in Base64||Same as
||SFSymbol name||Sets an image for item from SF Symbol. Only available on Big Sur and above.|
||True||Sets a checkmark in front of the item.|
||Text||Sets a tooltip for the item.|
||True||Plugin Script will be executed on item click|
||Absolute URL||Sets an URL to open when item clicked|
||Absolute file path||Executable script to run in Shell|
||CMD+OPTION+T||Hotkey assigned to item. If item is in header, hotkey will show the menu; otherwise, hotkey will launch associated action.|
When running a plugin, SwiftBar sets the following environment variables:
||The running SwiftBar version number (in
||The running SwiftBar build number (
||The path to the
||The path to the running plugin|
||Current macOS appearance (
||The first part of the macOS version (e.g.,
||The second part of the macOS version (e.g.,
||The third part of the macOS version (e.g.,
It is recommended to include metadata in plugin script. Metadata is used in the About Plugin screen in SwiftBar.
SwiftBar adopts metadata format suggested by BitBar:
# <bitbar.title>Title goes here</bitbar.title> # <bitbar.version>v1.0</bitbar.version> # <bitbar.author>Your Name</bitbar.author> # <bitbar.author.github>your-github-username</bitbar.author.github> # <bitbar.desc>Short description of what your plugin does.</bitbar.desc> # <bitbar.image>http://www.hosted-somewhere/pluginimage</bitbar.image> # <bitbar.dependencies>python,ruby,node</bitbar.dependencies> # <bitbar.abouturl>http://url-to-about.com/</bitbar.abouturl> # <bitbar.droptypes>Supported UTI's for dropping things on menu bar</bitbar.droptypes>
Hiding default items
SwiftBar supports these optional metadata flags to hide default menu items:
# <swiftbar.hideAbout>true</swiftbar.hideAbout> # <swiftbar.hideRunInTerminal>true</swiftbar.hideRunInTerminal> # <swiftbar.hideLastUpdated>true</swiftbar.hideLastUpdated> # <swiftbar.hideDisablePlugin>true</swiftbar.hideDisablePlugin> # <swiftbar.hideSwiftBar>true</swiftbar.hideSwiftBar>
Option+Click will show all items:
A special tag can be used as an alternative to refresh interval defined in plugin’s name, value adopts Cron syntax:
<swiftbar.schedule>01,16,31,46 * * * *</swiftbar.schedule>
<swiftbar.runInBash>false</swiftbar.runInBash>– doesn’t wrap plugins in Bash when running
<swiftbar.type>streamable</swiftbar.type>– mark plugin as Streamable
<swiftbar.environment>[var1:default value, var2:default value, ... ]</swiftbar.environment>– this variables will be passed in plugin’s environment, in later release SwiftBar will provide a UI to change values for these variables.
Metadata for Binary Plugins
For binary plugins metadata can be added as an extended file attribute:
xattr -w "com.ameba.SwiftBar" "$(cat metadata.txt | base64)" <plugin_file>
For Standard type of plugins, SwidtBar expects that plugin execution is finite, i.e., plugin runs and exits with output to stdout:
- exit with code 0 and non-empty stdout – menu bar is built from the output
- exit with code 0 and empty stdout – nothing in the menu bar
- exit with code 1 – error shown in the menu bar
Optionally, a standard plugin can be run on a repeatable schedule, configured in the plugin’s file name or
schedule metadata property.
Swiftbar launches a separate process for each Streamable plugin, which runs indefinitely until SwiftBar is closed or a failure.
You should use Stremable plugins only when dealing with a stream of incoming events; an example could be financial market info read from a websocket or CPU load information for a remote computer.
To let SwiftBar know when to update the menu bar item, Streamable plugins must use a special line separator
~~~. SwiftBar will reset the menu item on each occurrence of this separator.
In the example below, SwiftBar will show “Test 1” in the menu bar for 3 seconds, then nothing for 5 seconds, and “Test 2” indefinitely.
#!/bin/bash #<swiftbar.type>streamable</swiftbar.type> echo "Test 1" echo "---" echo "Test 2" echo "Test 3" sleep 3 echo "~~~" sleep 5 echo "~~~" echo "Test 2"
You can mark a plugin as streamable with a special metadata property
|refreshallplugins||none||Force refresh all loaded plugins||
||Force refresh plugin by name||
||Force refresh plugin by its position in menubar||
||Add plugin to Swiftbar from URL||
Preferences aka ‘defaults’
List of preferences that are not exposed in SwiftBar UI:
defaults write com.ameba.SwiftBar DisableBashWrapper -bool YES– doesn’t wrap plugins in Bash when running
defaults write com.ameba.SwiftBar MakePluginExecutable -bool NO– disables auto
chmod +xall files in Plugin Directory
defaults write com.ameba.SwiftBar PluginDeveloperMode -bool YES– enables editing in Preferences -> Plugins
defaults write com.ameba.SwiftBar StreamablePluginDebugOutput -bool YES– enables debug output for Streamable plugins, Swiftbar will expose the stream data in Console.App
Logs and Error
If plugin fails to run SwiftBar will show ⚠️ in the menu bar, you can see details by clicking on Error in dropdown menu.
Console.app to view SwiftBar logs.
SwiftBar uses these open source libraries:
To freeze and secure dependencies these libraries are forked to SwiftBar organization.
SwiftBar can be translated here.
If you enjoy SwiftBar you may like these as well:
- TRex – Easy to use text extraction tool for macOS
- Esse – Swiss army knife of text transformation for iOS and macOS