SwiftBar turns any file in a folder into a menu bar item, and the filename sets the refresh
Powerful macOS menu bar customization tool
At a glance
- What is it?
- SwiftBar is a macOS menu bar customization tool that runs scripts from a plugin folder and renders their output in the menu bar. The filename carries the refresh interval, every file in the folder is imported, and parameter syntax is terse enough to cause silent surprises.
- Who is it for?
- SwiftBar fits someone who wants system state in the menu bar and is willing to write small scripts, and it fits people arriving from BitBar or xbar, since the plugin API is adopted from those projects and existing plugins run unchanged. It does not fit a shared or sensitive machine without care, because every executable file in the plugin folder, including anything reached through a symlink, is imported and run, so folder hygiene is the only guard.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- swiftbar/SwiftBar4,797 ★ · +256
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| swiftbar/SwiftBar | 4.5k | 4.8k |
256 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The filename carries the refresh interval
Plugin files must adopt one format:
{name}.{time}.{ext}The name can be anything. The time part is optional and is the refresh interval, written as a number plus a duration modifier, and the modifiers run from milliseconds to days: ms for milliseconds such as 1ms, s for seconds such as 1s, m for minutes such as 10m, h for hours such as 3h, and d for days such as 1d. A complete example given is date.1m.sh, which is a script that refreshes every minute. Because the interval lives in the name rather than in a setting, changing how often a plugin runs means renaming its file, and the documentation warns about the side effect of that: plugin position is remembered unless you change the name of the plugin file, in which case the plugin has to be positioned again.
Every file in the folder is imported as a plugin
SwiftBar tries to import every file in the plugin folder as a plugin, and on first launch it asks you to set that folder. The rules around what gets imported are worth reading closely. Hidden folders are ignored, nested folders are traversed by SwiftBar including symlinks, and a .swiftbarignore file is supported so you can exclude files. A folder can be hidden by prepending a dot to its name or by using the command chflags hidden with the folder name. The consequence is that the folder is a load directory rather than a curated list: a notes file you drop next to your plugins becomes a menu bar entry unless you hide it, prefix it with a dot, or list it in the ignore file. Symlinked directories are followed too, so a shared plugins folder works and also imports everything it happens to contain.
STDOUT is the API and STDERR is for errors
A plugin is an executable script in the language of your choice. When SwiftBar detects a new file in the plugin folder it makes the file executable if needed and runs it. The contract is short: the script produces its output on standard output in the required format, and script errors should be redirected to standard error. The format is adopted from the BitBar and xbar projects, and the stated consequence is that SwiftBar can run any existing BitBar or xbar plugin. That compatibility is the main reason to choose this tool, and it is also a constraint: the output format is another project's design, quirks included, and anything your script prints unintentionally becomes menu content rather than a log line.
Everything before the first --- is the menu bar
Output is read as two blocks. The header is what you see in the menu bar, the body is the dropdown contents, the header is everything before the first ---, and each --- after the first one is interpreted as a menu separator. The simplest possible plugin is one line:
echo "This is Menu Title"Several lines in the header are cycled through in the menu bar and also shown in the dropdown, so a plugin can carry more than one title:
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 shown in the drop-down menu only"The separator is the fragile part. Since every --- after the first one becomes a separator, a script that prints one while building a title splits its own menu in a place you did not choose.
Parameters are a pipe-separated key value list
Each line of header and body output follows one format:
<Item Title> | [param = ...]The title is any string, and the parameters are key-value pairs separated by =, with | between the title and the parameters and spaces between parameters. The text formatting parameters are:
| Parameter | Value | Description | | ------------- | ------------- |------------- | | `color` | CSS color or HEX, `light_color,dark_color` | Sets item text color. If only one color is provided, it is used for both light and dark appearance. | | `sfcolor` | CSS color or HEX, `light_color,dark_color` | Sets SF Symbol color. If only one color is provided, it is used for both light and dark appearance. | | `font` | macOS font name | Sets font name to use in item text | | `size` | Number | Sets item text size | | `md` | True | Enables markdown support in menu title for (bold) and (italic) | | `sfsize` | Number | Sets size for SF Symbol image embedded in text | | `length` | Number | Trims item text to a provided number of characters, with the full title in a tooltip | | `trim` | True | Trims whitespace characters | | `ansi` | True | Enables support of ANSI color codes. Conflicts with symbolize |
The conflicts are the part to memorise: ansi and symbolize cannot both apply, and the GitHub style emoji option requires symbolize set to false when it is turned on.
Menu position is manual and lost on rename
Whether a plugin comes from the repository or you wrote it yourself, plugins initially appear in the menu bar in no pre-determined order. Reordering is done by holding down Cmd and dragging them, and the same gesture can move some other non-SwiftBar menu bar icons as well. The position is remembered, but with the caveat already mentioned: change the name of the plugin file and the plugins need to be repositioned again. Combined with the naming format, this creates an odd dependency, since the natural way to change a refresh interval is to edit the time part of the name, which is also the name. If you care about the order of your menu bar, treat the filename as a permanent identifier and pick intervals you are willing to live with.
Catalina guidance survives a Monterey minimum
The platform floor is stated plainly: SwiftBar runs on macOS Monterey (12) and later. Some of the parameter documentation has not caught up with that. The symbolize parameter is documented as always False on Catalina, which is a system the app no longer supports at all, and the sfimage parameter for setting an item image from an SF Symbol is marked as only available on Big Sur and above, which is below the stated minimum. So the version conditions in the parameter reference do not line up with the supported systems, and a reader cannot tell from the reference whether a symbol will render. Practically, treat the Monterey floor as the real boundary and test symbols on your own machine rather than reading version rules out of the table.
Recent tags are 2.1.2 betas, and plugins have their own docs
The release list is worth a look before you download. The three most recent tags are all betas of the same version: 2.1.2 beta 3 dated 2026-08-15, 2.1.2 beta 4 dated 2026-09-27, and 2.1.2 beta 5 dated 2026-09-29, and the most recent push on the repository is dated 2026-09-29. So grabbing the newest artifact from the releases page may hand you a beta rather than a final 2.1.2. The repository root also separates the app from its plugins, holding SwiftBar.xcodeproj/, SwiftBar/, SwiftBarTests/, Examples/ManualTesting/, a Justfile for tasks, Scripts/, and Resources/, next to README-PACKAGED-PLUGINS.md for the bundled plugins and the main README for the application itself. Plugin requests go through a separate issue tracker.
Editorial conclusion
SwiftBar fits someone who wants system state in the menu bar and is willing to write small scripts, and it fits people arriving from BitBar or xbar, since the plugin API is adopted from those projects and existing plugins run unchanged. It does not fit a shared or sensitive machine without care, because every executable file in the plugin folder, including anything reached through a symlink, is imported and run, so folder hygiene is the only guard. Before you rely on it, check three things: your macOS version, since the stated minimum is Monterey 12; the tag you install, because the recent releases are 2.1.2 betas rather than a final 2.1.2; and your file naming, because a refresh interval lives in the filename and renaming a plugin resets its menu bar position.
Frequently asked questions
how to install swiftbar
Download it from GitHub Releases, or install it with Homebrew using brew install swiftbar. SwiftBar runs on macOS Monterey (12) and later. To build it from source instead, clone or download the repository, open SwiftBar/SwiftBar.xcodeproj, and press play.
what is swiftbar
A macOS menu bar customization tool. You write a shell script, add it to SwiftBar, and there is no third step. Plugins can also come from the bundled Plugin Repository through the Get Plugins... menu item, or from the BitBar plugin repository, because the plugin API is adopted from BitBar and xbar.
how to use swiftbar
On first launch SwiftBar asks you to set the Plugin Folder, then tries to import every file in it as a plugin. A plugin is an executable script that writes to standard output, where everything before the first --- is the menu bar header and each later --- becomes a menu separator. Each line is a title followed by optional parameters separated by |.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/swiftbar-swiftbar)Star history chart for your README
[](https://hysenlabs.com/projects/swiftbar-swiftbar)Was this useful?