gammonview-helper

Analyze your backgammon matches on your own computer, and see the results on gammonview.com.

GammonView analyses matches on a shared server. That server is shared, so the deepest settings are not on its menu — a World Class run that takes a minute on your laptop would take an hour of a queue everybody else is waiting in. The helper moves that work to your machine: you keep using the website exactly as before, and the analysis happens at home.

Nothing listens on a port. The helper dials out to gammonview.com, waits for work you queued from your own browser, runs it, and sends the result back. There is no inbound connection, no router setting, no firewall rule.

Install

Needs uv (or pipx, or a plain pip install into a virtualenv).

uv tool install gammonview-helper

That pulls in the analysis engine and its neural networks — about 80 MB, and it takes a minute or two the first time. Update later with gammonview-helper update (below).

Two other forms, for whoever prefers them:

# the exact wheel from a release, no index involved. Pinned by definition:
# re-run it with a newer version to upgrade, since `uv tool upgrade` has
# nothing to ask about a package installed from a URL
uv tool install https://github.com/ngvlamis/gammonview-helper/releases/download/v0.1.1/gammonview_helper-0.1.1-py3-none-any.whl

# straight from a tag — needs `git`, and builds from source rather than
# installing the wheel that was tested
uv tool install git+https://github.com/ngvlamis/gammonview-helper@v0.1.1

Link this computer

gammonview-helper link

It prints a word and opens your browser. Sign in if you are asked, and pick the word it printed out of the three you are shown. You will get an email saying the computer was linked.

If the three words do not include the one on your screen, something is wrong — close the page and start again. That is the check working.

Run it

gammonview-helper run

Leave it running. Analyses you start on gammonview.com will now go to this computer, and the deeper presets appear in the menu. If the helper is not running, the website falls back to the shared server on its own — you never get an error for having closed it.

You can start it before linking. An unlinked helper waits for a credential rather than giving up, so the usual order — install, let it start, then link in the browser — needs no third step telling it to look again; it picks the link up within a few seconds. The same is true if you unlink and re-link later.

The menu-bar item (macOS)

On a Mac, run puts a doubling cube showing 2 in the menu bar. Its menu says what the helper is doing — ready, analysing (with a percentage beside the icon), paused, or not linked — and which account it is linked to, and has these controls:

• Pause / Resume. A match already being analysed finishes first; after that the helper takes no more until you resume. The website stops offering this computer at once, and sends your analyses to the shared server instead.
• Open GammonView.
• Link This Computer… — while it is not linked. Opens the browser and shows the word to pick in a dialog, exactly as link does in a terminal. Once linked, the same place offers Unlink This Computer…, which asks first and does what unlink does. Not while a match is being analysed.
• Update to … — only when gammonview.com offers a newer helper. Installed by the installer or with uv tool, it updates itself and restarts; installed any other way (pipx, a checkout), it tells you to update it the same way.
• About GammonView Helper, with the version.
• Quit GammonView Helper. Asks first, then stops it until you next log in or open the app below. A match being analysed at that moment is stopped, and the website says why.

run --no-menu leaves the item out. It is never shown over SSH.

Run as the login item, the helper also keeps GammonView Helper in Applications (in ~/Applications if it cannot write to /Applications). Opening it starts the helper again after a Quit, or says it is already running. It is written on the Mac itself rather than downloaded, so it opens with no Gatekeeper warning, and the installer's Remove deletes it.

Keeping it running (macOS)

run stops when you close the terminal. To have it start at login and stay up:

deploy/install-login-item.sh

That registers a launchd agent pointing at the installed gammonview-helper, logging to ~/Library/Logs/GammonView/helper.log. Re-run it after an upgrade — it boots the old job out first, so you never end up with two pollers sharing one worker id, and it keeps whatever site the installed agent already pointed at. To move a machine between sites, say so explicitly:

GAMMONVIEW_SITE=https://gammonview.com deploy/install-login-item.sh

It says when it moves one, because a credential is per site: the machine has to be linked to the new one separately.

deploy/install-login-item.sh stop     # stop it, and leave it stopped
tail -f ~/Library/Logs/GammonView/helper.log

Installing always leaves the helper running, so a stop does not survive the next install. After stopping, the website keeps saying Connected for up to two minutes — a helper stops by going quiet, and the relay waits that long before believing a silence.

The eventual installer does this for you; the script exists because the machine this is developed on needed it first, and deploy/com.gammonview.helper.plist records the four choices in it that are not boilerplate.

The other commands

gammonview-helper update     # install the version gammonview.com has released
gammonview-helper status     # what is configured, and is the link still alive
gammonview-helper unlink     # unlink this computer from its account

update installs exactly the version gammonview.com offers, not simply the newest on PyPI, and on a Mac restarts the login item onto it. Elsewhere, stop the running helper and start it again afterwards. It works for an installer install and a uv tool one; for anything else it says to update the way you installed it.

unlink does both halves: it tells the site to drop this computer, then forgets the credentials here. If it cannot reach the site it still forgets the credentials and says so, so use Unlink in your account settings to finish. --local-only skips the site entirely.

The helper still cannot reach your account — a worker credential is refused by every route that takes a sign-in. The one exception is the route that unlinks the caller itself, which names no computer and so cannot name another one.

Uninstalling

Remove the login item, the directory, and the account row:

gammonview-helper unlink                      # the account row, and the credentials
launchctl bootout gui/$(id -u)/com.gammonview.helper   # macOS login item
rm ~/Library/LaunchAgents/com.gammonview.helper.plist
rm -rf ~/Library/"Application Support"/GammonView

Order matters: unlink spends the credential that the last line deletes.

Installed with the macOS installer app instead? Open it again and press Uninstall — it does all four, in that order.

Settings

Everything lives in one directory:

The credential is kept in your platform's credential store (Keychain, Credential Manager, Secret Service), not in that directory. status says which store it actually got — on a machine with no credential store it falls back to a 0600 file, and tells you so.

config.json takes a few optional keys:

The parallelism is sized by the engine, from measurements it keeps for the purpose; set either to a number if you want a hard cap, and it will be kept. nice is what makes the helper something you forget is running — it yields to whatever you are actually doing, and every engine worker inherits it.

Licence

MIT. The engine (bgsage) is MPL-2.0 and is installed as an ordinary dependency.

Development

uv run pytest -q -m "not slow and not contract"

Two markers are deselected there. slow runs a real analysis and needs a minute of CPU. contract talks to a live relay and is opt-in:

GAMMONVIEW_CONTRACT_BASE=https://beta.gammonview.com uv run pytest -m contract

The other end of that protocol — the relay itself — is part of the gammonview.com service and is not open source. docs/Relay.md documents the seam from this side, says which revision this client implements, and explains why the contract carries a number of its own.