Topframe

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 ...

Getting Started

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 lets you say where to install the binary, ensuring it is put in your PATH, but is optional if Go is more setup.

$ 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

To start it and show the demo webpage overlay, run topframe agent. This will also:

• create a ~/.topframe directory with a demo index.html used for the overlay
• watch for file changes in ~/.topframe to trigger a page reload
• add a menu bar extra (🔲) to control the overlay

If you edit ~/.topframe/index.html and hit save, changes will reflect immediately. If you hate the demo content of the default index.html, change it! Use Show Source... from the menu extra to quickly open your topframe directory.

Launching on Startup

Topframe works with launchd to run as a background 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!

Documentation

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.

Getting Help

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.

Contributing

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.

About

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

MIT Licensed