JankyBorders: a macOS window border daemon for yabai and AeroSpace users

What JankyBorders is for, and who it is not for

JankyBorders is a lightweight tool that adds colored borders to user windows on macOS 14.0 and later. Its stated purpose is to visually highlight the currently focused window. The README puts the design claim plainly: it does this "without relying on the accessibility API, thereby being faster than comparable tools." That sentence is the whole pitch, and it also defines the audience.

If you run a tiling window manager on macOS, the focused window is not always obvious. Tiles sit flush against each other, shadows are often disabled to save space, and the title bar may be hidden. A one-pixel or five-pixel colored outline is the cheapest way to answer the question "where is my keyboard input going?" JankyBorders answers that question and does nothing else. It does not tile windows, it does not move them, and it does not read window contents.

That narrowness is why it is the wrong tool for most macOS users. If you use the default window manager and drag windows around by hand, the title bar already tells you which window is focused. If you are on macOS 13 or earlier, the tool does not apply at all. And if you arrived here from a search about window borders on Windows 11, this project has nothing to offer you: it is a macOS-only C program, and the README makes no mention of any other platform.

How the border is drawn without the accessibility API

The repository is small: a makefile, a src/ directory, docs/, images/, and a LICENSE file. The primary language is C. The README does not describe the internal architecture, so the mechanism has to be inferred from what the documentation does say and what it deliberately avoids.

The README's central claim is the negative one: JankyBorders does not rely on the accessibility API. On macOS, the accessibility API is the sanctioned way for one process to inspect and manipulate other applications' windows, and it is also the usual source of latency and permission prompts in tools of this kind. Avoiding it means JankyBorders cannot read window titles or control window geometry, which is exactly why it pairs with a window manager rather than replacing one. The window manager owns layout; JankyBorders owns the outline.

The process model is documented. A borders process runs in the background, and the README states that invoking a new borders instance with any combination of available options will update the properties of the already running instance. So the running daemon holds the border state, and each invocation of the binary is a message to that daemon, not a new process. This is what makes runtime restyling cheap: you change a color by running the command again, and the existing borders redraw.

Configuration also has two paths. You can pass options directly on the command line when starting the process, or you can let the primary process read a file. The README says that if the primary borders process is started without any arguments, or launched as a service by brew, it searches for ~/.config/borders/bordersrc and executes it on launch if found. That file is a shell script, not a declarative config format, which is a deliberate trade-off: it gives you variables and loops, but it also means a broken bordersrc is a shell error rather than a schema validation failure.

Installing JankyBorders with Homebrew and drawing your first border

The README gives Homebrew as the install path. You tap the author's formulae repository and then install the borders formula:

brew tap FelixKratz/formulae
brew install borders

After that, the binary is on your PATH as borders. The README points to man borders for a comprehensive overview of all available options and commands, and notes that a rendered version of the man page lives in the project wiki. Read that page before you start guessing at flag names, because the README itself only demonstrates a handful of options.

The first real use is to start the process with an active and inactive color and a width. The README's yabai example is:

borders active_color=0xffe1e3e4 inactive_color=0xff494d64 width=5.0 &

The README suggests adding that line to the very end of your yabairc, which starts borders alongside yabai. The trailing ampersand matters: without it you block the shell that launched the window manager.

If you use AeroSpace instead, the README shows a TOML entry in aerospace.toml that runs the same command through exec-and-forget:

after-startup-command = [
  'exec-and-forget borders active_color=0xffe1e3e4 inactive_color=0xff494d64 width=5.0'
]

If you would rather not tie borders to a window manager's startup, the README offers a third path, running it as a separate service:

brew services start borders

A service started this way gets no arguments, which means it will look for ~/.config/borders/bordersrc. The README's example of that file sets style, width, hidpi, and both colors, then invokes the binary with the array:

#!/bin/bash

options=(
	style=round
	width=6.0
	hidpi=off
	active_color=0xffe2e2e3
	inactive_color=0xff414550
)

borders "${options[@]}"

The README notes that the appearance can be adapted at any point in time, so you do not need to restart anything to try a new color: run borders with the changed option and the running instance picks it up.

Where JankyBorders stops being the right choice

The macOS 14.0 floor is the first hard limit. The README states the tool is designed for macOS 14.0+, and there is no documented fallback for older releases. If you are pinned to an earlier version for hardware or compatibility reasons, this project is simply unavailable to you.

The second limitation is that JankyBorders has no opinion about which window should be focused. It draws a border around whatever the system considers focused. If your window manager is misconfigured, or if focus follows the mouse in a way you did not intend, the border will faithfully highlight the wrong window. Debugging that is a window manager problem, not a borders problem, and the README does not offer diagnostics for it.

The third is the configuration surface. Options are passed as bare key=value tokens on the command line, and the bordersrc file is executed as a shell script. There is no documented validation step and no documented way to query the running instance's current state. If a border fails to appear, the README does not describe a log file, a verbose mode, or a status command you can run to see what the daemon thinks its settings are. You are left comparing your invocation against man borders.

Finally, the project is not a window manager and does not pretend to be. Anyone hoping to replace yabai with it will be disappointed: it has no layout engine, no window rules, and no concept of a workspace.

JankyBorders compared with the accessibility-API approach

The natural alternative to JankyBorders is a border implementation built on the macOS accessibility API, which is how many window-management utilities observe and annotate other applications' windows. The difference is not cosmetic. An accessibility-based tool asks the system for permission to inspect other processes, and it pays for that access with the latency of cross-process queries. JankyBorders's README frames its own design as the opposite: no accessibility API, therefore faster than comparable tools.

That trade has a cost on the other side. An accessibility-based tool can read window titles, so it can color a border based on which application is focused, or apply per-application rules. JankyBorders, by avoiding the API, gives up that information. Its two documented color options are active_color and inactive_color: focused and not focused. There is no documented per-application coloring. If your workflow depends on distinguishing windows by title or by app, an accessibility-based tool is the better fit, and you should accept the permission prompt and the overhead that come with it.

A second comparison is with the window manager itself. yabai and AeroSpace both manage window placement, and both are documented in the JankyBorders README as launch partners. Neither ships a border feature that JankyBorders duplicates; the README treats them as the thing that starts borders, not as competitors. The practical question is therefore not "borders or yabai" but "do I want an outline on top of the layout my window manager already produces."

Maintenance, licensing and the cost of upgrading

The repository is not archived. The last push was on 2026-05-14, which is the same date as the v1.9.0 release. Before that, v1.8.4 was released on 2025-09-17 and was labelled "macOS 26 Compatibility," and v1.7.0 on 2024-11-18. That release spacing is worth reading carefully: roughly seven months passed between v1.8.4 and v1.9.0, and about ten months between v1.7.0 and v1.8.4. This is a project that moves in bursts, often in response to macOS changes, rather than one that ships continuously. Plan for that rhythm. A macOS point release that changes how windows are composited is exactly the kind of event that produces a compatibility release here.

The upgrade cost is low by design. Installation is a Homebrew formula, so brew upgrade borders is the mechanical step, and because appearance options can be changed at runtime, a version bump does not force you to rewrite your bordersrc. The risk sits in the undocumented internals: the README does not guarantee option stability across versions, and since the tool avoids the accessibility API, a macOS change to the underlying window server behaviour can break it in a way that no configuration change fixes. The v1.8.4 release name suggests the maintainer tracks those changes, but it also shows the dependency.

The licence is GPL-3.0, as stated in the LICENSE file at the repository root. That is a copyleft licence. If you are a normal user running the brew formula on your own machine, this is not something you need to think about. If you intend to redistribute a modified binary, or to link the code into a product you ship, GPL-3.0 carries obligations that permissive licences do not, and you should read the licence text in the repository rather than rely on a summary. This is not legal advice.

Editorial conclusion

Adopt JankyBorders if you already run yabai or AeroSpace on macOS 14.0 or newer and want a focused-window indicator that does not touch the accessibility API. Skip it if you are on an older macOS release, if you want a border tool that manages windows itself, or if you are looking for a Windows 11 customization utility, which this is not. Before installing, confirm your macOS version meets the 14.0 floor and read man borders for the full option list, since the README only shows a subset.

Frequently asked questions

Official sources

1. FelixKratz/JankyBorders on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases