Features

Mobile and notifications

The point of the phone is not to write code on it. It is that a run which stopped four minutes in should find you, instead of waiting until you walk back to the desk.

Setting this up for the first time? Run Claude Code from your phone walks through it in order, start to finish.

Install the app

Termdeck installs as a progressive web app, so there is no store download and no separate build to keep updated.

Open termdeck.io/dashboard in Safari, tap the share button, and choose Add to Home Screen.

On iOS this step is not optional if you want notifications. Safari only allows web push for a site that has been added to the home screen, and only from the icon rather than from a browser tab. This is the single most common reason people report that notifications do not work on an iPhone.

Turn on notifications

Go to Settings, then Notifications and select Enable beside Push on this browser. The line under it says whether your browser allows notifications, has blocked them, or has not been asked yet. Your browser asks for permission once. Termdeck then registers this device, so each phone, tablet, and desktop is subscribed separately and you can keep the phone loud and the desktop quiet.

Push needs a secure context. On termdeck.io that is always true. If the option says not supported, the browser itself lacks push rather than something being misconfigured.

What can notify you

EventFires when
Approval requestsA tool needs your permission before it can run.
Questions and plansThe agent asks you to decide something.
Turn finishedA turn finishes in any chat on your machines, whether you started it from Termdeck or in a terminal.
Run failedA turn ends with an error.

Every chat notifies, including chats in folders you have not added to the sidebar and chats hidden by the sidebar filters. A chat you are running in a terminal sends Turn finished when its turn ends, but never an approval or question alert: a prompt raised in a terminal can only be answered in that terminal, so answer it there.

Each event has its own menu under Notify me about. Open it and tick any of Push, In-app and Sound; the button then lists what you picked, or says Off. Push can only be ticked once this browser has push enabled. A reasonable starting point is push for approvals and questions and not for turn finished, because a finished run is something you go and look at while a blocked run is something that needs you now. The same goes for the sound: you can chime for approvals and stay silent when a turn finishes.

Logging out of a browser stops its notifications, and so does changing your password from another device. They come back on their own the next time you sign in on that browser, as long as it still allows notifications.

This browser remembers your choices, and Quote what the agent said with them. Disabling push and enabling it again, or the browser renewing its subscription on its own, keeps what you chose. Phone preview, under that switch, shows what a push looks like on a lock screen with quoting on and off.

While you are using Termdeck

An alert never lands on one device while you are working in another. When you are using a Termdeck window, that window raises the alert itself, as a popup in the top right corner and a sound, and nothing is pushed to any device on the account. Chats other than the one on screen are covered too, so a run finishing on a different machine still reaches you, in the window you are actually looking at.

Push comes back as soon as you leave that window. Locking the phone, switching to another app, and switching tabs all count as leaving, so an alert that fires the moment you put the phone away still reaches it. If the page never got the chance to say it left, a closed laptop for example, push comes back within about a minute.

A window left open and focused on an empty desk stops counting after three minutes with no typing, clicking, or mouse movement, so your phone takes over. The window still shows the alert when you come back to it.

In-app popups keep up to four cards in the top right corner, with status notices in a separate bottom corner. Swipe a card sideways to dismiss it, or use its close button. Dismissing an approval popup leaves the request available in the bell and the Approvals page. Scrolling vertically over a card keeps it open.

Approving from a notification

Approval notifications carry Allow and Deny buttons, so a blocked run can be unblocked without opening the app. Each notification carries a single use token that expires after 5 minutes, the same five minutes after which an unanswered approval is denied, which is why answering an old notification asks you to open the app instead.

An approval notification arrives about two seconds after the request, and only if it is still waiting then. A request that a Claude Code hook or rule on your machine answers straight away never sends one.

An approval you answer somewhere else, one that times out, and one whose run ends all take their notification with them. A device with Termdeck open clears it within seconds; a locked phone clears it the next time you open Termdeck on it.

Notifications are always free, on every plan. Watching your agents and unblocking them is never something Termdeck meters.

In app alerts

Separately from push, the interface keeps its own count of everything that needs you: the badge on the bell at the foot of the sidebar, the badge on the tab title, and the Approvals page. All three are computed from one list, so they cannot disagree with each other.

What counts is deliberately narrow: a waiting permission, a waiting question or plan, and a turn that failed. A turn that finished cleanly and has not been opened yet does not count as something that needs you. It shows a small green dot on the bell instead, and is listed under Earlier when you open it.

Clear all at the top of the list empties Earlier and dismisses failed turns, on every device, without opening each chat. A waiting approval, question or plan stays until you answer it.

When something lands, a popup drops in at the top right and the bell rings. A waiting approval, question or plan glows as it arrives and stays until you answer it, here or anywhere else. A finished turn leaves on its own after a few seconds; hold the pointer over it to keep it. Select the popup to go to the chat. No popup appears for an approval whose card is already on screen.

On the Terminals page notifications lead to panes instead of chats: Go to pane switches to the window holding that chat and highlights its pane, or opens it in a new pane if none holds it. A popup that arrived while you were on Terminals still goes to the pane after you have left the page. Choose which events pop up and which play a sound in Settings, then Notifications: untick In-app or Sound in an event's menu. If you had turned popups or the sound off before these became per event, that choice was copied to all four events.

Using Termdeck on a phone

Everything is reachable on a small screen. The sidebar becomes a drawer, the transcript takes the full width, and the dock opens over it.

Outside a chat, the bar at the top holds only the menu button, which opens the sidebar as a drawer, and +, which starts a new chat. The bell, your account and Settings are at the foot of the drawer, so the menu button wears a red dot while something needs you, inside a chat too, and the bell's list opens over the drawer. The top of a chat is one row: the menu button, the title over its project (and the machine), the context ring with how full the context window is, as a percentage (tap it for the breakdown), ⋯ and Files & agents. How many files changed shows as a number on the Files & agents button.

On Approvals each request leads with what it wants, with its risk word and the chat it came from under it. A plan's choices stack one above another, and the sidebar's rows, the tabs in Files & agents and the buttons on a request are all big enough for a finger. On Home the project moves under each chat's title.

  • Read a live transcript and follow tool calls as they run.
  • Approve or deny anything waiting.
  • Send a prompt, including a photo or a screenshot.
  • Read the diff of what an agent changed.
  • Stop a run that has gone the wrong way: while it runs, the round send button becomes a square stop button.
  • Switch account when a rate limit is reached.

Dictation uses the browser's own speech recognition where the browser provides it, which keeps audio out of any upload path.

Composer pickers and machine dialogs stay above the keyboard too. Scroll inside a picker or dialog to reach the rest of its content; closing a picker keeps your message draft. Machine dialogs close with their Close button or Escape, so a tap outside cannot discard an unfinished step.

When the keyboard opens, the chat resizes to the space above it: the message box sits on the keyboard's top edge, the header stays put, and the transcript keeps whatever room is left rather than sliding out from under you. The tray above the message box shows only its first row while the keyboard is up.

The model chip under the message box opens a sheet that rises from the bottom of the screen instead of a small menu. Choosing a model inside it swaps the sheet for the model list, with All options at the top to go back. Tap outside the sheet to close it.

When notifications do not arrive

Nothing arrives on an iPhone

Almost always the home screen requirement. Add the site to your home screen from Safari's share menu, open Termdeck from that icon, and enable push there. A subscription created in a Safari tab does not carry over.

Then check iOS Settings, Notifications, Termdeck, and confirm alerts are allowed.

The switch turns itself back off

The browser denied permission. Reset the site's notification permission in browser settings and enable it again. A denied permission cannot be re asked for by the page.

They worked and then stopped

Browsers expire push subscriptions, particularly after a long idle period or a browser data clear. Toggle push off and on in Settings, then Notifications to register a fresh subscription for that device. Your per event choices are kept.

Some events notify and others do not

Check the per event switches. Approval requests, questions and plans, finished turns, and failed turns can each be enabled or disabled for this device.

My phone stays quiet while I am at my desk

That one is deliberate. A Termdeck window you are using on any device silences push on all of them and shows the alert in that window instead. Leave that window, or stop typing and moving the mouse in it for three minutes, and the phone notifies again. See while you are using Termdeck.

They arrive late

Delivery goes through the browser vendor's push service, and aggressive battery saving on the device can delay it. On Android, exclude the browser or the installed app from battery optimisation. On desktop, keep the browser running rather than fully quit.

Pair notifications with a couple of auto allow rules. Rules stop the routine questions ever being asked, and notifications carry the ones that are genuinely worth interrupting you for.