Docs

Getting started

Install the agent, pair your phone, and open a terminal from anywhere.

Install the agent

On the Mac or Linux machine you want to reach:

curl -fsSL https://tilde.yescomet.com/install.sh | sh

It downloads one binary, checks it against the published checksum, and puts it in ~/.local/bin. Nothing runs as root and nothing is installed system-wide.

One command

In the terminal window you are working in:

tilde share

The first time, it does everything the first time needs: shows a code to scan, starts the agent so it keeps running after the window closes, and hands this window over. After that it just hands over the window.

Keep working as you were. Nothing is intercepted, no keys are captured, and the shell is the one you always use — it is simply owned by the agent now, which is what makes it reachable and what makes it survive the window closing.

To pair another phone later, or to see what is running:

tilde pair
tilde status

Reaching it from anywhere

On the same network the app finds your machine by itself and connects straight to it. Somewhere else, it reaches it over the internet, through a relay that carries encrypted bytes it cannot read. The screen says which path it took.

Joining something already running

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 work

To see what your phone would be offered, without a phone:

tilde sessions

Joining 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.

Knowing when something finishes

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 release

The 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.

Much of the time nothing is needed at all. Your Mac watches a session's own output for the marks a shell leaves when a command ends, and for the ones programs use to ask for a notification. A command that finished in a moment is ignored; one that took a while, or that failed, is not. If your shell has no integration, wrapping the command as above always works.

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 it

That 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.

When something did not reach you, ask the Mac why:

tilde notifications

Usually the answer is a rule working as intended — you were looking at that session, nothing is paired, the host has nowhere to send it through. Each line says which.

Sleep

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 -status

The 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.

Losing the network

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.

Updating

tilde update -check   # is there something newer
tilde update          # install it

Releases 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 every few hours and installs what it finds. Nothing you have open ends: the agent takes the new version into use in the same process, terminals included, and a phone reconnects within a second. If it cannot do that at the moment, it leaves you on the version you have and tries again later rather than restarting. The commands above do the same at once.

When something is wrong

What you seeWhat 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 over the internet 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.

Removing it

tilde stop         # stop the agent, and keep it from starting at login
tilde uninstall    # remove it altogether

tilde uninstall says what it will remove and asks first. It stops the agent, takes out the Claude Code hooks and editor settings that tilde hooks -write and tilde editors -write added (backing each file up, and leaving alone anything you changed by hand), and deletes the binary, its log and its data. Sessions in tmux and Zellij are not touched.

Deleting the data unpairs every device: they hold keys for a machine identity that no longer exists. Remove the machine from the app as well.

Support

Something wrong, missing or unclear? Write here, or from the app: Send feedback at the bottom of the home screen. Leave an address if you want an answer. A screenshot helps more than a description of one.

Or by email: support@yescomet.com. What the form sends, and what happens to it, is in the privacy policy.