Run Claude Code on your iPhone or iPad

Does Claude Code run on the phone?

Claude Code is a program on the disk of some machine you own. A shell starts it. It reads your project through that machine's filesystem, runs git and the tests, and writes its edits back into the same directory. None of that happens in your pocket, though the phrase suggests it does.

From the phone, two things cross the wire: keys go out, characters come back. The agent is not installed there, and no copy of your repository travels. The phone draws a picture of a session running on another computer.

• On the phone. Keystrokes, the display, your thumb. Lock the screen or swipe the app away and the display stops, and that is the whole list.
• On the machine. The process, the files being edited, the tests, and everything the agent has already read and decided. None of it notices your screen going dark.

Two consequences follow. The machine has to stay on and reachable: a laptop closed in a drawer runs nothing. The phone is the cheap half to replace.

Three things to set up, in this order

Skip one and the arrangement fails, so work through them in this order.

1. A door into the machine. On a Mac: System Settings → General → Sharing → Remote Login. On Linux, the SSH service, a daemon called sshd.
2. A private network instead of an open port. Install Tailscale on the machine and the phone, sign both into one account, then connect to the MagicDNS name or the 100.x address. Do not use a LAN address such as 192.168.1.23, which means nothing on mobile data. Forwarding port 22 instead hands your machine to every scanning bot that finds it.
3. A tmux session with a name, and the agent inside it.

tmux new -s work     # name it
claude               # inside it

From the phone, on another network:

tmux ls              # what exists
tmux attach -t work  # open a window onto it

The name matters: tmux attach on its own takes the most recent session, and that is a guess about which one you meant. If tmux is missing, Agentmux installs it.

Why a plain SSH window kills the agent

Skip tmux: you SSH in, run claude, then put the phone in your pocket and lock the screen.

The phone stops sending packets, the connection times out, and it closes. sshd closes the pseudo-terminal that connection was attached to, and the kernel sends SIGHUP to every process still attached to it: your shell, and Claude Code running inside your shell. Both take the default reaction and exit, so the agent dies mid-edit with twenty minutes of reading gone.

Keeping the app open fixes nothing. Wi-Fi switches networks, cellular loses signal, one Ctrl-C lands somewhere it should not. tmux moves the session onto the machine itself, so a dropped connection takes the window and leaves the process alone (the mechanism). The agent goes inside the session before the work starts, because a process that is already running cannot be moved into tmux afterwards.

What is working from a phone actually like?

A phone fits one decision at a time, which is what an agent cycle is made of anyway. It proposes a plan, and you take it or send one sentence back. A two-line correction such as "leave the serializer alone, the export job uses it" is enough, and then the phone goes away.

The on-screen keyboard is the first real cost. Backticks, pipes, quotes, backslashes and the tilde all sit two layers deep, so ~/src/auth/session.ts takes longer than it should, and one wrong segment costs a round trip. Long prompts are harder to proofread than they look, which is why many people draft them in a notes app.

A diff is where a phone runs out of room. Forty changed lines across two files is three screens of scrolling on six inches, and a wrapped line hides whether a change sits at the end of a line or in the middle. Turn an iPad sideways and that same diff fits without wrapping.

One habit pays for itself: a second session for the noisy parts, so a test run cannot bury the agent's prompts.

tmux new -s tests -d    # -d starts it detached
tmux attach -t tests    # watch it, then detach

Can the agent answer its own permission prompts?

Claude Code does not run everything it thinks of. Before it runs a command, and depending on your configuration before it edits a file, it stops and asks: here is the command, go ahead? That stop is where the job waits, and if only you can answer it, the waiting becomes the bottleneck.

AI Permission Review answers those prompts and nothing else: it reads the prompt, then suggests or presses the key. A blacklist blocks dangerous commands and always hands a match to you. An allowlist passes commands you already trust, decided on the device. Anything matching neither goes to an AI judgement: allow, deny, or unsure, and the last two come back to you. The session's mode then decides whether it only suggests the key or presses it.

Distance does not move the responsibility off you. A command you approve on cellular runs on a machine that holds your .env, your keys, and a repository you do not own alone, and the judgement sees the screen, not the reasoning that got the agent there. Start in the mode that only suggests, allowlist the commands you approve every day, and read the screen before pressing anything when the signal and your attention are both poor. The blacklist exists because "approve everything" is a bad default: an rm -rf aimed at a home directory is no gentler because you said yes on a train platform.

claude: command not found, but it runs in Terminal

Same machine, same account, two different answers: claude starts in Terminal and prints claude: command not found over SSH. That reads like the remote setup is broken. It is the most common failure on the way in.

An install through npm, or under a node version nvm pins, writes its directory into a startup file that only an interactive login shell reads, and that is how the PATH gets the entry. A connection that runs one command, like ssh host claude, starts a non-interactive shell, and that shell never reads the file.

The fix that always works is to stop relying on the PATH. In the Terminal where it runs:

which claude
# /Users/you/.nvm/versions/node/v20.11.0/bin/claude

Use that absolute path, either as the agent command or typed into the session. It breaks when nvm changes the node version. The durable fix depends on your shell and your distribution, and the troubleshooting page covers it.

Can the agent work overnight?

A session on a machine that stays awake runs all night: hand it a refactor at eleven and read the result over coffee. Three things get in the way.

The machine has to stay awake. A Mac that idles into sleep takes its network interface with it, and Remote Login makes no difference because nothing is left to answer. System Settings → Battery on a laptop, Energy Saver on a desktop: lengthen or switch off idle sleep, and turn on "Wake for network access" if your Mac offers it.

A reboot takes the session with it. tmux does not restore sessions after a restart, and a software update reboots the machine without asking. Commit before you stop for the night, so the worst case costs an hour instead of the whole task.

A session can be waiting rather than dead. Attach and look. A fresh shell prompt means the process exited: finished, or died, and the lines above say which. A prompt asking you a question has waited six hours for one word, at no cost. From a lock screen both look the same, and only one needs you to act.

What belongs on the phone, what belongs at the desk

Three things have to hold: a machine that stays awake, a session with a name, and a private way in. If one is missing, the setup wizard asks three questions about your machine and hands back a checklist.