AIRPOCKET GITHUB
G2GUIDE · CLAUDE CODE

Claude Code on your iPhone

Airpocket puts the Claude Code sessions running on your Macs on your iPhone, and lets you answer them: read along, reply, pick an option, switch the model, stop a run. It is a web app on your Home Screen that talks to each Mac over your own Tailscale network, with nothing in between.

01
FROM THE PHONE

What you can do from the phone

  • See which session needs you. Every session on every paired Mac in one list, the ones waiting on you first, each marked by what it waits for: a permission, the answer to a question, or a look at a finished turn.
  • Read the conversation, not the raw terminal: your messages, Claude's replies and one short line per step, updated as it works.
  • Reply from the message box, with up to four photos if a screenshot says it better.
  • Answer a menu. When Claude asks before running a command, or offers numbered choices, they become buttons. A tap presses that key in the terminal the session runs in.
  • Change model and effort, from the models Claude Code itself offers on that Mac and the effort levels the model takes. Switch permission mode, or turn on plan mode.
  • Stop a run that heads the wrong way. Stop presses Esc in its terminal, after asking you first.
  • Session commands: compact, context, usage, resume, rewind and clear, and a keypad for single keys.
  • Open what it made: files the session wrote, edited or linked, as text, code, Markdown or images. PDFs and web pages open in a separate, locked-down view.
  • Start a new session in a project, on a Mac with Superset.
02
HOW IT KNOWS

Claude Code's own hooks

Claude Code runs hooks: commands it calls at fixed moments in a session. airpocket setup adds Airpocket's to ~/.claude/settings.json, or to the folder $CLAUDE_CONFIG_DIR names. It merges them in, keeps every setting and hook already there, and writes a timestamped backup of the file first.

Each hook tells a small service on the same Mac, over loopback, what has happened:

  • a session started, or ended;
  • you sent a prompt, so a turn is running;
  • the turn finished;
  • Claude is waiting: for a permission, for the answer to a question, or for you.

The hook is silent, gives up after a second and a half, and does nothing when the service isn't running, so it doesn't hold Claude up. The conversation itself the service reads from the transcript Claude Code already writes on the Mac.

airpocket uninstall takes Airpocket's hooks out again and leaves the rest of the file as it was.

03
NOT THERE YET?

Why a session appears only when you next prompt it

Claude Code re-reads its settings while it runs, so a session that was already open before setup picks up the hooks without a restart. But a hook runs only when something happens, and until that session does something, the service has never heard of it.

So a session from before setup appears on the phone the next time you prompt it. Sessions started after setup appear as they start.

NO RESTART NEEDED

Until then the phone counts them: a line under the list says how many Claude Code agents run on that Mac that haven't checked in yet. Setup prints the same when it finishes. Send each one a prompt and it appears.

04
WHERE IT RUNS

In the terminal you already use

Any terminal works: Terminal.app, iTerm2, Ghostty, Warp, a VS Code or Cursor pane. Start Claude through Airpocket and the phone can answer it:

$ airpocket run claude

Setup can also alias claude to that, so you type what you typed before. A session in tmux or Superset needs neither: the phone answers it as it is.

A session started the plain way still shows on the phone, read-only, with a line saying how to bring it in. Answering from any terminal explains why, and what run does.

05
LIMITS

What it can't do

  • It can't answer a session it can't reach. A Claude started the plain way, outside airpocket run, tmux or Superset, stays read-only until it is started again through one of them.
  • Controls wait their turn. A model change or any other command is refused while a turn runs, while a menu is open, or while unsent text sits in the prompt box, so it never lands in the middle of something.
  • Effort and model changes become your default. Claude Code saves /effort and /model as the default for new sessions, from the phone as from the keyboard. The phone says so when you change effort.
  • No tool output. The phone shows one short line per step, never a command's output or the contents of a file the agent read.
  • No file browser. Only files the session wrote, edited, cited or linked, inside its own folder, never one it only read.
  • A permission refused with Esc on the Mac stays "needs permission" on the phone until the next prompt, because Claude Code runs no hook for it.
  • A sleeping Mac is offline. The phone shows it as offline and hides its sessions until it wakes.
KNOW THIS BEFORE YOU PAIR

A paired phone can type anything into your agents, shell commands included: in Claude Code, a message that starts with ! runs as one, and the phone asks before sending it. A phone's token works until you revoke it on that Mac with airpocket revoke. Pair only phones you control.