Moshi with Claude Code

Claude Code is happiest on a real machine — your Mac, a Linux box, a VPS, a homelab. The problem is that you are not always at that machine. Moshi closes the gap: it puts a real terminal into that host on your phone, and surfaces the moments that need you — an approval, a question, a finished turn — as taps on your lock screen.

This guide is the full loop. By the end you'll start Claude Code from a coffee shop, answer its permission prompts from the notification shade, dictate a follow-up while walking, review the diff it produced, and let it keep grinding through a test suite while your phone is in your pocket.

What you'll learn

• Prepare a host so Claude Code survives disconnects and reports back to your phone
• Connect over a transport that tolerates cell networks and sleep
• Approve, deny, and answer Claude from the inbox, Live Activity, and lock screen
• Compose prompts fast on a phone with voice, the toolbar, and image paste
• Review what Claude changed with the diff viewer and browser preview
• Keep long agent runs alive and pick them back up cleanly

Before you start

You'll want three things on the host. Each one unlocks a different part of the loop, and you can add them incrementally.

The bare minimum is SSH plus claude. Everything below layers on top of that.

Part 1 — Prepare the host

Install the moshi-hook daemon

moshi-hook is a small Go daemon that installs Claude Code's hooks, serves a local bridge, and keeps a WebSocket open to Moshi so events reach your phone. Install it once per host:

# installs the daemon, the moshi launcher, and agent hooks
$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook status

moshi-hook status should report the daemon running and the gateway connected. If it isn't, start it with moshi-hook serve (or let your service manager keep it alive). Full options live in the hooks doc.

Use the moshi launcher for project sessions

The installer drops a short moshi command that resolves a directory, names a tmux session after it, and attaches — so every project gets a stable, named workspace:

$cd ~/projects/app
$moshi .
# equivalent to: tmux new-session -A -s app -c ~/projects/app

Because it execs into tmux, no wrapper process lingers — from the shell's view you simply started tmux. That durable session is what lets Claude keep working after your phone locks. The full rationale and window strategy is in the tmux guide.

Part 2 — Connect from your phone

Add a connection in Moshi pointing at the host. Two choices matter:

1. Auth: SSH key. Generate a key in Moshi (or import one) and add the public half to the host's ~/.ssh/authorized_keys. Keys beat passwords for an app you'll reconnect from dozens of times a day. See Connections.
2. Transport: mosh. With mosh installed on the host, Moshi prefers it and falls back to SSH automatically. Mosh is what makes a session shrug off going through a tunnel, losing signal, or the phone sleeping for an hour.

Once connected, attach to the project session and start the agent:

$moshi ~/projects/app
$claude

Part 3 — Approvals without staring at the screen

This is the part that changes how remote agent work feels. With moshi-hook running, Claude Code's permission prompts and turn events leave the terminal and come to you:

• Inbox. Every approval request, tool run, and turn completion lands in Moshi's inbox as a card. Tap Allow, Deny, or open the session to read context first. See Agent events.
• Live Activity. On iOS, the active turn shows on the lock screen and Dynamic Island — you can watch a long turn progress without unlocking. See Live Activity.
• Push notifications. When Claude needs you or finishes, you get a notification even with the app closed. Enable them under Settings. See Notifications.

A typical flow: you kick off "refactor the auth module and run the tests," lock your phone, and a minute later get a notification — Claude wants to run rm on a generated file. You read it on the lock screen, tap Allow, pocket the phone, and get a second notification when the turn finishes green.

Part 4 — Prompting fast on a phone

A phone keyboard should never be the reason you don't kick something off. Moshi gives you several faster paths.

Voice dictation

Talk instead of type. Moshi supports Apple's on-device SpeechAnalyzer, a local Whisper model, or a hosted cloud engine, and offers two modes:

• Chat mode composes a prompt you can edit before sending — best for detailed instructions.
• Command mode types straight into the shell — best for short commands.

Dictating "write a migration that adds a nullable deleted_at to users, then show me the diff" while walking is the single biggest unlock for impulse-driven agent work. Details and engine setup in Voice and dictation.

The keyboard toolbar and shortcuts

For the characters phones hide — |, ~, -, arrows, Esc, Ctrl — Moshi adds a terminal toolbar, a D-pad, and customizable shortcuts above the keyboard, plus full hardware-keyboard support if you pair one. See Keyboard.

Paste images directly

Hit a visual bug? Paste a screenshot or photo straight into a prompt. Moshi uploads it and hands Claude a fetchable URL — no scp, no temp files on the host. Great for "here's the broken layout, fix it." See Image paste.

Part 5 — Reviewing what Claude did

Reading a diff in raw terminal scrollback on a phone is rough. Moshi has purpose-built review surfaces.

The diff viewer

When Claude edits files, open the change in Moshi's diff viewer for a proper side-by-side (or stacked) read with syntax highlighting, tuned for a phone screen. It's far easier than squinting at git diff output. See Diff viewer.

Browser preview

If the agent is running a dev server, Moshi can preview the running app in-app so you can see the change, not just read about it. See Browser preview.

Scrollback and copy

For everything else, Moshi's scrollback and copy-mode are built for touch — grab an error, a stack trace, or a command without fighting iOS text selection. See Scrolling.

Part 6 — Surviving long runs

Long test suites, big refactors, and multi-step plans are exactly when you want to walk away. The combination that makes that safe:

1. tmux keeps the claude process and its shell alive on the host regardless of your phone.
2. mosh lets Moshi drop and re-establish the connection silently as you move between networks.
3. moshi-hook notifies you the moment attention is actually needed, so "walk away" doesn't mean "miss the approval."

When you come back, reattach and you're exactly where you left off:

$tmux a -t app
# Claude is right where it was — mid-turn or waiting on you

Part 7 — When one agent isn't enough

Once this loop is second nature, you'll want several agents going at once — one per project or per task. Moshi's session picker, per-multiplexer shortcut panels, and the inbox keep them straight, and Herdr gives Claude Code agents their own workspace model. That's its own deep dive: see Running a fleet of agents.

Troubleshooting

Approvals never reach my phone

Check moshi-hook status on the host — the gateway must be connected, not just the daemon running. If the daemon is up but events don't arrive, confirm notifications are enabled in Moshi's Settings and that the host can reach the internet. Re-running the installer refreshes the Claude Code hooks if they drifted.

Claude dies when I lose signal

That's the no-tmux failure mode. Start the agent inside moshi <dir> (or any tmux session) and the process survives the disconnect; Moshi just re-attaches.

Claude works locally but Moshi can't find the session

Moshi detects multiplexers over a non-interactive SSH shell, which often skips your rc files. If tmux lives in /opt/homebrew/bin or /usr/local/bin, make sure that's on the non-interactive PATH. The tmux doc walks through this.

Where to go next

• Running a fleet of agents — scale from one agent to many
• Moshi with tmux — the durable workspace this guide leans on
• Hands-free with voice — dictation-first workflows
• Hooks and Agent events — the event pipeline in depth