Driving Claude Code from your phone

The first time you run Claude Code from your phone, you’ll wonder why nobody offered this five years ago. The mental shift is small but real: instead of being tethered to a laptop to use AI coding, you can fire off a debugging session from a coffee shop, the back of a meeting room, or a couch — and the agent runs on your real machine, with your real shell, your real environment, your real test suite.

This is what setting it up actually looks like. Total setup time, end-to-end, is about 90 seconds.

What you need before you start

• A laptop with Claude Code (or Codex / Gemini / Copilot CLI) installed and working at the terminal
• Python 3.7+ on the laptop (you almost certainly have it)
• The PromptBeat app on your phone, with an account created (iOS 16+ or Android 10+)

If you don’t have those, the setup guide covers them in detail. The rest of this post assumes you do.

Step 1: Install the local agent

The local agent is what gives Remote AI Chat its “real” quality — it spawns the AI tool inside a real PTY on your laptop, so you get the same colors, prompts, resizable terminal, and signal handling you’d see if you ran it yourself.

The simplest way to install is the same one-line command that sets up the permission hooks:

curl -sS https://promptbeat.online/public/promptbeat-installer.sh | bash

The installer detects which AI tools you have and asks if you want to enable Remote AI Chat. Say yes. It installs the local agent at ~/.promptbeat/agent.py, a config file at ~/.promptbeat/agent.json, and a launchd / systemd service so the agent starts when you log in.

Step 2: Pair your phone with this machine

Run:

python3 ~/.promptbeat/agent.py install

The terminal renders a QR code and starts long-polling. On your phone, open the PromptBeat app, tap the laptop icon in the top app bar, and scan. The app shows a confirmation dialog — if you’ve paired this machine before, it offers Replace existing / Keep both / Cancel. Pick one. The terminal flips to “Connected,” the QR disappears, the agent writes ~/.promptbeat/agent.json at 0600, and you’re done.

What just happened under the hood: an API key got minted server-side, tagged to your machine’s hostname. The plaintext key was passed once through the install pairing channel and immediately wiped from the server — only the SHA-256 hash is stored. Now your laptop and your phone are mutually authenticated to the same account.

Start the daemon (one-time):

# macOS
launchctl kickstart -k gui/$(id -u)/com.promptbeat.agent

# Linux
systemctl --user start promptbeat-agent

Now the agent is running quietly in the background, connected to the PromptBeat server over WebSocket, waiting for you to start a chat.

Step 3: Open a chat session

On your phone, open the PromptBeat app and tap AI Chat. You’ll see your laptop in the device list (it shows the hostname from when you paired it). Tap it.

The next screen asks for two things:

• The AI tool to spawn. Claude Code, Codex, Gemini, or Copilot CLI — whichever you have installed.
• The project directory. The agent runs find-style discovery for git repos under your home, but you can also type a path. The AI tool will cd there before running.

Tap Start session. The local agent spawns Claude Code inside a fresh PTY, with a few sane defaults: --allowedTools Read,Glob,Grep pre-approved (so the obvious-safe stuff doesn’t bother you), PROMPTBEAT_CHAT_SESSION set in the environment so the permission hooks know which session a tool call belongs to.

Step 4: Type a prompt

Now you’re in the chat detail screen. Type a prompt — or, more usefully, hit the mic button and dictate it. Send.

The user message goes to the local agent over WebSocket. The agent passes it to Claude Code via stdin. Claude Code thinks, starts streaming a response, and every chunk gets relayed back to your phone in real time. Your message bubble looks how you’d expect; the AI’s message renders streaming as it arrives, with bash blocks syntax-highlighted and diffs colorized.

Step 5: Approve tool calls inline

This is where Remote AI Chat gets interesting. When Claude Code decides it needs to run a tool call — say, grep -rn "authenticate" src/ — it fires the same permission hook that’s installed for non-chat sessions. The hook reads the PROMPTBEAT_CHAT_SESSION env var, includes it in the permission POST, and the server knows this approval belongs inside a chat thread.

On your phone, the chat momentarily pauses. An approval card appears inline in the message stream, between the AI’s last message and where the next one will land. The card shows the exact command. You can:

• Tap Allow — Face ID gates it, the card collapses to a green “Approved” badge, the chat resumes streaming.
• Tap Deny — same thing in red. Claude Code sees the deny, picks a different approach, the chat continues.
• Long-press Session — pick a pattern (exact, prefix, tool-wide), and matching tool calls auto-approve for the rest of this chat.

If your app is backgrounded when the prompt fires, you get a normal push notification. Tap it, approve, then the home screen shows a “Chat resumed — Open” snackbar to jump you back.

What this is good for

The honest answer: not replacing your laptop. Remote AI Chat is for the gaps. Three patterns I’ve actually used it for:

• Diagnosing a CI failure from a meeting. Claude Code runs the same tests against the same branch. I read the output, ask a follow-up, leave the meeting with a fix queued.
• Triaging a production incident on the way home. Pull logs, grep for the error, get a hypothesis. Don’t commit anything until I’m back at a real keyboard.
• Letting a long task run unattended. Kick off a refactor across 40 files; the agent runs it; I check in periodically; approvals come to my phone for anything substantive.

The thing that makes it not a gimmick is the inline-approval flow. The phone is the right surface for two-second approve/deny decisions in a way the laptop terminal is not, even when the laptop terminal is right in front of you.