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
go get to download, build, and install the topframe binary into a directory in your
PATH by setting
$ 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
$ 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
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.
Launching on Startup
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
$ 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!
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.