Start a piece and write the spec with it
Open the new-piece screen, headed “Start something new” on iOS and “What should we build?” on Android, and describe the work. The iOS screen tells you what happens next: “Describe the work. The spec interview starts on your Mac and continues right here.” Android says the same thing in its own words: “Describe the work and the agent will interview you into a spec.” Above the prompt box sit three pills: the project, the interview depth, and the model. The model pill reads “Project default” until you pick something else from the synced catalog; leave it there and the interview starts exactly as it would if you had clicked New Piece on the Mac. The whole interview runs in the phone’s chat. You answer its questions, it drafts, and you keep going until the spec is right. If you set a piece down and come back later, Continue Interview on the piece picks the conversation up where it stopped.Approve what is waiting
Two kinds of thing wait for you, and both reach the phone. A piece parked at a phase. Spec approval offers a choice of how the piece runs from here, and the button says what tapping it will do: Approve Spec, or Approve & Run Auto once you pick the hands-off option. The Loop lane is not offered, because there is no board here. What these choices mean is in the two layers. Every gate that parks a run clears from the phone, each with its own button:
The two review passes, code review and work review, have nothing to clear; they add a check, not a stop. The one exception is a work review that fails on the Auto or Loop lane: the piece parks at Review, and Create PR on the phone is the way past it, the same button that clears the review gate. Both are explained in gates.
Approving one agent at a time is a Mac job. The phone’s review stop is the whole piece.
An agent asking to run something. The request arrives as an “APPROVAL REQUIRED” card in the session, with Allow, Deny, and Allow for Session as tappable options. The same three answers appear as Yes, No, and Yes for session chips above the composer of a waiting session. The scopes are the ones the Mac offers, explained in permission profiles and approvals.
Change the plan before you start it
While a piece sits at the plan gate, every agent in the graph is still “Queued”, and tapping one opens its editor instead of a session. Rewrite the agent’s name or its prompt, or tap Remove Agent to drop it from the run. Both apps show the same fields in the same order: the agent’s ordinal and state, what it depends on and what depends on it, then the Name and Prompt fields. Save stays disabled until both fields hold text. Saving does not close the sheet by itself: it waits for the Mac to apply the edit and dismisses only then, so a refusal leaves your typing exactly where you left it. Remove Agent asks first. The confirmation’s title names the agent, and if anything in the graph depends on it, the body says how many agents were waiting and will no longer be; either way it ends with “This can’t be undone, but you can regenerate the plan to start over.” Nothing is removed until you confirm. Once execution starts, tapping an agent opens its session instead. Changing a running or paused plan is a Mac job, covered on the agents phase.Talk to a running session
Open any session and read the transcript as it streams. The composer sends a prompt into a live session. Starting a New Session from the phone shows pills for the project, the permission setting, the branch, and the model before you send; a live session’s composer is just the box. When the Mac stops reporting in, the phone says so rather than showing stale work: the session list on either phone reads “Mac appears offline” and warns that sessions may not update.Drive the run
A piece’s action bar carries the same controls as the Mac, and which ones appear depends on where the piece is:- Start Execution, Pause All, Resume All, Stop All
- Regenerate Plan, Retry Failed with the count of failed agents, Evaluate
- Continue to Review to move a finished run on, Request Changes to send work back, Mark Done to close the piece
Notifications
Settings on the phone carries two toggle lists, the same labels on iOS and Android alike. “Notifications”: Session needs input, Session completed, Session failed, Approval requests. These are the session-level pushes: a live session waiting on you, one that finished, one that failed, and a tool-use approval request. “Piece Notifications”: Strategy ready, Agents ready, Piece errors, Piece complete. These are the phase-level pushes a piece sends as it moves, in the same words as the Mac’s own banners; the full sentence list is in notifications. Turning a toggle off silences that push. It does not change what the run does: a hands-off piece keeps going on its lane and gates whether or not you hear about it.Open and merge the pull request
Create PR opens the pull request from the phone, Open PR takes you to it, and Merge PR merges it behind a “Merge this pull request?” confirmation. Fermata opens the pull request; merging is still your call, on whichever device you are holding.What the phone does not do
Two gaps, stated plainly:- No diffs. It shows no diffs and no file counts. Reviewing the code itself is a Mac job.
- No Loop board. There is no board, no Play Loop or Pause Loop, and no backlog or draft management on the phone. You act on pieces one at a time.
Pairing
Pairing is a QR scan, done once.1
Open the Mobile pane on your Mac
Settings → Mobile (⌘,). Click Generate Pairing QR Code.
2
Scan it from the phone
The Mac shows “Waiting for phone to scan…” until the app reads the code.
3
Confirm it took
The Mac pane switches to “Paired with” your device name, with live sync health and an “End-to-end encrypted” confirmation. The phone’s Settings shows the same under “Mac Connection”.