Specification: signalbox settings

What this is

The settings window as four toolbar panes, plus the hub status light in the jumplist footer. The window title tracks the pane.

• General - three rows in one label column: the menu bar icon, the jumplist shortcut as a live recorder - click it, type a combination, and it applies immediately. It shows standard key glyphs, ⌃⌥J, never the ctrl+alt+j config syntax; clearing it leaves the jumplist reachable only from the menu bar; and the board filter field. The recorder and filter each have a one-line caption.
• Agents - one section per agent, identical verb-first toggles. Sections, not tabs: agents are an open-ended list and the tab strip stays fixed.
• Hub - the mode control first, with Confirm and Cancel beside it while a change is pending, the status pill under it, then the selected mode's caption, sketch and controls. A mode change is pending until Confirm.
• Logs - the hub log path, Copy path, and a Recent events tail.

The mental model

Every mode configures the hub on this machine. That never changes, and the captions say so:

• Local - the hub runs here on loopback, and nothing else can reach it.
• LAN - the same hub, open on your local network, so your phone can connect to it.
• Remote - the same hub, still here, still what your agents report to, but it forwards events to a remote hub. A remote hub can accept forwards from many machines at once, which is why the sketch shows two machines side by side.

The sketches sit below the caption. Every one is built from the same labelled unit: the small boxes are agents and they sit inside a machine frame, with the hub as the dot they report to. One rule carries the rest: the filled dot is the board of record. In Local and LAN it sits on this machine. In Remote each machine's dot goes hollow and the filled one moves to the cloud that they all forward to. Dashed links cross a network, solid links do not.

Changing mode: pending until Confirm

Picking a different mode in the popup changes nothing by itself. The caption, sketch and controls switch to the new mode so you can see what you are choosing, a Confirm and a Cancel button appear beside the popup with the hint under it, and the status pill keeps showing what is actually running. The buttons sit in the popup's row because that is the control that caused the pending change; at the foot of the pane they read as a form submit for everything above them. Confirm writes the settings file and restarts the hub; Cancel puts the popup back to the running mode. This is the standard idiom for a change that interrupts a running service, and it means the window can never half-apply a mode.

• To LAN or Local: Confirm is enabled immediately.
• To Remote: the URL field opens pre-filled with the last address that was confirmed (hub.remoteUrl, which no mode switch clears) and the token field with hub.token; only hub.upstream empties when Local or LAN is confirmed, because that key alone is what makes the hub a forwarder. Fill in the remote hub's URL and token, then Test. Confirm stays disabled until a test passes, so a forwarder is never pointed at an address that has not answered. The test calls the remote hub's /healthz and checks the token against an authenticated route; failures render under the field with the actual reason.

While a change is pending, that mode's own controls are visible but anything that needs the hub to already be in the mode is disabled: Pair a device... greys out under a pending LAN selection, because pairing hands a device the running hub's LAN address and bearer and the hub is still on loopback until Confirm. Its tooltip says why.

The status pill

One line of reality directly under the mode control: a dot, the running mode, and where the hub is, with a short amber suffix when something is wrong. It renders GET /healthz and nothing else - the settings file records what you asked for and is never read to describe what is running. During a pending change or a restart the pill keeps telling the truth about the running hub. The address is monospace and selectable, so it can be copied straight out of the pill. The pill never narrates health in sentences and never counts anything; the popover and the log carry the detail. When the hub does not answer at all, the pill still has to name a mode, so it uses the last mode the hub reported this session, or the settings file as a last resort - intent never describes a hub that IS answering.

The Logs tab

Karabiner-Elements and iTerm2 both put logging in a settings tab, and both are apps whose real work happens in a process the user never sees. Signalbox has the same shape: the app spawns signalbox hub as a child and its output lands in ~/.local/state/signalbox/hub.log. When a board is empty or a phone will not pair, that file is the answer.

The tab is deliberately small. The path is clickable and reveals the file in Finder; Copy path puts it on the clipboard. Recent events is a tail of the last 500 lines in a scrolling monospace view, read when the tab opens and on Refresh - not a live follow, so nothing moves while you read. The tail uses system text colors and follows the light or dark appearance, like Console.app, and it opens scrolled to the newest lines with the start of the line visible, never mid-line. It is a tail, not a viewer: no search, no level filter. Anything deeper is a job for Console or tail -f, and the path is right there.

What this asks of the hub: log lines gain a leading YYYY-MM-DD HH:MM:SS timestamp. Bare untimestamped lines make a tail nearly useless, so that is a required change, not a nice-to-have.

The footer status light

Everyday status does not live in Settings - it is a small light at the left of the jumplist footer, opposite the cog. Three states: Hub healthy (green), Hub warning (amber), Hub starting (grey). The light never names a mode - "Remote" as a status reads as a place, not a health.

Clicking the light opens a popover of facts, not narrative: Mode, Address, Hub version, and in Remote mode the Uplink row with the spool count when events are queuing. Values are monospace and selectable. Two links close it out: Open Settings (the Hub tab) and Open log (the Logs tab). Clicking elsewhere closes it. There are no menu bar menu items for any of this.

Where settings are stored

Writes merge key by key, so unknown keys survive. A missing or broken file falls back to defaults and keeps the hook path working.

The /clear and /rename toggles

Claude Code fires SessionEnd with reason clear on /clear. Checked (default), the session ends and leaves the board. Unchecked, the hook maps it to done so the old session stays listed until you hide it (⌃X), remove it (⌃⌫), or it expires. The Codex pair behaves the same. For scripting, SIGNALBOX_CLEAR_ENDS=0|1 overrides the file. Rename toggles: on, the agent's /rename shows on the board as the session name; off keeps the folder name; your own ⌃R rename always wins.

Every status string