PhoneBox

Phone…

Pages

Each page is a 12 × 6 grid of widgets. Pick a page on the left, arrange its widgets on the phone below and set their options. Drag pages to reorder them; the first one is the home page the panel returns to when idle. On the phone, swipe, use the volume keys, or tap the dots (or long-press a page) for an overview of all pages.

Shortcuts

The keys shown by Shortcut grid and Big button widgets. Click a key to edit it, drag to reorder. The phone only sends the key's id; commands never leave this computer.

Rules

Let the panel react to what happens on this computer: show the AI page when Claude needs you, the music page when something plays, an "on air" sign during calls. A rule fires when its condition starts; with only while it lasts the phone goes back to where it was (and a pushed value is removed) when the condition ends.

Add a rule

Page switches count down on the phone and wait while you use it (General › Page switching).

General

Weather, night mode, display behaviour and the phone connection.

Weather

Calendars

For the Agenda widget and calendar rules. Paste an iCalendar (ICS) address: Google Calendar › Settings › your calendar › Secret address in iCal format; Outlook › Settings › Calendar › Shared calendars › Publish a calendar (ICS link); iCloud › share as a public calendar (webcal:// works). The addresses stay on this computer.

Home Assistant

For the Home Assistant widget. Create a token in Home Assistant › your profile › Security › Long-lived access tokens. The token stays on this computer; the phone only sees the entities its widgets list. (Home Assistant can also push values and notifications to the panel, see Webhooks.)

OBS Studio

Connect to OBS (for the OBS widget, the On air widget and rules)

In OBS: Tools › WebSocket Server Settings › Enable WebSocket server; copy the password from Show Connect Info.

Night mode

Dim the screen at night and show only the clock

Display

You design pages in landscape; in portrait the panel arranges the widgets by itself, top to bottom. Tablets use the same pages, just bigger.

Page switching

How rules, webhooks and the idle return change the page. Instead of jumping, the phone shows “Claude needs me — switching to AI in 3…” with Stay and Go now, then fades over. It never pulls a page away while you are using the panel, and rules that fire one after another wait their turn instead of bouncing the screen back and forth.

Where the idle return and the Back key go.
Each page can override this (page editor › Back home after).
After that the panel goes home when nobody touches it.

Kiosk

Keep the phone on the panel. Neither needs root.

Battery care

A phone that is plugged in all the time wears its battery out. PhoneBox can keep it between two levels by switching the phone's power on and off. Phones cannot stop charging by themselves without root, so the power is switched where it comes from: a smart plug in Home Assistant (the phone on its own charger), or two shortcuts, for example uhubctl for a USB hub with switchable ports. Without USB power the panel keeps running over Wi-Fi.

Keep the battery between % and %

Claude Code permission prompts

When Claude Code asks for permission (run a command, edit a file…), the phone shows the request with Allow and Deny. If the phone is not connected or nobody answers in time, Claude Code asks in the terminal as usual. This needs a small hook in ~/.claude/settings.json; PhoneBox adds it for you (a backup is kept next to the file).

Ask on the phone

Phone connection

If several Android devices are connected, choose which one runs the panel.

Phones

Several phones (or a phone and a tablet) can use this computer at once, over USB or Wi-Fi. Give each one a name and choose the pages it shows; a phone shows all pages until you choose.

No phone has connected yet.

Wi-Fi & Tailscale

Let the phone connect without the USB cable

Pairing happens over USB: after turning this on (and restarting), plug the phone in once. The phone then talks HTTPS to this PC, trusts only this PC's certificate and has to present a secret key. The phone and this PC must be on the same network — or both on Tailscale, which also works from another place or across separate Wi-Fi networks. Windows Firewall asks once — allow it (tick the network type Tailscale uses, too).

—

Updates

Install new releases automatically

Checks on GitHub every 6 hours. The phone app is installed over USB without a prompt on the phone; the agent replaces its own files and restarts.

Webhooks

Push data into the panel from scripts, CI jobs, Home Assistant, cron … Values show up in Pushed value widgets (key = the last part of the URL), notifications in a toast on the phone and in the Notifications widget. Values survive restarts.

Try it

Examples

JSON payloads may carry value, title, sub, unit, icon, color, level (ok / warn / error), progress (0–1 or 0–100), items (a list) and ttl (seconds). Plain text or a number works too. Notifications take title, text, level, vibrate, seconds, wake (light up the night screen) and page (switch to it).

From other machines

Current values

Advanced

The raw settings. "Apply JSON" loads your edits into the form; Save writes them to disk.

The settings file includes your shortcut commands, tokens and keys: keep it private.