The phone app shows what is happening in Tori on your Mac and lets you act on it while you are away from the desk. It is a window onto the Mac, not a second Tori: the agents keep running on the Mac, and the phone talks to it over Tailscale. Pair it first, see Pairing and remote access.
Find a session
The app opens on your projects.
- The space switcher along the bottom picks a space, like the tiles on the Mac. Each space shows its status bubble. When folders are attached on the Mac, Home is there too, listing them like a space’s projects. Chats stay on the Mac.
- Projects lists the space’s own Topics first, under Topics with a + for a new one, each naming its members. Then the space’s projects, each with its status rollup and how many sessions are running.
- Topics, in the bottom bar, is titled Topics, all spaces, and lists the Topics that belong to no space, each naming the spaces its members come from.
- The search button searches Projects, worktrees, sessions at once.
Tap a project for its worktrees. Each worktree card shows its branch, the lines changed, its commits ahead and behind, its pull request and checks, and an issue chip, the same facts the desktop sidebar shows. A worktree the autopilot is working in is tinted violet.
A git project also has Fan out, the same as on the Mac: say what the attempts are for, pick 2, 3 or 4, and Tori makes that many attempts, each a worktree on its own branch named from the goal. Promoting one attempt deletes the others, so Promote this attempt stays on the Mac. See Fan out.
In a project that shows branches rather than worktrees, Attach a branch under the list shows an existing local branch there, the same as picking a local branch in the Mac’s add branch dialog. Type its name and tap Attach.
Spaces and Topics
Tap Spaces next to the space’s name for the Spaces sheet:
- The arrows move a space up or down, in the order the Mac shows too.
- Edit sets a space’s colour (Auto derives it from the name) and icon (the first tile wears the space’s initials).
- New space makes a folder of that name in Tori’s base folder, with the colour and icon you pick.
Deleting a space removes its folder and everything in it, so it stays on the Mac. See Spaces.
New Topic, at the end of the Topics tab or the + over a space’s Topics, takes a name and the repositories in it, each Worktree (its own worktree on the branch) or Reference (read only, the repository’s own checkout). The branch is made from the name, as on the Mac. Where puts the Topic in the space you are on, the default, and lists Projects in work only; or in Topics, listing every space’s projects under its space.
A Topic shows the space it belongs to under its name, or Topics for one of no space.
A Topic’s More has:
- Rename.
- Add a repository: one of your projects not in the Topic yet, as a worktree or a reference. A Topic in a space offers only that space’s projects.
- Move to: Topics or a space. A space that does not hold every member is greyed, saying which members are elsewhere, the same as on the Mac.
- Promote a member: a reference member gets its own worktree on the Topic branch.
- Move a member up: one place, in the order the Mac shows too.
- Delete Topic: only the Topic goes; its worktrees and branches stay.
A worktree’s More has Move to Topic, which adds the worktree to a Topic as it is, on its own branch. It lists the Topics of the worktree’s space first, then those of no space. See Topics.
A worktree
A worktree shows its branch and standing, then its sessions in two groups: Now, what is running, and the rest as history, grouped by when they were last active, the same sessions as the Mac’s History dropdown. Tap a session to open it. An ended chat opens with its transcript and a box that reads Message to resume: what you send there resumes it, on the Mac too.
More (the three dots) has Move to Topic and Remove worktree, for a worktree in a project. The phone asks Remove worktree “name”? first. The branch stays, and so does everything committed on it. The phone never forces the removal: a worktree with uncommitted changes, or with a session still running in it, is refused with the reason, so commit, or close the session, first. Deleting the branch with it stays on the Mac.
New opens the New session sheet. Pick where the session runs, then tap Start:
- Here: in this worktree.
- New worktree: on a new Branch, made From the ref you type, or the default branch when From is empty. The project’s setup command runs in it first, as on the Mac.
- From an issue: pick one of the issues assigned to you. Tori makes a worktree on the issue’s suggested branch, the worktree remembers the issue, and an empty First message sends the issue’s title and body.
- Review a PR: pick one of the pull requests waiting on your review. Tori makes a worktree on its head, forks included.
New worktree, From an issue and Review a PR show only for a worktree that belongs to a project.
The sheet also has:
- Agent: the agents that run as a chat, starting on the one last used in this worktree.
- Account: shown when the agent has more than one account, with each account’s email when Tori knows it.
- First message: optional; the session starts and waits when it is empty.
- Run in background: starts the session as background work. At the default execution level it runs boxed, in the agent’s own sandbox. See Unattended sessions.
A session you start in the foreground counts as watched while the app is open, so at the default level it is not boxed even with the Mac’s lid closed. Pick its model and mode in the chat once it opens.
Read and steer a chat
A chat looks the way it does on the Mac: prompts, replies, tool calls, diffs. Scroll up and earlier history loads in pages.
- Send a message. While a turn runs, the box reads Steer the running turn: what you send goes into that turn, as a steer. Otherwise it starts the next turn.
- Switch model, effort or mode from the pickers in the box. Effort shows for a model that lists effort levels. A switch applies from the next turn.
- The agent’s own options, when it has any, sit beside them: a picker for a choice, a chip that turns on or off for a switch. They are the same options the Mac shows for that agent.
- Slash commands. Type
/and the agent’s commands show above the box, narrowing as you type. Tap one to put it in the box. - The plan card shows above the box while the agent has a plan, the same steps the Mac shows.
- Context and cost show in one line above the box: the context used out of the model’s window, with its share, and what the session has cost so far.
- More has Stop (stop the running turn), Rename, Close session, Changes, Send to a new chat, Fork this chat, Copy session id and Open worktree.
- Rename names the session on the Mac too. Leave the name empty to go back to its title.
- Close session ends a running chat, as closing its tab on the Mac does. It moves to the worktree’s history, and a message there resumes it.
- Send to a new chat starts a new chat in the same folder, on the same agent, with what is in the box (and its attachments) as its first message.
- Fork this chat starts a new session that carries this conversation on, on the same agent. It shows once the chat has a turn.
Changes and reverts
More > Changes lists the session’s turns that changed files, each with how many files. All changes at the top is everything the session changed, as one diff. Tap a turn for that turn’s diff.
Rewind on a turn puts the worktree’s files back to how they were before that turn: what the session wrote in it and in every turn after it is undone. The phone asks Rewind the files to before turn N? first. Tori takes a backstop before rewinding, so the Mac’s checkpoint timeline can bring the files back. Unlike a rewind on the Mac, the conversation is not cut: it goes on as it was, and the agent still remembers writing what was undone. A rewind is refused while another live session works in the same folder.
A tool call that edited files opens to its diff, the same as on the Mac. Revert on one hunk asks Revert this hunk of name? and puts only those lines back.
Attach photos and files
The paperclip next to the pickers attaches files to your next message:
- Photo library: one or more photos or images from the phone.
- Camera: take a photo now.
- File: one or more files from the phone’s file picker.
Each file uploads to your Mac as soon as you pick it, into
~/.config/tori/attachments/, the same place the Mac’s composer writes to.
Its chip reads Uploading until the upload finishes, then shows its label
and name; the x removes it. Send waits until every upload has finished, and
a message can be attachments alone.
Labels are numbered by kind within the message, [Image 1], [PDF 1],
[File 1], and Tori adds them at the end of your text, so you can write
“compare [Image 1] with [Image 2]”. The agent reads each file from its path
on the Mac.
Limits:
- A photo larger than 2048 pixels on its long edge is scaled down on the phone and sent as a JPEG, so camera photos fit.
- The phone sends files up to 8 MB; a larger one is refused with its size. Images and other files are also held to the Mac’s 5 MB limit.
- Up to 10 attachments per message, and the same kinds the Mac refuses (video, audio, archives, Office documents) are refused here.
- Claude takes images, PDFs and any other file. The other agents take files only, and refuse an image or a PDF when you send.
See Attach files and images for the Mac’s side.
Answer what is waiting
Whatever a session is waiting on shows as a card at the bottom of its chat, and the session’s dot turns rose in the lists:
- A permission prompt: Allow Bash? with the arguments, and Allow once or Deny.
- A question: its options as buttons, or Or type an answer.
- An approval from the autopilot: the draft, Show the draft to read all of it, and Approve or the other answers.
- A worker’s question: marked A worker asks.
Answering from the phone is the same as answering on the Mac; the card closes on both. To allow one command for every worker asking for it, use the Inbox’s Permissions tab instead.
The Inbox
The tray button in the bottom bar opens the Inbox, with the same four tabs as on the Mac, the first one labelled Since. The button counts the Needs you rows you have not answered plus the sessions waiting for review. See The Inbox.
Since you looked lists what happened since you last looked: finished sessions with their lines and verdict, pull requests, usage limits and what still waits on you. The Inbox opens on it when it has something. It counts as seen when you leave the tab or put the app in the background, and the Mac then starts from the same point. See Since you looked.
Needs you lists what needed you in the last day, grouped by project, with answered rows dimmed. Tap a row to open its chat, where a waiting approval or question sits above the message box; a pull request row opens its worktree. Opening a chat on the phone, from anywhere, answers its Finished rows and its branch’s pull request rows, on the Mac too.
Permissions lists every permission prompt waiting right now, grouped by project and then by the command asked, the same as on the Mac. Always allow for all and a number answers the whole group with Always in this project, Deny on a row denies that one prompt, and tapping a row opens its chat. See Permissions.
Review lists sessions with work you have not reviewed yet, riskiest first. Each card shows the score, the session’s name, folder and agent, its last reply, and the signals behind the score.
- Approve marks the session reviewed, the same as Mark reviewed on the Mac, and the row leaves both lists. While the session is still working the button reads Still working and does nothing.
- Reply opens the session’s chat to send it a message. It shows only while the session is live; an ended session has no Reply.
The autopilot
The wheel in the bottom bar opens the autopilot, with the same time of day scene as the Cockpit:
- Set sail and Drop anchor start and stop it.
- Chat is its own conversation, with Message the autopilot to hand it work.
- Decision cards for anything waiting on you.
- Crew, the workers running now, and Log, what happened.
See Autopilot.
Alerts with the app closed
The app only hears what happens while it is open and connected. To hear about a session that needs you with the app closed, turn on Settings > Alerts when closed. The phone asks for permission to show notifications the first time.
When a session needs you or finishes, the phone shows a notification with the project’s name and what happened:
- A session needs approval, A session has a question, A session is waiting, A session hit its budget, A session had a command blocked, or A pull request needs a look.
- A session finished when a turn ends.
Tap it and the app opens that session’s chat, saying Opening a session in and the project’s name while it connects. Answer the session on the Mac instead, and the notification goes away on the phone by itself. A session that alerts again replaces its earlier notification rather than adding one.
The Mac sends nothing for:
- a session you are looking at on the Mac, with its window focused;
- a worker whose question reaches you through the chat that spawned it, or through the autopilot;
- anything at all while Remote is off in the Mac’s Settings.
The Mac’s own notification switches do not change what the phone gets. An alert the phone cannot receive within an hour, because it is off or offline, is dropped.
Disconnect in Settings turns alerts off on the phone. Removing the phone in Settings > Remote on the Mac stops them as well.
What leaves your Mac
Alerts travel through Google’s push service (FCM) and a small relay Tori runs
at relay.gettori.app, because only a push service can wake an Android app
that is closed. Each alert is encrypted on the Mac with a key the phone made
and sent to the Mac when you turned alerts on, so neither Google nor the
relay can read it. The relay stores nothing.
- The relay sees your Mac’s IP address, when an alert is sent, and how large it is.
- Google sees your phone’s push token and when an alert is sent.
- Neither sees the project, the session, what it needs you for, or any path. Those are inside the encrypted alert, and only the phone opens it.
When the switch stays off
The switch turns back off and says why when alerts cannot work:
- Notifications are off for Tori. Turn them on in Android settings. You declined the permission. Allow notifications for Tori in Android’s settings, then turn the switch on again.
- This phone has no working Google Play services, which alerts with the app closed need. Phones without Google’s services, such as many de-Googled ROMs, cannot get alerts with the app closed.
- Tori on your Mac is too old for alerts with the app closed: update Tori.
- Connect to Tori first. Turning alerts on needs the phone connected to the Mac.
- This build of Tori has no push setup. An app built from source without Tori’s Firebase config cannot get alerts. The release APK has it.
Settings
The gear opens a sheet:
- Connection: the Mac’s address, this phone’s name, the status, and Disconnect, which forgets the Mac on the phone. Revoke the phone in Settings > Remote on the Mac too, to remove it there.
- Alerts when closed: notifications on this phone while the app is closed. See Alerts with the app closed.
- Appearance: Tori Dark or Tori Light, kept on this phone.
- Autopilot button: whether the wheel shows in the bottom bar.
If the Mac revokes the phone, the app says This phone was removed from Tori. Pair it again to reconnect.
When the app and Tori disagree
Tori on the Mac updates itself, but the app updates only when you install a newer APK. When the two no longer speak the same protocol, the app says which one to update in a banner instead of failing:
- Tori on your Mac is too old for this app: update Tori. Update Tori on the Mac, from the update notice in its title bar.
- This app is too old for Tori on your Mac: update the app. Install the newer APK from the releases page. A release that needs a newer app says so in its notes.
What the phone cannot do
The phone can read everything, steer, stop, answer, approve, review finished work, start a session here, in a new worktree, from an issue or as a pull request review, in the foreground or the background, attach photos and files, switch a chat’s model and mode, rename, close and resume sessions, remove a worktree, attach a branch, make, edit and reorder spaces, make and change Topics, fan out, fork a chat, read and revert a session’s changes, and start or stop the autopilot. It cannot delete a session or a space, promote an attempt, delete or check out a branch, or pair another device. Those stay on the Mac.
Platform
The app is for Android, as an APK on the releases page, not through the Play Store. See Install. An iOS app is planned.