Phone control¶
When you need this: you want to steer the work — approve specs, answer an agent's questions, review and merge PRs — away from your desk.
mship's phone app is Ground Control (Android). The workspace side is just
mship serve; everything below rides on it.
1. Start serve¶
mship serve # reachable on your LAN / tailnet
mship serve --relay # reachable from anywhere, via a reverse tunnel
--relay dials out to a relay host and gets a stable per-device URL, so NAT
and coffee-shop Wi-Fi don't matter. You can use a self-hosted relay
(Relay hosting); serving over a tailnet works too
(Serve over Tailscale).
Upgrading mailbox writers¶
Mailbox thread files are read-modify-written. Before using a release that adds
phone-visible mailbox fields such as Done, install the new mship version
and restart every long-lived mailbox writer for that workspace — including
mship serve and any running agent, worker, or inbox process that can write
.mothership/messages. Fresh CLI invocations started after the upgrade use the
new version.
Do not leave an older mailbox-writing process running during the rollout: its
older Thread model ignores fields it does not know, so a later write can
discard a newer resolution cursor. A configuration change in the new binary
cannot protect data from an already-running older binary; upgrade and restart
all writers first.
2. Pair the phone¶
mship pair
Prints a groundcontrol:// deep link and a QR code carrying the serve URL and
token. Scan it in Ground Control and the workspace appears in the app. Repeat
per workspace — the app is multi-workspace.
3. What you can do from the phone¶
- Capture ideas. A thought typed on the phone becomes a thread the agent can brainstorm with you and shape into a spec — capture is a conversation, not a one-shot form.
- Review and approve specs. Specs in
needs_reviewsurface in the Queue as swipeable cards: acceptance criteria, open questions, verdicts. Approve, or request changes with a reason — approval is what unlocks feature development (Ship a feature). - Answer decisions. When the agent hits a fork it can't resolve alone, it posts a decision card — a question with tappable options. One tap unblocks the build.
- Chat with the agent. Every work item has its threads; messages are durable, so the agent answers when it wakes even if it wasn't running when you wrote.
- Close completed conversations. Mark a finished thread Done to clear its older action and decision cards without sending a message or waking an agent. Opening a thread marks it read but does not resolve its requests. Any later request still returns to your attention.
- Watch progress. Work items show their phase (inbox → shaping → ready → in flight → review → done) as the linked spec, tasks, and PRs advance.
- Review and merge PRs. Merged PRs flow back as events — the agent sees the merge and closes out the task.
4. How the agent hears you¶
Messages land in a durable mailbox on the workspace. A running agent listens
between turns (mship inbox wait) and drains the inbox at each turn boundary,
then answers with mship reply or posts options with mship ask. Nothing is
lost if either side is offline — it's store-and-forward, not a live socket.