Controlling Sessions from Your iPhone

Once your iPhone or iPad is paired with your Mac, it mirrors every running claude/codex/kimi/grok/opencode/muse/shell session live, end-to-end encrypted, and lets you answer questions, approve plans, send prompts, and even dictate — all from the Session Detail screen. Muse sessions appear only with a current app version; an older companion shows them neutrally. This page covers everything you can do once you’re looking at a session; for pairing itself, see Pairing Your iPhone, and for cross-user sharing, see Sharing a Session.

The toolbar also has a Board button for the project’s open items — questions and to-dos that can wait, without turning the session amber. To-dos show who they are assigned to, like on the Mac — an older Mac sends no assignee, so the line stays hidden there. The button shows a count of all open board items across every project on the paired Mac; the project picker behind it lists each project with its own count, sorted so projects with open items sit at the top. The count needs a Mac running a current vord build — an older Mac does not report one, and the button then shows no number. The phone board is a dashboard: counts for needs you, running, and new, then Needs you (waiting sessions plus open items), In progress (active phase, folded plan, answers already handed over), and New results. Empty groups stay hidden. Finished work from the last 7 days is folded at the bottom; older items stay on your Mac. Notes for your assistant is folded unless you are typing a note. A board notification opens that board at the named item, in its project’s mode and tab, and briefly highlights it; a done or missing item shows the same short notice. See Opening an item from a notification. Every item shows its ID, such as F-12 or T-3, in front of its title; touch and hold it for Copy ID. The search field at the top finds items by ID, title and text, including finished items the phone has received, and an exact ID such as F-478 shows only that item. An older Mac sends no display ID; the phone then shows the stored ID, which can carry the Mac’s device suffix. You can answer a question in your own words even when it offers options, with Optional, in your own words… under them. You can reply to a to-do without marking it done (needs an up-to-date Mac) — the field is Message to the agent, Send keeps the to-do open and your reply shows with its delivery status. Mark done checks the to-do off and carries your message along as an instruction to the agent; against an older Mac that message still goes out, arriving as a reply right before the check-off. Tap a waiting row to open the session and decide there. Leave a note for the agent… adds a note that goes out with the next prompt in that project (needs an up-to-date Mac), and Withdraw takes back a note that has not gone out. Every item also has a trash icon: Delete takes it off the board for good and tells the agent nothing, and questions and results can be Dismissed — the agent is told, whatever you typed in the field travels as the reason, and an empty field means none. Both appear only when the paired Mac runs a version that supports them; against an older Mac the previous actions stay. If the session that asked has ended, your answer uses the preselected target automatically — a still-running parent session or the project lead that started the session, the resumed session, the project lead, the most recently active running main session (never a child session), or a new session. The per-item Hand over to… menu offers the project lead first, with a clipboard icon, then eligible sessions alphabetically with child sessions indented under their parent. Ended sessions and sessions shared by someone else are not targets. A board that is off for a project on the Mac shows The board is switched off for this project on your Mac. With more than one Mac paired, the Mac menu at the top right of the board and of its project list switches between their boards; the phone remembers your choice. Until you pick one, it uses the Mac of the session you had open; a board notification always opens the board of the Mac that sent it.

In Hand over to…, the project lead appears first, followed by main sessions in alphabetical order. A main session’s direct children are indented below it; ended and guest sessions are not offered.

When the paired Mac supports board assignment and the project has at least two members, the iPhone offers the same assignee menu on open questions, to-dos, commitments, and notes. Open commitments also have it in the Agenda context menu. Assignment of questions, commitments, and notes requires support from the linked vord Cloud server. For an unowned question, to-do, or commitment in a project without a lead, choose Start project lead and hand over; it uses the usual project-lead start flow and the new lead takes the item automatically. Notes are never unowned. Assigned items show Assigned: … (or Assigned: you) on the phone.

With a current Mac, a project’s phone board also has an Agenda section as soon as the project has a commitment (V-n). It lists the open commitments in the order of the Mac’s agenda — overdue ones marked red — and the finished ones in a collapsed Completed group. Each row shows the due time, the detail, what it waits for, the session it goes to and, for an item from another device, an origin line: from Name · Device or edited by Name. Done, Reschedule (a date, an optional time and a required reason) and Run now appear only when the Mac announces boardAgenda; an older Mac sends no agenda, so the section is missing. Commitments from another device stay read-only on the phone — only their home Mac can act on them. The same section lists the project’s automations: every automation with an upcoming run in the next 14 days shows a clock, its name and the time of its next run. Tapping the row opens Automations with that job marked.

The Cockpit also shows a read-only Agenda across projects when a paired Mac supports it and has entries. It lists open commitments that are overdue or due in the next 14 days; each row names its project and, when several Macs are paired, its Mac. The overview initially shows up to two entries; tap Show all (n) to expand it and Show less to collapse it again. In Cowork mode it lists only Cowork projects and in Code mode only Code projects, as long as the Mac identifies Cowork projects; commitments without a project appear in both modes. Tap a row to open that project’s board. This overview requires a current Mac build with agenda support. Automations of the paired Macs join the list with their next run and follow the same mode filter; automations without a project appear in both modes. Tap an automation to open Automations with that job. Items whose session no longer exists and that no project lead could take over appear in a separate No owner group instead of as overdue.

A linked Code/Cowork pair appears once in the board’s project picker, with the same All, Code, and Cowork tabs as on the Mac — the default tab follows the iPhone’s work mode. Entries carry the same origin badges, and the item menu offers Side and Hand over. This needs a Mac running a build with pair support.

Agent replies to your board questions, to-dos and notes appear below your message on the card, with the agent’s name and a colored bar. Replies are plain text, up to 1,000 characters each and 10 per card; they do not change the item’s state. See Responding to a Waiting Session for details.

The mirrored shadow terminal

Open a session from the Sessions tab or the Cockpit tab, and its live output starts streaming automatically — a transcript-tail replay first, then a live stream as new output arrives.

Chat view (when available). It shows the actual conversation — prompts, answers, and tool steps — directly from the agent’s transcript, not as an interpretation of a terminal image. See The chat view for details.
Semantic view. When the chat view is unavailable, such as on an older Mac or in a shell without a readable transcript, terminal output is wrapped into readable prose, code blocks, and cards. Highlighted echoes rejoin their wrapped columns; large raw blocks can be collapsed and expanded, while the block currently in progress stays open. The fold markers <<<VORD_FOLD…>>> themselves are hidden, but their content stays readable.
Character-accurate raw grid at low heights. The raw grid mirrors the Mac terminal’s actual column width and shows collapsed messages as a ▸ vord: heading. The app chooses this view for short windows.

The view adapts to the space available in the window. The software keyboard keeps the input accessible without switching between chat and terminal views.

Highlighted echoes (the gray block showing what you sent) render as one continuous tinted card, even where the Mac padded them with blank colored rows, and wrapped lines keep a hanging indent so continuations line up under the text instead of at the card edge.

The chat view

vord can show a session as a conversation instead of a terminal view: prompts appear on the right, answers as Markdown at full reading width, and tool steps as unobtrusive one-line entries. The content comes from the transcript file written by the agent on the Mac; claude, codex, kimi, grok, and muse are supported. Plain Shell and SSH have no transcript, so they stay in the terminal view.

Day separators group the history, and a quiet activity line sits at the end: The agent is working… while it works, a pointer to the command zone while it waits on you, and the usual usage-limit countdown when the session is rate-limited.
It opens at the end. The view lands on the newest message once, without you scrolling — and it verifies that it actually got there before it lets go, so you never open a session onto an empty stretch of screen.
While the phone is still waiting for the first answer, you see placeholder message shapes and Loading conversation… instead of a blank area. They only appear if that wait takes longer than a moment. A fast Mac with messages goes straight to the conversation; a fresh session whose transcript file is not there yet (or is still empty) shows No messages yet as soon as the Mac answers — not the loading placeholders.
Scroll up to load more. Nearing the top of the loaded conversation pulls the next block of older messages from the Mac automatically; Beginning of the conversation appears once there’s nothing older left. Your reading position is held across the insert — the view doesn’t jump.
Selecting and copying works as everywhere else: long-press to select text, or long-press a message and choose Copy block. Code blocks keep their own copy button.
Thinking is collapsed by default and only appears at all when the agent actually wrote readable thinking text. claude stores its reasoning encrypted (an empty field plus a signature) and codex encrypts it too, so for those there is nothing to show and nothing is faked. kimi and grok do write thinking in clear text, and vord deliberately leaves it out of the chat: it is the bulk of what they record and would bury the actual conversation. It stays visible in the terminal.
Messages vord injects (a mesh delivery, a child-session report) show as a compact system note with their origin label — not as a user bubble, and not with the fold-marker lines the Mac terminal uses to collapse them.
Pasted images appear as previews. When a message contains an image, the phone shows a thumbnail instead of the [Image #N] marker text and the attachment line; tap the thumbnail to open the image large. This needs a current Mac build that announces image support — against an older Mac, or when the image cannot be loaded, the plain attachment line stays.

When the chat view does not appear, the screen says why. A one-line note sits above the terminal view and names the reason: waiting for your Mac (the connection is down — nothing is decided yet), this Mac is too old for the conversation view (it doesn’t announce the transcriptChat capability), this session has no readable conversation (a plain shell or SSH session), your Mac can’t read this session’s conversation right now (the Mac answered but cannot open the session’s transcript — for example because the session no longer exists on the Mac), or couldn’t load the conversation. The last two come with a Try again button. A session that has already talked never shows No messages yet just because the Mac could not open its transcript; the Mac also records the reason in its event log, so the case can be traced afterwards.

Ended sessions keep their conversation for claude, kimi, grok and muse: their session files stay on disk and vord finds them again without a running session. An ended codex session is the exception — vord deliberately doesn’t search its rollout tree (tens of thousands of files) just to render a view, so it falls back to the note above.

vord retries the first fetch by itself a few times before giving up, so a lost request or a Mac that was busy binding the session’s transcript no longer costs you the chat view. Those retries run quietly in the background: once the Mac has said the conversation is empty, the screen stays on No messages yet instead of flipping back to the loading placeholders. Once a conversation has loaded, it stays: locking the phone, a reconnect or a Mac going briefly offline no longer drops you back to the terminal view — the messages you already have remain on screen. A session whose transcript exists but is still empty shows No messages yet rather than silently reverting. Because the transcript is a Mac-side file, the chat can reach back further than the terminal’s own scrollback.

Selecting and copying text

Everything in the transcript is selectable — prose, code and diff blocks, highlighted echoes, question cards and status captions. Long-press to select, then use the system Copy.

For a whole block at once, long-press a card and choose Copy block. You get the text as you read it, not as the Mac’s column grid stored it: prose and highlighted echoes come back as re-joined paragraphs, while code, diffs and tables keep their exact lines because the column alignment carries meaning there. Long-pressing inside an agent card copies the entire card, including its nested content.

In the raw grid, long-press and choose Copy visible area to copy exactly the currently visible lines, character for character.

iOS session detail in portrait: shadow terminal with the answer command zone below

Starting a new session from the phone

You don’t need to be at your Mac to start a fresh session.

Tap + — top left in either tab, with a project list if you have more than one project. In the Sessions tab you can also tap the + next to a project header to skip the picker and start right in that project.
Confirm the project, or tap the project field to open the full scrollable list (color dot, name, checkmark on the current choice) and pick one.
Choose the agent: claude (default), codex, kimi, grok, opencode, muse, or shell.
Tap Start.

The new session appears once the Mac pushes the updated list — there’s no instant optimistic entry beyond navigating you straight to it.

Under By project, a project lead has its own accent-framed card with a clipboard icon, directly below the project heading; it is never a regular session row. The title is Project lead · project. Next to its status dot, the card shows one text state at a time: a usage-limit countdown or wait reason when the lead needs you; otherwise its work state (Working, Waiting for you, or Done) when supplied by the Mac, or the regular status label when no work state is available. The card also shows any open question and open board items. Choose Work state in the card menu to switch it; older Macs without projectLeadWorkState show no work state. Under By activity and in the Cockpit, a Project leads block at the top stacks one visible card per project. Tap a card to open the lead’s chat. Its menu (…) offers Open board, Work state when supported, and End project lead…. In Session Detail, the header reads Project lead · project and has a Board button. Banners and notifications use the title Project lead · project. Sessions led by a project lead carry the clipboard badge Led by the project lead, including on Cockpit tiles.

Project names on the iPhone are the same display names as on the Mac: a name set with Rename… on the Mac wins, otherwise the linked vord Cloud project’s name, otherwise the folder name. The Sessions list follows the Mac sidebar’s project order and groups. Group headings show a folder icon and path, such as Clients › Acme, above their projects. Sessions are sorted by status and then last activity, as on the Mac. Search Search projects and sessions keeps a whole project visible, including its project-lead card, when the project name matches; otherwise it filters sessions by title and finds a lead through its project. The Cockpit has no search. An older Mac without project-structure support supplies alphabetical project order without groups. Start a lead from the project heading’s menu, and release a session from its lead in Session Detail, whenever the Mac supports it.

All projects

The third tab, All projects, pages through every project lead chat instead of listing sessions. Swipe sideways to move between leads; the order matches the Mac sidebar, and each page header names the project with a page counter (1 / 3). With more than one project lead, the page counter becomes a menu: tap it to see the project names and jump to that page — the current page shows a checkmark. The navigation bar keeps showing All projects: there is no title menu, switching happens only through the page counter. Only the page you are looking at is live — the others stay parked on their header until you swipe to them or pick them from the menu. With no project lead anywhere, the tab shows No project leads yet.

Like the Mac, where the window bar is global and every column has its own header, the navigation bar in All projects carries only the global buttons (usage, notifications, more, new session) — and the lead’s own actions, Shown by the agent and Session actions, sit in the page header next to the page counter of the page you are looking at. On iPad and the unfolded iPhone Duo the detail column has a bar of its own, so these actions stay in that bar there. There is no sort-and-group menu here: the pages have no order of their own.

On iPad, All projects sits in the sidebar under Cockpit and pages through the same leads in the detail column; side-by-side lead columns on iPad arrive later.

The status header and subagent overview

Tap the header at the top of Session Detail to expand or collapse it. Expanded, it shows the session’s status, its wait reason or usage-limit countdown, and the project name. If auto-continue is active for a limited session, the header adds a short continues automatically line next to that countdown. If subagents are running, a compact summary row appears below: finished/total progress plus colored counters for how many agents are currently working or idle. Tap the summary row to unfold the full list — each agent’s name and status dot (capped at 16 entries, 80 characters of description each — a wire-protocol limit). Only real agent/team/workflow nodes show up, not individual tool calls.

If the session has child sessions, the expanded header keeps the chat tall: a one-line family chip shows the child count and status dots. Tap it to open a native bottom sheet with the full scrollable list, each child’s title, status, runtime, and a jump action. The session list and cockpit fold every child into its parent’s card instead of giving it a card of its own, with the same compact status signal.

Inside a child session the same expanded header carries the way back: a line marked with ↳ names the parent session. Tap it to return to the parent — if you came from it, you land back on the screen you left rather than on a second copy of it, so the back button keeps working the way you expect. When the parent is no longer in the list (ended, filtered away), the line reads detached and is not tappable.

When the Mac has a current agent to-do list, the expanded header also shows a compact To-dos card with the completed/total count. Tap it to see the current items in order, their state, and (when Claude provides one) the active form describing the step in progress. The card is informational only; questions and approvals still appear exclusively in the command zone. A refreshed list replaces the previous one completely, so completed, reordered, and removed items are reflected immediately, and the card disappears when the Mac reports no to-dos.

On current Mac and iPhone builds, the same header can show a Live activity card. It is a versioned full snapshot of the real subagents, teams, workflows, monitors, and background tasks behind this session. Expand it for status dots, kind, title, model/tool, runtime, and a stale warning when a worker has stopped reporting. The card is capped and scrolls internally; it shows a +N more indicator for larger snapshots. Every snapshot replaces the previous one, so workers that finish or disappear do not remain on screen. The card is shown only when both peers announce the activitySnapshot capability; shared-session guests never receive these private activity details. It is informational only — all answers remain in the command zone.

On wide iPad layouts, the same read-only material can live in the right-hand Inspector instead: live activity, to-dos, child sessions and shown media stay visible while the conversation remains at reading width. The Inspector never contains answer buttons; questions, permissions and plan approval still happen only in the command zone.

If you run more than one Claude login, the header also shows which account this session runs on — the account name next to the project name together with the full address, and the account name alone in the session list. The account name is the same one the Mac shows: the slot name you gave the account (for example mandr), or for the default account the part of its email before the @. With a Mac that doesn’t send account names yet, the phone falls back to the part before the @. It’s read-only here: connecting, pinning and removing accounts happen on the Mac (see Agent Accounts). The Mac only sends it for sessions where Claude is actually detected, so a plain shell, codex or kimi session shows nothing. When the Mac has official quota numbers for that account (from the agent CLI’s own reporting), the badge also shows the account’s plan usage as a percentage — the same value as the Mac’s account badge, mirrored read-only.

The active-agents bar (who’s working right now)

Directly above the command zone — like a terminal’s footer line — a slim bar appears whenever at least one subagent is actually working. It lists the active agents only, not the “x of y done” statistic: the agent’s name, how long it’s been running (6m), and its model when the Mac sends one. With more than one active agent it collapses to a count (“3 agents working”); tap it to unfold the full agent list, the same rows the header section shows.

It disappears completely when nothing is running, so it never steals space from the terminal — in portrait or landscape.

The bar is deliberate about what it claims. An agent only counts as “working” while it has recently written to its transcript. If nothing has come from it for five minutes, the bar says so — “no response for 8m” in amber — instead of leaving a green dot up forever. That matters because the Mac’s subagent start/stop hooks lose events under load: without this check, an agent that finished long ago could stay “running” indefinitely. Five minutes is deliberately generous — a long build or test run can easily go minutes without writing anything, and vord would rather stay quiet than cry wolf.

The same honesty applies in the other direction: when the Mac has to assume an agent stopped (it saw the session go quiet but never got the stop event), the agent shows as finished but marked “probably finished” in the tree on the Mac, rather than claiming an ending nobody witnessed.

Against an older Mac that doesn’t send activity timestamps yet, running agents still appear — just without runtimes, and never flagged as unresponsive.

Answer cards: selection, multi-question stepper, checkboxes, own answer

Whenever a session is waiting on you (🟡) — an AskUserQuestion, a permission prompt, or a plan approval — full-width answer cards appear automatically in the command zone below the terminal, each with a number badge. Tap the one you want instead of navigating with arrow keys. Claude’s unnumbered folder-trust prompt appears here as No, exit and Yes, I trust this folder cards too.

A selection you have made but not yet submitted is preserved when switching between compact and split views.

Best case: the Mac announces the boxUpdate capability, and you get a fully structured box.
Fallback: on an older Mac without that capability, detection falls back to a local grid parser — it works, but is less robust on multi-line or unusual boxes.

Multi-question stepper

When one AskUserQuestion bundles several sub-questions, a tab bar reading “Question X of N” tracks progress (answered/unanswered). Pick options for the active sub-question, tap Next question, and on the last one, Submit answers closes out the whole round.

Multi-select (checkbox) questions

For checkbox-style questions where several options can be true at once, tapping toggles your local selection — nothing is sent to the Mac’s PTY per tap. Only Submit answers sends the full, deterministic sequence of toggles at the end.

Write your own answer

Below the offered options, a final card reads Write your own answer… — tap it, type your text in the compose field, and send. This needs the Mac’s composedText capability.

When the open box really takes free text — claude’s “Type something.” option, a plan/permission feedback option (“Tell Claude what to change”), or codex’s notes field — the Mac answers the box for real: it opens the inline field, pastes your text, waits for the terminal to echo it back, and only then submits.

Answer cards with numbered options under the terminal

The compose field and draft persistence

When there’s no active question box, the compose field at the bottom of the command zone is a free-text editor for a new prompt — type and tap Send.

With the Mac’s composedText capability, your text is delivered natively.
Without it (older Mac), sending falls back to raw keystrokes, and the send button is disabled with an explanation while a question, permission, or plan box is open — rather than risk pasting into the wrong place.
If the session is sitting in a question, permission or plan box, your typed text is held and delivered once the session leaves that box, instead of vanishing or sending blind. The box itself is never touched.
Messages sent in quick succession stay separate prompts: the Mac spaces them out instead of writing them into the agent’s composer back to back (which would merge “3” and “3” into “33”).

Unsent text and image attachments stay associated with their session and Mac on your iPhone or iPad. Your draft is preserved when you switch views or open another session.

Your draft stays until the send is confirmed

Sending used to clear the compose field and any attached image right away — even though the Mac can only know a moment later whether the message really went in. When the agent’s composer swallowed the submit (it happens while a session is still starting up), the message sat there unsent while the phone had already suggested “sent.”

Now the phone holds on to the message until its Mac has verified the submit on the actual terminal, and shows a quiet line above the command zone in the meantime:

Sending your image… / Sending image 2 of 5… — one or more images are still being handed to the connection. This is purely local (how far the phone has gotten sending the bytes over a slow or spotty link) and appears before the Mac has seen anything.
Delivering… — sent, waiting for the Mac’s confirmation.
Waiting for the session to be free… — the session is inside a box; the Mac keeps the message and delivers it as soon as the box is gone.
Delivery unconfirmed — your draft was restored. Check your Mac before sending again. — no result arrived within six minutes. Your text and images are back in the compose field itself (not just the hidden per-session draft, so you can see exactly what didn’t get confirmed) — but the phone still won’t send it again for you: the Mac may have received it after all, and a second send could duplicate the prompt.

If the Mac reports a real failure — the session no longer accepts input, the submit could not be confirmed and the text is sitting in the composer, or an image upload stalled for 30 seconds on a bad connection — your draft and attachments come straight back into the compose field immediately, together with the reason, wherever you are in the app (not just after navigating back to the sessions list). The same happens if the send never made it off the phone at all — a dropped connection while sending counts as a failure too, not silence. The Mac also records the composer-stuck case in its notification inbox, so an unsent message can’t quietly rot in a composer even when your phone isn’t watching.

This needs the Mac’s deliveryReceipt capability. Against an older Mac, sending behaves exactly as it did before: the field clears immediately and no status line appears.

Special keys (esc/arrows/ctrl-c/enter)

A row of keys sits at the bottom of the command zone (hidden only while answer cards are active), so you don’t need to open the software keyboard for basic terminal control. Every key has full comfortable touch size (44 pt), and the row is split in two:

Fixed on the right, always reachable: the keyboard toggle, Interrupt (Ctrl-C), and Send (Enter) — Enter sits at the right edge, in the thumb zone.
Scrollable on the left: esc (a labeled text key), the Permission mode key, the Model key, and the arrow keys. If they don’t all fit, swipe the left part sideways — a fade at the edge hints that more keys are waiting there. Image attach lives on the compose field, not in this row.

Keys are visually grouped (modifiers | arrows | actions) with wider gaps between groups.

Permission mode: display, direct pick (claude), single-step (codex/kimi)

The Permission mode key in the control row shows the session’s current approval mode as a glyph (open lock for default, pencil for accept-edits, lightning for auto/bypass), with a red warning tint on risky modes.

claude — direct pick. Tap the mode key to open a compact list of every mode reachable in the Shift+Tab ring (default / accept edits / plan / bypass / auto). Pick one to jump straight there — no clicking through step by step. Harmless switches, and leaving a risky mode, apply on the first tap. Entering a risky mode (auto or bypass) from a safe one asks for confirmation right there: the row turns red with a “Really?” prompt, and only a second tap on it switches — there’s no separate dialog. The armed row clears itself if you pick another mode, close the list, or wait a few seconds, so a forgotten tap can never switch later. Even before the Mac reports a known mode (right after session start), the list is available; the switch waits “armed” for the first mode report instead of sending blind.
codex — single-step cycle. codex has no fixed mode ring, so a tap sends codex’s own /permissions slash command, opening codex’s picker directly — that picker is the deliberate choice, so there’s no extra confirmation on the phone. Reaching a distant mode takes several taps.
kimi — single-step plan toggle. kimi toggles plan mode with Shift+Tab, so a tap sends that keystroke: plan on, plan off. The Mac reads the current mode back from kimi’s status line (plan/auto prefix in front of the model name) and shows it with kimi’s own names — Manual approvals, Plan mode, Auto-approve, the last one with the red warning tint. There’s no direct-pick menu: kimi has no keyboard ring that reaches auto or yolo, and its /plan-style slash commands can’t be sent reliably (kimi swallows text and Return sent in one write as a newline — the same paste-burst trap behind all of vord’s kimi keyboard delivery). Shell sessions have no mode concept at all, so the key is disabled there.

See Permission Modes and Claude vs. Codex for the full mode reference and the reasoning behind this gap.

Model: see what’s running, switch it from the phone

Next to the mode key sits its own Model key (a chip glyph) — deliberately a separate key, not a second section inside the mode list: permission and model are two different decisions. A tap opens a compact list of the models the session’s agent offers, with a checkmark on the one that’s actually running. The running model comes from the Mac, which reads it out of the session’s own transcript, so it’s the truth for this session — not a guess from your global settings.

Nothing reported yet. Right after a session starts, before the first turn, the Mac has no model to report. The list says Current model unknown and shows no checkmark instead of silently leaving everything unticked.
A model the app doesn’t know. When a new model generation shows up, its raw name (for example claude-nimbus-9-20301104) is printed as-is at the top instead of ticking the closest-looking entry.

claude — direct pick, no extra confirmation. Tapping a model sends claude’s /model <name> command straight away — including the costly ones (Opus, Fable): the agent itself asks nothing extra, not even for the 1M-context models, so the app doesn’t second-guess it with a confirmation step either. It’s exactly like typing /model <name> in the terminal yourself. Be aware of what claude does with it: that command also saves the model as your default for all new sessions, so it isn’t a session-local change. The list says so right above the last row.

Where the confirmation shows up. A direct pick is one command with no reply channel back to the phone, so the list never claims success on its own. claude answers in the session itself — Set model to Opus 5 and saved as your default for new sessions — and that line is what you see in the transcript. If the pick can’t be applied (say the model isn’t available for your account), claude says that there too, and nothing changes. The checkmark in the list moves once the Mac reports the new model back, usually with the next turn, so a checkmark that hasn’t jumped yet isn’t a failed switch.

Session-only: use the agent’s own picker. The last row, Open the agent’s picker, sends a bare /model, and claude’s own selection dialog arrives on your phone as normal answer cards. That dialog is the only proven way to change the model for this session only — its footer offers “s to use this session only”, which leaves your global default untouched. Navigate it with the arrow keys and confirm from the cards.

codex — dialog only. codex’s /model dialog couples the model with its thinking depth in one step, and there is no documented way to preselect a model from the command line. So codex’s models are listed for information (dimmed, with the checkmark on the running one) and can’t be tapped; the Open the agent’s picker row is the way. A tappable row that opened a dialog without preselecting anything would be a lie.

kimi and shell — no key. kimi exposes no /model command over the wire, and text plus Return sent in a single write doesn’t submit in kimi anyway (the same paste-burst trap behind all of vord’s kimi keyboard delivery); its model is chosen with the --model start flag. Shell sessions have no model at all. In both cases the Model key is disabled and dimmed.

The dedicated plan-approval stage

When claude is waiting for plan approval, a collapsible plan view replaces the normal chat or semantic view: plan text at the top, approval/rejection cards below in the command zone. A chevron returns to the full terminal view when you need more context. There is no second interaction surface; approval always uses the same answer cards.

The dedicated plan-approval stage: plan content above, approval cards below

Workflow decisions: approve, reject, one more round, resume, abort

When a workflow run of the mirrored session needs you — it reached your approval, or it halted because its rounds or budget ran out or you rejected a stage — the Mac posts a notification, and the session on the phone shows exactly one workflow decision card in the command zone. It carries the blueprint name and the stage (“Spec-first Feature is waiting for your approval”, “… — rounds used up”, “… — rejected”, “… — budget used up”), the round (“Round 2 of 3”) and the budget in plain words (“5/8 starts”), and the same buttons the Mac offers for that state and nothing else: Approve and Reject… on an approval, One more round and Abort when rounds are used up, Resume and Abort on a budget halt (“Extends by 2 starts.”), Abort alone when you rejected a stage that has no loop. One more round is the same durable human decision as on the Mac: it adds two starts, resets the parent’s self-resume quota and wakes the loop target exactly once. A transport retry keeps its request id, so reconnecting to a restarted Mac cannot apply the grant twice.

Reject… opens a sheet for the reason (1–500 characters); the reason travels to the parent as gate evidence exactly as on the Mac.
Abort always asks for confirmation on the phone.
Several open decisions on one session become one card with a 1 of N pager — approvals first, then halts, newest run first.
The Mac stays the single truth: it re-checks the run when your tap arrives, and if the decision has already changed (someone decided on the Mac, or the run moved on) the card says “This decision has already changed.” and refreshes instead of applying anything.
Offline, the card stays visible but disabled (“Connect to the Mac to decide.”). Nothing is queued; reconnect and decide.
Buttons live only in the command zone — never in the transcript, the notification inbox, or a banner. Guests of a shared session never see the card.
Needs a Mac app and phone app from the same release or newer; against an older Mac the phone shows the run without a card, and the notification still points you to the Mac.

Open decisions in the inbox

When a deletion needs your say, the deletion watchdog has paused agents, or an agent asked to change one of your jobs, a current Mac puts an Open decisions section at the top of the notification inbox. The oldest open request also appears as a prominent sheet. The lists come live from the Mac and are never stored in the phone’s inbox cache.

Deletion request — Allow / Deny. Allow asks Allow deletion? — The files will be moved to the Trash. See Deletion Protection.
Agents paused — Resume / Stop agents. Stop agents asks Stop paused agents? — All paused agents will be stopped.
Job change — Approve change / Reject. See Scheduled Jobs.

A push tap opens the oldest open decision of that kind. Against an older Mac the inbox keeps the previous text and has no buttons. Guests never see the lists. If the Mac already answered, the sheet says This request was already decided.

Changing Mac settings from the phone

With a current Mac that announces the settings channel, Settings in the phone app gains a Mac settings section for each connected Mac. It mirrors that Mac’s switches, and a change runs through the same setter as the switch on the Mac itself: it takes effect on the Mac immediately, and the Mac pushes the new state back to every connected device.

Automatic — Auto-continue, Stop and wait instead, Auto-pilot, Approve plans automatically, Retry on provider errors.
Child sessions — Child sessions, Max per parent (stepper, 1 to 20), Choose model automatically.
Mac notifications — Push to this iPhone, Include child sessions, Mute while at the Mac, and the reason toggles Needs permission, Done and waiting, Has a question, Plan approval, Session errors, Board activity — the same switches Settings → General → Notifications shows on the Mac. The one exception is Hide names in iPhone notifications: that privacy switch stays on the Mac.
Delete guard — shown but never editable from the phone: the switch is disabled and carries the Mac’s reason, Deletion protection can only be changed on the Mac.

A row can also be locked because its configuration does not exist yet — Approve plans automatically stays read-only until a matching auto-approve rule exists and says Create a matching auto-approve rule on the Mac first. When the Mac rejects a change (locked, out of range, unknown), the row rolls back to the Mac’s value and the Mac’s message appears under the section. If the change never leaves the phone or the Mac does not confirm it, the row rolls back the same way and says The Mac did not confirm the change. Keys the phone does not know are simply not shown.

Against an older Mac that does not announce the channel, the section does not appear — everything stays as before and you change settings on the Mac. A guest device never receives the snapshot.

Editing usage limits from the phone

The Usage & quota screen adds Edit limit to each account card your Mac addressed with its opaque account reference. The editor lists exactly the windows your Mac’s limit editor offers for that account:

A Custom limit switch per window, with a slider from 5 % to 95 % in 5-point steps (turning it on starts at 80 %) — the same values the Mac’s Limits control accepts.
Pause this account.
vord only, and only when the Mac offers it: Release weekly limit — Lets this account keep working after its weekly window is spent. Your Mac still counts every run. While it is active, the card shows the Limit released badge.

Refresh in the overview toolbar runs the same update as Refresh in the Mac’s usage dashboard; the provider filter only changes what the list shows on the phone. As with settings, a change applies on the Mac immediately and a rejected one rolls back with the Mac’s message. An account your Mac no longer knows says This account is no longer known to your Mac. instead of editing. Guests never get the editor, and against an older Mac the cards stay read-only — limits are changed on the Mac.

Approving external start requests

When an external AI app asks to start a session on your Mac, the inbox entry carries a Review button that opens the approval sheet — client, project, agent, model, full prompt, time remaining, Reject and Start. Full behavior is covered on Let AI apps start sessions.

Sending images (single and group)

Attach a screenshot or photo to your next prompt, the same way ⌘V works on the Mac.

Tap the photo button to the left of the compose field — it stays visible in every view, so you do not need to swipe the special-keys row.
Choose Paste from clipboard or Choose from Photos. Paste from clipboard is always listed and works with every image format, including HEIC photos and WebP images from the web. vord only reads the clipboard when you tap it; if it holds no image, a short note says so.
A preview card appears above the compose field.
Type optional accompanying text, then send — image and text go as one prompt.

You can also paste an image straight into the compose field: tap or long-press the field, choose Paste in iOS’s edit menu (or press ⌘V on a hardware keyboard). The image becomes the same preview card above the field instead of landing in the text. Pasted text always arrives as plain text; formatting from other apps is dropped.

iOS may ask once whether vord may paste from other apps. If you chose Don’t Allow Paste, Paste from clipboard reports an empty clipboard; change it under iOS Settings → vord → Paste from Other Apps.

While the Mac is reconnecting, the photo button stays visible but dimmed and says the Mac isn’t ready yet. Against an older Mac that can’t receive images, the same button stays visible and explains that — it never sends an image over the wire.

For multiple photos at once: tap the photo button → Choose from Photos → select several → optional shared caption → send. The preview card shows a scrollable thumbnail row with individual remove buttons.

Image attachment preview card above the compose field

Attaching documents from Files

The same attach button also offers Files when your Mac is current. Pick one or more documents from iCloud Drive or On My iPhone; they join the same attachment list as images (a document shows as a chip with its name and size) and travel as one prompt with the optional text.

Each document is limited to 32 MB. A larger file is not attached — the compose field shows This file is larger than 32 MB. instead. For a document, the Mac saves a copy in its managed remote-attachment folder and inserts that path into the session, exactly the way image paths are inserted. This needs a current Mac build that announces document support; against an older Mac the Files option is not shown at all.

Voice dictation (Skald)

Press and hold the microphone button in the command zone (grant microphone access the first time), speak, and release to finish. While you’re holding it, the live transcript grows in the compose field as you talk — the full running text, not just your last sentence, so pauses between thoughts don’t lose anything. Release, and the complete raw transcript appears instantly; a moment later Skald’s cleaned-up version replaces it, still editable.

See Skald Dictation for how the desktop side of this works.

Scrolling back through history

In the terminal view, drag past the beginning of the loaded history to load older lines from the Mac automatically. This This requires the scrollbackHistory capability on both sides; without it, history ends at the original attach replay (a tail of up to 128 KiB).

History

Closed sessions stay on your Mac and stay reachable from the phone. Open the “…” menu in the header and tap History for everything, or open a project’s menu in the Sessions list for that project’s history. Entries come with the most recent activity first, same as the Mac history.

Tapping a row shows its transcript read-only. Open restores the session on the Mac and takes you there. If the project already has an active project lead, opening an archived lead takes you to that active lead instead of restoring a second one.

Against an older Mac without history support, the History entries stay hidden.

Automations

The Automations entry appears in the header’s “…” menu when at least one of your own paired Macs supports automations. The list follows the Mac’s order, with one section per capable Mac when more than one supports it. Each card shows its schedule and next run, project, origin, agent and no catch-up, along with the last run’s open board items and reason, recent run sessions and finished runs.

Use the switch to pause or resume a job. Work now and Run once · Automation paused appear as they do on the Mac. Open takes you to a live session or its read-only transcript in History. Agent requests to change or delete an automation appear at the top and can be approved or rejected. Create, edit and delete automations on the Mac. Guests in shared sessions do not see automations.

Timeline

Open the “…” menu in Session Detail and tap Timeline — or Saved checkpoints, when the session belongs to a Cowork-cloud project. The list is newest first, like the Mac Timeline tab. Scroll to load more.

A row shows the turn (or the saved-state label in Cowork), when it was saved, and how many files changed. Markers call out a safety point Before restore, a checkpoint Restored here, commit and fork counts, and Parallel when other sessions worked in the same folder.

Tap a row for that turn’s diff: each file with its added, removed, and context lines, in monospace. If the Mac had to shorten the payload, a line at the top says how many files and lines you are seeing, and that the full diff is on the Mac.

Tap a line to write a comment. In a Cowork-cloud session the same action is Please change…. A context menu Extend to here stretches the last comment on that file and side to the line you chose. The bar under the diff shows N comments, Send, and Discard — discard asks for confirmation on that button. Send needs timeline support on that session’s Mac. After a send the phone says Sent. or Will be sent when the session is ready. Draft comments stay in memory on the phone until you send or discard them; they are not the same store as the compose-field draft.

Restore to here… puts the session’s files back at that checkpoint, after you confirm on that button. Uncommitted work is kept as a safety point. Branch off from here starts a new session from that checkpoint; in Cowork the same action is New conversation from here. vord does not restore while the agent is working — the phone then says Wait until the agent is finished.

The menu entry appears only when that session’s Mac announces timeline support. An older Mac, or a Headless host that does not announce it yet, hides the entry. Guests of a shared session do not get the timeline.

Ending a session from the phone

Open the “…” menu in Session Detail and tap End session, then confirm. This terminates the Mac process, not just your phone’s view of it — only available for your own (host) sessions, not sessions you’ve joined as a guest.

Build runs started from this session through the build gate keep running after it ends. On Macs that support build-run reporting, End session lists them in the confirmation dialog first; otherwise, the dialog is unchanged.

Media the agent shows you

When an agent calls show_to_user and your phone is in the foreground, an image or URL opens full-screen immediately. General files stay as private snapshots and open from the “Shown to you” list when you tap them. A Markdown file opens formatted there — headings, lists, tables, and code — with the entry title or the file name in the header, and a share button. Other files open in the system preview with that same header. Everything shown during the session (seen or missed) remains reachable, so nothing gets lost if you weren’t looking at the right moment. Full behavior and how this interacts with the Mac preview are covered on Showing Things to You.

kimi on the phone: new, with the basics solid

kimi sessions get the same chat view as claude and codex, read from Kimi’s own session log (agents/main/wire.jsonl): prompts and steers appear as bubbles, answers as Markdown, and tool calls as one-line entries. Two Kimi-specific rules apply: messages that Kimi’s log does not attribute to you (such as a completed background job or an instruction to a swarm worker) do not appear as your messages; swarm workers do not get their own chat and remain in the subagent hierarchy on the tile.

kimi sessions mirror, start from the phone, report status, and show kimi’s permission, plan, and question boxes through the same answer-card path everything else uses — including kimi’s bracket-style question options (→ [1] …), which arrive as tappable cards like any other box. A tap on a kimi card sends the bare option digit, which kimi accepts as an immediate choice (its own footer says so: 1-3 / ↵ choose) — no arrow-key dance, and no pasted Return that kimi would misread as a composer newline. The permission-mode key covers kimi too (single-step plan toggle, see above), and a limited kimi session shows the ⏳ limited status like any other; since kimi’s messages name no reset time, a countdown appears only when the account’s quota data backs one.

Notifications and usage limits

Status changes (waiting on you, done, has a question, plan ready, session failed) generate an interrupting notification, and a session simply ending lands quietly in the notification inbox instead — check the bell rather than expecting a banner for it. Hitting a usage limit never makes the Mac send a “done” notification. Rate-limited sessions show a live countdown instead of a plain “rate limited” label whenever the reset time is backed — stated by the provider or taken from the account’s quota data; a limit whose reset is unknown shows the limited status without a countdown. Both are covered in full on their own page.

A rate-limited session stays fully operable from the phone: the control-keys bar and the compose field remain available, so you can continue the session manually at any time (for example once you know the limit has cleared) — input goes straight to the session’s terminal, exactly as it would on the Mac. Only an exited session hides the input zone.

When the usage brake holds automation for a session’s account, the session row carries a short brake badge with the waiting state. Guests of a shared session never see it.

See Notifications on iPhone for the notification behavior and the five per-reason toggles in Settings, and Usage Limits & Auto-Continue for where a reset time comes from.

What codex can’t do here

Collected in one place, the codex gaps you’ll hit while controlling a session from the iPhone:

Feature	claude	codex
Multi-question stepper	Full stepper with Next/Submit	Each sub-question shown in isolation, no stepper
Write your own answer	Delivered as a real tool answer via “Type something.”	Delivered as a real tool answer via the notes field (Tab)
Permission mode display	Full mode + red warning on risky modes	Neutral glyph always — no warning even in the riskiest mode
Permission mode change	Direct-pick list, jump to any mode (inline “Really?” before entering a risky mode)	Single-step cycle via `/permissions`, one tap = one step
Model change	Tap a model to switch straight away (`/model <name>`) — at the price of also setting your global default	No direct pick at all: codex couples model and thinking depth in one dialog, so the list is read-only and you go through codex’s own picker
Usage-limit countdown	Live countdown to reset	Live countdown when codex states the time (“try again at …”) or quota data backs it; otherwise the limited status without a countdown

None of this is a phone-side limitation — it traces back to codex not exposing the same hooks and structured state that claude does on the Mac. See Claude vs. Codex vs. Kimi for the full picture beyond the iPhone.

When a Mac cannot start an agent

The new-session sheet keeps unavailable agents visible but greyed out and explains why: Not installed on your Mac or Not signed in on your Mac. This detail appears when the Mac provides it; older Macs keep their previous behavior.

A child session whose report is ready also has a Read report action in its child row or detail. It opens the Markdown report formatted, with the child session’s name in the header and a share button. The report is fetched for viewing and is not kept on your iPhone.