Webpage screen overlay using web technologies
- Customize your computing experience with webdev
- Display information and always-on-top widgets
- 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
lets you say
where to install the binary, ensuring it is put in your PATH
, but is optional if Go is more setup.
$ topframe -h
Usage: topframe <flags>
Topframe is a fullscreen webview overlay agent
Flags:
-docs open documentation in browser
-help show help
-plist generate launch agent plist
-version show version
To start it and show the demo webpage overlay, simply run topframe
. This will also:
- create a
~/.topframe
directory with a demoindex.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.
Topframe works with launchd
to run as a background agent on startup. You can generate
an agent plist file with topframe -plist
, which you can write to a file in ~/Library/LaunchAgents
:
$ topframe -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