CLI tool
tonsky/AnyBar avatar
tonsky/AnyBar

AnyBar: a UDP datagram on port 1738 becomes a dot in your menubar

OS X menubar status indicator

6,037 stars157 forksObjective-CEPL-1.0

At a glance

What is it?
AnyBar is a macOS menubar indicator that draws one colored dot and changes it when it reads a name out of a UDP packet. That is the entire feature set, which is why a dozen language libraries and four other dot tools speak the same protocol.
Who is it for?
Adopt AnyBar if you want a build or test loop to show state without writing a menubar app: install the cask, launch it with `open -a AnyBar`, and end your script with one `echo -n green` to port 1738. Skip it if you need more than a dot, since the README documents no configuration file and the socket sends no reply, and every setting is an environment variable read at launch.
Can I use it commercially?
Yes, with conditions. EPL-1.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly Objective-C, 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.

From daily snapshots

Star history

  • tonsky/AnyBar6,037 ★ · -6
Star history
Repository2026-09-232026-11-15
tonsky/AnyBar6k6k

-6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A UDP packet on port 1738 is the whole control surface

Every AnyBar instance listens on a UDP port, 1738 by default, and reads the name of an image out of whatever arrives. There is no HTTP server, no handshake and no reply, so the client writes one datagram and the menubar changes. Launch the app before sending anything, then talk to it with netcat:

sh
open -a AnyBar
echo -n "black" | nc -4u -w0 localhost 1738

The `-n` keeps the newline out of the packet and `-4u` forces IPv4 UDP. Bash can write the same datagram without netcat:

sh
bash -c 'echo -n "black" > /dev/udp/localhost/1738'

Thirteen names are built in: nine colors from `white` through `black`, the two glyphs `question` and `exclamation`, and the two fill styles `filled` and `hollow`. `quit` is the odd one out, since it shuts the app down instead of drawing.

The cask and the 0.2.3 zip produce the same app, and both need a launch

Two routes to the binary. One is the release zip for version 0.2.3, the other is a Homebrew cask, and the cask is one command:

sh
brew install --cask anybar

Installation is the easy part. The interesting detail is that installing is not running: the port only exists while the process is alive, so `open -a AnyBar` is a mandatory step before any datagram lands. The shortest useful loop is therefore a build script that ends with a colour change, and the shortest client is short enough to inline:

sh
function anybar { echo -n $1 > /dev/udp/localhost/${2:-1738}; }

That second argument is the useful part. Instances are told apart by port rather than by name, so `anybar green 1739` addresses a different dot without changing the environment of anything.

Only filled and hollow survive a Big Sur menubar change

`black` and `white` always draw with black or white fill, which is a problem on Big Sur, where the menubar text color depends on the wallpaper. A black dot on a dark menubar simply disappears.

`filled` and `hollow` exist for that case and are inverted when the menubar changes its appearance, which keeps the dot legible in both states. The README singles out only `black` and `white` as always drawing with a fixed fill. That is the whole reason to choose between them, and it is a visual decision rather than a functional one: the pair that inverts is the pair that keeps working, and the two extremes are the two to avoid when the background is not yours.

ANYBAR_PORT and open -na give you one dot per project

Several instances can run at once as long as each listens on its own port, which takes one environment variable and the `-na` flags:

sh
ANYBAR_PORT=1738 open -na AnyBar
ANYBAR_PORT=1739 open -na AnyBar
ANYBAR_PORT=1740 open -na AnyBar

A title distinguishes them in the menubar, and an initial color closes the window between launch and the first packet your build script sends:

sh
ANYBAR_PORT=1738 ANYBAR_TITLE=First  open -na AnyBar
ANYBAR_PORT=1739 ANYBAR_TITLE=Second open -na AnyBar
sh
ANYBAR_INIT=blue open -na AnyBar

All three are read at launch, on the open command line. The README documents no configuration file or preference pane; the top level of the repository is `AnyBar.xcodeproj/`, `AnyBar/`, `Tests/`, `CHANGELOG.md`, `LICENSE`, `README.md` and two png files. State lives in the environment, which makes a dot trivial to script and means changing a title or a port means starting a new process.

A png in ~/.AnyBar becomes a command name at 19 or 38 pixels

AnyBar looks in the `~/.AnyBar` directory and treats what it finds as commands of its own. A file called `[email protected]` means a packet containing `square` swaps the built-in dot for that image, so a project can invent states the thirteen built-ins never covered, building or blocked or flaky, without patching the app.

Two sizes are expected: 19×19 pixels for standard resolution and 38×38 pixels for retina, written as `@2x` in the filename. Anything else is not described. The README states those two sizes and stays silent about what happens to an image that does not match, so a wrong-size file is a question you answer by looking at the menubar rather than by reading an error.

Four other dot tools and a dozen client libraries share this port

The port is not private. Projects named alongside it are limpbrains/somebar for Ubuntu Unity, enkore/i3pystatus for i3wm, PavelStefanov/NoteBar for Windows 10 and an Emacs package, emybar.el.

Client libraries exist for Go, Node, Python, Rust, PHP, Java, Ruby, Nim, Erlang, C, C#, Crystal and Emacs, with completion for zsh and fish, plus integrations for webpack build status, boot-clj, an IntelliJ IDEA plugin and ipython/jupyter. Each one wraps the same packet. AppleScript is the exception that shows the app is scriptable a second way, through its own dictionary rather than the socket:

applescript
tell application "AnyBar" to set image name to "blue"

tell application "AnyBar" to set current to get image name as Unicode text
display notification current

The `set image name to` line is the same operation as an echo to 1738, and the next two lines read the state back, which the UDP path cannot do because nothing is ever returned.

Release 0.2.3 is from 2021 while master moved in 2026

The three most recent releases are 0.2.3 on 2021-02-18, 0.2.2 on 2020-11-03 and 0.2.1 on 2020-08-28. The last push to the default branch, master, was on 2026-03-21. Those two facts describe different code: the README's download link is the 0.2.3 zip from 2021, and anyone building `AnyBar.xcodeproj/` gets whatever master holds now. `CHANGELOG.md` sits at the top level next to `Tests/`, so the release history and the test target are both in the repository, but the release line and the source line have drifted apart and nothing in the README says which one the project intends to support.

The licence is the Eclipse Public License, with copyright dated 2015 to Nikita Prokopov. That distinction matters more here than it would for a library: patching the Objective-C source and shipping an app is a different position from sending six bytes to a localhost port, and the file to read for the first case is `LICENSE`.

Editorial conclusion

Adopt AnyBar if you want a build or test loop to show state without writing a menubar app: install the cask, launch it with `open -a AnyBar`, and end your script with one `echo -n green` to port 1738. Skip it if you need more than a dot, since the README documents no configuration file and the socket sends no reply, and every setting is an environment variable read at launch. Check two things first: the newest release is 0.2.3 from 2021-02-18 while the last push to master was 2026-03-21, so the latest release and the source tree are not the same code, and the only styles that survive a Big Sur wallpaper change are `filled` and `hollow`.

Frequently asked questions

How do I install AnyBar and change the dot color on macOS?

Run `brew install --cask anybar`, launch the app with `open -a AnyBar`, then send a color name such as `red` to UDP port 1738 with `echo -n "red" | nc -4u -w0 localhost 1738`. The app has to be running before any packet has an effect.

How do I run more than one AnyBar dot at a time?

Start one instance per port with the ANYBAR_PORT environment variable and `open -na AnyBar`, for example `ANYBAR_PORT=1739 open -na AnyBar`. ANYBAR_TITLE labels the dot and ANYBAR_INIT sets its initial color. All three are read at launch.

Can AnyBar show my own images instead of the built-in colors?

Yes. AnyBar detects images in the `~/.AnyBar` directory and treats the filename as a command name, so `~/.AnyBar/[email protected]` is shown by sending `square` to the port. Images should be 19×19 pixels, or 38×38 for retina.

Which AnyBar commands are not color names?

Beyond the nine colors there are the glyphs `question` and `exclamation`, the fill styles `filled` and `hollow`, and `quit`, which shuts the app down. `filled` and `hollow` invert themselves when the menubar appearance changes, which the fixed colors do not.

Does AnyBar work outside macOS?

AnyBar itself is a macOS menubar app, but the same UDP port convention is used by other indicator projects: somebar for Ubuntu Unity, i3pystatus for i3wm, NoteBar for Windows 10 and an Emacs package. Clients for those platforms exist separately.

Official sources

  1. Issues
  2. License: EPL-1.0
  3. README
  4. Releases
  5. tonsky/AnyBar on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tonsky-anybar.svg)](https://hysenlabs.com/projects/tonsky-anybar)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tonsky-anybar.svg)](https://hysenlabs.com/projects/tonsky-anybar)

Was this useful?