# Rig Pocket

A phone-friendly status page and push notifier for [OpenRig](https://openrig.dev) teams.
The OpenRig TUI is great on a laptop and hard to use on a phone; Rig Pocket gives the same overview
as an installable web app (PWA):

- every rig and seat, with **working / idle / waiting for an answer**
- open and recently finished queue items
- the latest commits on every branch of the repositories your teams work in
- **questions from the agents, answered right on the page:**
  - menus and permission prompts are read off the seat's screen and shown as labelled buttons (plus Esc)
  - an agent that stopped with a question gets a reply box
  - queue items blocked on a human seat are decisions, recorded with `rig queue resolve` so the owner wakes up
- tap a seat to see its screen (refreshes every 5 s) or type a message to it
- optional push notifications through [ntfy](https://ntfy.sh): new commits, a seat waiting for an answer
  (only if it is still waiting on the next poll), a new request to the operator, a lead's task finished

It reads everything through the documented `rig` CLI (`--json`), so it does not depend on daemon internals.
Python 3 standard library only, no build step.

## Run

Run it as the same user as the OpenRig daemon, next to it:

```sh
RIG_POCKET_REPOS="~/work/*" python3 server.py   # listens on 127.0.0.1:7440
python3 -m unittest                           # tests
```

`rig-pocket.service` is an example systemd unit.

| Variable | Default | |
|---|---|---|
| `RIG_BIN` | `rig` | path to the rig CLI |
| `RIG_POCKET_BIND` / `RIG_POCKET_PORT` | `127.0.0.1` / `7440` | listen address |
| `RIG_POCKET_POLL` | `30` | seconds between snapshots |
| `RIG_POCKET_REPOS` | (none) | space separated globs of git work trees to show commits from |
| `RIG_POCKET_ORIGIN` | (none) | if set, POSTs must come from this origin, e.g. `https://rig.example.com` |
| `RIG_POCKET_URL` | (none) | where tapping a notification opens |
| `RIG_POCKET_THEME_CSS` / `_JS` | weirsoe-theme on assets.weircon.dk | stylesheet and script of the design system |
| `NTFY_URL` / `NTFY_TOPIC` / `NTFY_TOKEN` | (none) | ntfy server, topic and access token; unset = no push |
| `RIG_POCKET_DONE_DEST` | `^orch-lead@` | regex: notify when a task to such a seat closes |
| `RIG_POCKET_HUMAN_DEST` | `^operator-agent@kernel$` | regex: notify when such a seat gets a new task |
| `RIG_POCKET_HUMAN_SEATS` | `^operator-human@` | regex: human seats (not scanned for prompts; items blocked on them are decisions) |
| `RIG_POCKET_HUMAN_SEAT` | `operator-human@kernel` | the seat a decision is recorded as |

## Security

Rig Pocket can type into your agents, and OpenRig agents usually run without permission prompts.
**Never expose it without authentication.** Put it behind a reverse proxy with single sign-on (forward auth)
and, ideally, an IP allow list, and keep it bound to localhost. Write requests need a custom header
(which forces a CORS preflight) and, with `RIG_POCKET_ORIGIN`, a matching `Origin`. Seat names are checked
against the current snapshot before anything is passed to `rig`, and arguments are never run through a shell.

The page is served with a strict Content Security Policy: scripts and styles only from itself and the theme host,
no inline scripts, `connect-src 'self'`.

## Look

The page uses only classes from the shared [weirsoe-theme](https://gitea.weircon.dk/agw/Weircon-wind) design system
(`.wt-card`, `.wt-tag--warn`, `.wt-pre`, `.wt-row`, …) and has no stylesheet of its own. Point the two theme variables
at your own copy to re-skin it.

## License

MIT