User programmable screen overlay using web technologies

• Display information and always-on-top widgets
• Use HTML/JS/CSS to draw on your screen
• Edit source, hit save, screen will update
• Extensible with shell scripts in any language
• Less than 400 lines of Go code, minimal deps
• Currently alpha, macOS only ...

First, download Go 1.16+ or brew install go. If already installed, make sure it is version 1.16 or greater:

$ go version
go version go1.16.2 darwin/amd64

Then use go get to download, build, and install the topframe binary into a directory in your PATH by setting GOBIN:

$ GOBIN=/usr/local/bin go get github.com/progrium/topframe

Currently, this is the preferred way to install as anything else requires a much more elaborate release process with Apple code signing, etc. Specifying GOBIN is optional, but lets you specify where to install the binary, ensuring it is put in your PATH.

$ topframe
Usage: topframe <flags> <subcommand> <subcommand args>

Subcommands:
        agent            fullscreen webview overlay agent
        docs             open documentation in browser
        help             describe subcommands and their syntax
        version          show version

Running topframe agent will create a ~/.topframe directory with a default index.html used for the overlay. A new menu bar extra will let you enable or disable the overlay, make it interactive for debugging and bringing up devtools, and quickly open the ~/.topframe directory to edit source. Files changed in the directory will trigger a reload, so if you edit index.html and hit save, changes will reflect immediately.

Topframe works with launchd to run as an agent on startup. You can generate an agent plist file with topframe agent -plist, which you can write to a file in ~/Library/LaunchAgents:

$ topframe agent -plist > ~/Library/LaunchAgents/com.progrium.Topframe.plist

It's a good idea to view the output before writing to the file, just to make sure paths are correct. If you don't know what is correct, it's probably fine!

There is not a whole lot to Topframe! I recommend reading the source as its only a few hundred lines, but otherwise there is a wiki ready to document anything else.

If you're having trouble, be sure to check issues to see if its a known issue. Otherwise, feel free to drop a question into the discussion forum.

Ideally, Topframe is kept small. Bug fixes and other small PRs are welcome and should be merged quickly. If you happen to have a large PR that we haven't discussed, you should talk about it in the forum first. In order to keep the project small, some features suggestions may be held back in favor of determining a good extension point to expose instead.

Topframe started as a 130 line example for progrium/macdriver.

MIT Licensed