On the Mac or Linux machine whose terminal you want to reach:
curl -fsSL https://tilde.yescomet.com/install.sh | shIt downloads a binary, checks it against the published checksum, and puts it in ~/.local/bin. Set INSTALL_DIR to put it elsewhere. On macOS you can also build from source — the repository is linked above.
tilde startThis installs a background service — a LaunchAgent on macOS, a user unit on Linux — so the agent runs now and after a reboot. tilde stop removes it again.
To try it without installing anything, tilde serve runs in the foreground until you press Ctrl-C.
tilde pairA QR code appears in the terminal. Scan it with the app, and the Mac will ask you to approve the device by its fingerprint. Nothing is trusted on the strength of a scan alone.
What you are approving is the machine, not the window: the device will be able to open terminals as the user running the agent, and to attach to that user's tmux and Zellij sessions. It cannot see terminal windows that are already open elsewhere — those belong to the programs that started them.
tilde devices # who is paired
tilde devices -revoke ID # remove oneOn the same network the app finds your machine by itself and connects directly. Somewhere else, it reaches it through a rendezvous that carries encrypted bytes it cannot read. The screen says which path it took.
Tapping a machine lists the sessions it has open, and the terminal you pick carries on where it was — the build still running, the agent still working, the output from before you arrived still on screen.
Only sessions inside tmux or zellij can be listed, and that is not a limitation we chose. A terminal belongs to the process that opened it, so a window in Terminal.app, iTerm, VS Code or Zed cannot be joined by anything, including us. Starting work inside a multiplexer is what makes it reachable later:
tmux new -s workTo see what your phone would be offered, without a phone:
tilde sessionsJoining a session someone is already using is allowed and sometimes what you want. The window then keeps the size of the larger screen, so your phone does not rearrange what the person at the keyboard is reading; you see the top-left of their window. With nobody there, the session sizes itself to the phone.
While the app is open, your Mac tells it what happened — a build ending, an agent stopping to ask a question. Nothing passes through a server for this, and there is nothing to set up.
Anything that exits can say how it went, whether or not it knows about Tilde:
tilde notify -- make releaseThe command runs normally, its output is untouched, and it exits with its own status. Your phone gets the title, the exit code and the last few lines — which is usually the part worth reading.
Claude Code can report by itself, since an agent waiting for an answer produces no output to notice:
tilde hooks # what it would add
tilde hooks -write # add itThat covers three moments: it needs permission, it needs you, it has finished. The rest of what an agent can report is noise on a phone. Existing hooks are never overwritten — if you have your own, the entries to merge are printed instead.
Pushes to a phone that is not open come later. For now the app has to be running.
A sleeping Mac answers nothing, and nothing can wake it from the outside. So while your phone is attached, the agent keeps the machine awake, and lets it sleep again the moment you disconnect. It is in the log when it happens, and tilde serve -no-wake turns it off.
For work that outlasts the connection, hold it awake around the command itself:
tilde awake -- make release
tilde awake -for 2h
tilde awake -statusThe hold ends when that command does, so there is nothing to remember to turn off. Every hold is bounded — twelve hours at most — and released early if the battery falls below 20%, because the worst outcome here is a laptop that arrives flat.
One thing it cannot do: a closed lid sleeps anyway, unless the Mac is on power with an external display. No hold outranks that.
If the phone changes network or loses signal, the terminal keeps running on your machine. The app reconnects and replays what it missed. If the gap was longer than the agent could hold — about two megabytes of output — the screen is cleared rather than continued from the middle of an escape sequence.
Restarting the agent is different: that ends every session. Anything inside tmux or zellij survives it, which is the main reason to work inside one.
tilde update -check # is there something newer
tilde update # install itReleases are signed, and the agent checks the signature against a key built into it. An update it cannot verify is refused rather than installed. Installs owned by Homebrew or a system package manager are left to those instead.
A running agent checks once a day and only says so in its log; it never updates itself while you are using it.
| What you see | What it means |
|---|---|
| The app lists nothing under “on this network” | iOS asks for local network permission the first time. If it was refused, turn it back on in Settings → Tilde. A machine started with -no-advertise never appears and is reached through the rendezvous instead. |
| “The host refused” | That device is not paired, or its access was revoked. Run tilde pair again. |
| Pairing says the port is taken | Expected while the agent is serving: pairing steps aside to a temporary port and says so. Nothing to do. |
tilde status says “not installed” |
The agent is not set to run in the background. tilde start. |
| The session list is empty | Nothing is running inside a multiplexer. Anything you started in a normal terminal window cannot be joined — start it with tmux new -s work instead, and it will be there next time. tilde sessions says the same thing from the machine itself. |
| A session you tapped will not open | It ended between the list being drawn and your tap. Pull the list down to refresh it. |
| Sessions end when the Mac sleeps | A sleeping machine cannot answer, and nothing can wake it from outside. Keep it awake for the work you are running, or keep that work in tmux so it survives. |
tilde stop
rm ~/.local/bin/tilde
rm -rf ~/.config/tilde # keys and paired devicesDeleting the configuration unpairs every device: they hold keys for a machine identity that no longer exists.