Github url


by matryer

matryer /bitbar

Put the output from any script or program in your Mac OS X Menu Bar

12.9K Stars 529 Forks Last release: almost 4 years ago (v1.9.2) MIT License 658 Commits 26 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

BitBar BitBar

BitBar (by Mat Ryer - @matryer) lets you put the output from any script/program in your Mac OS X Menu Bar.

Digging deeper:

And finally...


Example showing the latest Buy and Sell figures for BitCoins:

BitBar Example showing BitCoins plugin

Click to see the full output, and more options:

BitBar Example showing menu open

Example showing your internal and external IP addresses:

BitBar Example showing IP Addresses

Get started

Installing BitBar

There are two ways to install BitBar on your Mac:

Use Homebrew:

brew cask install bitbar

Or download .app file directly:Get the latest version of BitBar. Then copy it to your Applications folder and run it - it will ask you to (create and) select a plugins folder, do so.

It's free, so please donate

If you love this, any BitCoin donations are most welcome, to


or send something useful (Amazon Wishlist).

Installing plugins

There are two ways to install BitBar plugins on your Mac:

Browse our plugins to find useful scripts, or write your own.

Or just download the plugin of your choice into your BitBar plugins directory and choose


from one of the BitBar menus. Remember to use

chmod +x {pathname}

before you use the plugins. *

  • The pathname of the file

    Configure the refresh time

The refresh time is in the filename of the plugin, following this format:

  • name
    • The name of the file
  • time
    • The refresh rate (see below)
  • ext
    • The file extension

For example:

    would refresh every minute.

Most plugins will come with a default, but you can change it to anything you like:

  • 10s - ten seconds
  • 1m - one minute
  • 2h - two hours
  • 1d - a day

Ensure you have execution rights

Ensure the plugin is executable by running

chmod +x


Using symlinks

Because Git will ignore everything in


, you can use it to maintain your own plugins directory while still benefitting from tracking (upstream) changes.


cd Plugins/Enabled # Enable spotify plugin ln -s ../Music/ # Enable uptime plugin and change update interval to 30 seconds ln -s ../System/

Then select the


folder in your BitBar preferences.

Resetting Plugin Directory

In case you made the mistake of choosing a directory with thousands of files as the plugin directory and BitBar getting stuck forever, do this from terminal to reset it:

defaults delete com.matryer.BitBar


BitBar app

To work on the BitBar app, fork, then clone this repo.

In terminal, navigate to the project directory and run:

git submodule init && git submodule update


  • Special thanks to @muhqu and @tylerb for all their help (see commit history for details)
  • Thanks to Chris Ryer for the app logo - and to @mazondo for the original
  • Thanks for all our plugin contributors who have come up with some pretty genius things

Writing plugins

We're always looking for new plugins, so please send us pull requests if you write anything cool or useful.

Join the conversation with plugin authors and BitBar maintainers on Slack.

Got ideas?

If you've got ideas, or want to report a bug, nip over to our issues page and let us know.

If you want to contribute, please send us a pull request and we'll add it to our repos.

  • Ensure the plugin is executable
  • Be sure to include appropriate Metadata to enhance the plugin's entry on

Plugin API

  • To write a plugin, just write some form of executable script that outputs to the standard output.
  • Multiple lines will be cycled through over and over.
  • If your output contains a line consisting only of

, the lines below it will appear in the dropdown for that plugin, but won't appear in the menu bar itself.
- Lines beginning with 


 will appear in submenus.
  - Use 

 etc. for nested submenus. Two dashes per level of nesting.
- Your lines might contain 


 to separate the title from other parameters, such as...


 to make the item clickable


 to change their text color. eg. 






 to change their text font. eg. 




 to change their text size. eg. 




 to make the item run a given script terminal with your script e.g. 


 if there are spaces in the file path you will need quotes e.g. 

bash="/Users/user/BitBar Plugins/scripts/"



 to specify arguments to the script. additional params like this 

param2=foo param3=bar

 full example 

bash="/Users/user/BitBar_Plugins/scripts/" param1=--verbose

 assuming that is executable or 

bash=/usr/bin/ruby param1=/Users/user/rubyscript.rb param2=arg1 param3=arg2

 if script is not executable


 start bash script without opening Terminal. 






 to make the item refresh the plugin it belongs to. If the item runs a script, refresh is performed after the script finishes. eg. 




 May be set to 




. If 


, the line will only appear and cycle in the status bar but not in the dropdown


 to truncate the line to the specified number of characters. A 

 will be added to any truncated strings, as well as a tooltip displaying the full string. eg. 




 whether to trim leading/trailing whitespace from the title. 




 (defaults to 




 to mark a line as an alternate to the previous one for when the Option key is pressed in the dropdown


 set an image for this item. The image data must be passed as base64 encoded string and should consist of only black and clear pixels. The alpha channel in the image can be used to adjust the opacity of black content, however. This is the recommended way to set an image for the statusbar. Use a 144 DPI resolution to support Retina displays. The imageformat can be any of the formats supported by Mac OS X


 set an image for this item. The image data must be passed as base64 encoded string. Use a 144 DPI resolution to support Retina displays. The imageformat can be any of the formats supported by Mac OS X


 will disable parsing of github style 


 into :mushroom:


 turns off parsing of ANSI codes.

### Metadata

To enhance your entry on [](, add the following metadata to your source code (usually in comments somewhere):

<bitbar.title>Title goes here</bitbar.title># <bitbar.version>v1.0</bitbar.version># <>Your Name</># <>your-github-username</># <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></bitbar.abouturl>

- The comment characters can be anything - use what is suitable for your language


 - The title of the plugin


 - The version of the plugin (start with 



 - Your name

 - Your github username (without 




 - A short description of what your plugin does


 - A hosted image showing a preview of your plugin (ideally open)


 - Comma separated list of dependencies


 - Absolute URL to about information

For a real example, see the [Cycle text and detail plugin source code](

### Useful tips

- If you're writing scripts, ensure it has a [shebang]( at the top.
- You can add to 


 by including something like 

export PATH='/usr/local/bin:/usr/bin:$PATH'

 in your plugin script.
- You can use emoji in the output (find an example in the Music/vox Plugin).
- If your bash script generates text in another language, set the 


 variable with: 

export LANG="es_ES.UTF-8"

 (for Spanish) to show the text in correct format.
- If you want to call the plugin script for action, you can use 


- If your plugin should support Retina displays, export your icon at 36x36 with a resolution of 144 DPI (see [this issue]( for a more thorough explanation).

### Examples

#### One line plugin

#!/bin/bash date

#### Multi-line plugin

#!/bin/bash # the current date and time date # the current username echo $USER # the current user id id -u

#### Multi-line plugin with extra data

#!/bin/bash echo "One" echo "Two" echo "Three" echo "---" echo "Four" echo "Five" echo "Six"

- Only One, Two and Three will appear in the top bar
- Clicking the plugin menu item will show all lines

#### Multi-line plugin with links and colors

#!/bin/bash curl -m 1 -I >/dev/null 2>&1 [$? -gt 0] && echo "FAIL | color=red" || echo "OK | color=green" echo "---" echo "Show Graphs | color=#123def href=" echo "Show KPI Report | color=purple href="

#### Multi-line plugin with fonts and colors

![BitBar Example showing colored fonts](

#!/bin/zsh FONT=( 'size=14' 'font=UbuntuMono' ) if ((0)); then echo "DO | $FONT color=orange" else echo "DO | $FONT color=cadetblue" echo "---" ...

### Tested languages

Anything that can write to standard out is supported, but here is a list that have been explicitly tested.

1. Ruby
  - Status: Working
  - Output: 

puts "your string here"

2. Python2
  - Status: Working
  - Output: 

print "your string here"

3. Python3
  - Status: Working
  - Output: 

print("your string here")

  - Caveats: To output unicode shebang has to be in the format 

#!/usr/bin/env PYTHONIOENCODING=UTF-8 /path/to/the/python3

4. JavaScript (


  - Status: Working
  - Caveats: Shebang has to be in the format 

#!/usr/bin/env /path/to/the/node/executable

  - Output: 

console.log("your string here")

  - Notes:


 doesn't output desired text.
    - There may be a better way to run JavaScript files.
  - Tips:
    - Use the Node.js [


 module]( to simplify plugin creation.
5. CoffeeScript (


  - Status: Working
  - Caveats:
    - Shebang has to be in the format 

#!/usr/bin/env /path/to/the/coffee/executable



 shebang also had to be modified.

#!/usr/bin/env /path/to/the/node/executable

  - Output: 

console.log "your string here"

  - Notes:


 doesn't output desired text.
    - There may be a better way to run CoffeeScript files.
6. Swift (Interpreted)
  - Status: Working
  - Output: 

print("your string here")

7. Swift (Compiled)
  - Status: Working
  - Caveats: You still need a file extension (


  - Output: 

print("your string here")

  - Notes:
    - To compile a swift file, use: 

xcrun -sdk macosx swiftc -o file.1s.cswift file.1s.swift

8. Go (Interpreted)
  - Status: Working
  - Caveats:
    - Your script's shebang must be: 

//usr/bin/env go run $0 [email protected]; exit



 must be in your 


  - Output: 

Println("your string here")

9. Go (Compiled)
  - Status: Working
  - Caveats: You still need a file extension (


  - Output: 

Println("your string here")

  - Notes
    - To compile a Go file, use: 

go build file.1s.go

10. Lisp
  - Status: Working
  - Caveats: 




 must be in your 


  - Output: 

(format t "your string here")

11. Perl5
  - Status: Working
  - Output: 

print "your string here"

  - Notes
    - Add 


 to shebang to automatic add newline to print function: 

#!/usr/bin/perl -l

12. PHP
  - Status: Working
  - Output: 

echo 'your string here'

  - Notes
    - Add shebang 



We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.