+3
日增长
4,797
stars
146
forks
20
watchers
141
prs
421
issues
60
releases
README
SwiftBar
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 Monterey (12) and later.
...or build it from source
- Clone or download a copy of this repository
- Open SwiftBar/SwiftBar.xcodeproj
- Press play
Plugin Repository
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.
Creating Plugins
To add a new plugin to SwiftBar, you need to create an executable script following the required format (see below) and put it into Plugin Folder.
Plugin Folder
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.
Important:
hidden folders are ignored
nested folders are traversed by SwiftBar, including symlinks
.swiftbarignore file is supported, you can use it to exclude files from being imported as plugins.
You can hide a folder by prepending . or using this command chflags hidden .
Plugin Naming
Plugin files must adopt the following format:
{name}.{time}.{ext}
name - Anything you want.
time - Refresh interval (optional). Should be a number + duration modifier (see below)
ext - File extension.
Duration modifiers:
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
Example filename: date.1m.sh
Whether you are using a plugin from the plugin repository, or creating your own, plugins will initially appear in the menu bar in no pre-determined order. However, you can reorder how they appear by holding down Cmd and dragging them (this process can sometimes also be used on some other non-SwiftBar icons in the menu bar too). Plugin position will be remembered unless you change the name of the plugin file, in which case they'll need to be re-positioned again.
Plugin API
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 STDERR.
Plugin API is adopted from the BitBar\xbar, which means that SwiftBar can run any existing BitBar\xbar plugin.
Script Output
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 ---. Each --- after the fiTop issues
#5942.1.2-beta-5 on macOS 27: two-line image rows lose the 2.0.1 layout; crash when launched by a swiftbar:// URL; crash with sfconfig Palette and no colors5 comments · 2026-10-27#599Restore native SF Symbol menu sizing and accept scale-only configuration2 comments · 2026-11-07#598Restore multiline dropdown image layout on macOS 26 and later2 comments · 2026-11-07#572regression: image and templateImage don't respect image sizes (#513)2 comments · 2026-09-28#530#529 bis [Menu item loses image on hover with multiline title, refresh, and alternate sibling]2 comments · 2026-08-14#600Clear false stale warnings immediately after wake with unchanged output1 comments · 2026-11-07#607Shortcut on header works only once when refreshOnOpen is set to true0 comments · 2026-11-12#606Memory grows without bound while a streamable plugin runs0 comments · 2026-11-12
Discussions
#5842.1.2 release ETA0 comments · 2026-10-19#582Stacked info in bar?0 comments · 2026-10-02#552Argus — one menu bar icon to monitor/control local & remote AI services0 comments · 2026-09-10#550Curious about status of feature that let's users add toggles/variables to their scripts via the interface.1 comments · 2026-09-03#545I just want to say thankyou for developing this.0 comments · 2026-08-18#543`sfsize= has no effect as of 2.1.2 — plugins can no longer control SF Symbol size`0 comments · 2026-08-16#542`A way to opt out of highlighting on informational rows`2 comments · 2026-08-16#503When is the next SwiftBar release planned?1 comments · 2026-08-05
Latest release
2.1.1 v2.1.1 2026-08-11SwiftBar 2.1.1 SwiftBar 2.1.1 requires macOS 12 or later. This patch release fixes two regressions introduced in SwiftBar 2.1.0. Fixes Fixed plugins being skipped when the configured plugin directory is the conventional ~/.swiftbar path. 508 510 Restored Base64, template, and color images in dropdown menu items on macOS 26 and later, including correct sizing, appearance, highlighting, and incremental refresh behavior. 507 509 Contributors Thank you to @EhsanAzish80 for the menu-image fix. Full changelog: https://github.com/swiftbar/SwiftBar/compare/v2.1.0...v2.1.1