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, check how much of your rate limit the run burned, 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 — and land in the right project in one tap
• Approve, deny, and answer Claude from the inbox, lock screen, Dynamic Island, and Apple Watch
• Cut notification noise with permission modes, plan mode, and a tuned allowlist
• Compose prompts fast with voice, the Claude shortcut panel, and image paste
• Review diffs, browse the whole repo, and preview the dev server without leaving the app
• Watch Claude's rate-limit windows and context budget before they bite
• Keep long agent runs alive, and resume a closed conversation 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 gateway for diff and preview, and keeps a WebSocket open to Moshi so events reach your phone. Install it once per host — the pairing token comes from the Moshi app:

$brew tap rjyo/moshi
$brew trust rjyo/moshi
$brew install moshi-hook
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$brew services start moshi-hook

$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$moshi-hook serve

moshi-hook status should report the daemon running and the gateway connected. Moshi also shows a small status dot on each saved connection — green when the daemon is healthy, with a tap-through fix-it dialog when it's outdated, on the wrong port, or not running. Full options live in the hooks doc.

Use the moshi launcher for project sessions

The installer also exposes 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, and the launcher's details in Moshi CLI.

Part 2 — Connect from your phone

Add a connection in Moshi pointing at the host. The fastest path is Easy Pair: Moshi shows a QR flow that checks the host's prerequisites — Remote Login on, tmux and mosh-server reachable — and saves the connection for you. Setting up manually instead, two choices matter:

1. Auth: SSH key. Generate a keypair right 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.

Land in the right project, fast

On connect, Moshi's session picker shows more than running tmux sessions. The Recent tab lists the directories Claude Code (and Codex, Cursor, OpenCode) recently worked in — scanned from their history on the host — so "open a shell in that project I prompted from my desk this morning" is one tap, optionally straight into a tmux session at that path.

Once you're in, 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.

The inbox

Every approval request, question, tool run, and turn completion lands in Moshi's inbox as a card, grouped by project under Needs you / Working / Done — a live kanban of everything in flight. Each card carries the model name, the working directory, and a stamina ring showing how much of Claude's context window is left — so you can tell at a glance whether a run is cruising or near /compact territory. Turn on Settings → Agents → Keep Screen On and a phone propped next to your keyboard becomes a dedicated status board. See Agents & Usages.

Approvals render their real options — Approve and Deny buttons for permission prompts — and resolve over the daemon's bridge, so a tap on your phone unblocks the claude process on the host instantly. When Claude asks an open-ended question, the card offers Open terminal instead, which jumps you into the exact tmux window the agent is waiting in — not just the right host, the right pane.

The lock screen and Dynamic Island

You don't even need to open the app:

• Push notifications carry Approve/Deny action buttons. A long-press on the lock screen answers Claude in the background — the app never opens. See Notifications.
• Live Activity keeps the active turn on the lock screen and in the Dynamic Island — current status, model, and the context bar — so you can watch a long turn progress without unlocking. See Live Activity.

The watch

The same loop reaches your wrist. Moshi's Apple Watch app shows pending approvals with Approve/Deny buttons, the question text, and the agent's context bar — plus a complication that keeps your usage gauge on the watch face. Walking the dog is no longer a reason an agent sits blocked for an hour. See Apple Watch.

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, long-press, tap Approve, pocket the phone, and get a second notification when the turn finishes green.

Tune how often Claude asks

Claude Code's permission system is per-tool and very granular — which means you decide what becomes a lock-screen moment. Three controls are worth setting deliberately before a long remote run:

• ⇧Tab cycles permission modes. Default mode asks about anything not already allowed; auto-accept edits lets file changes through silently while commands still ask; plan mode has Claude propose before touching anything. The ⇧Tab button on Moshi's Claude panel sends the exact escape sequence Claude expects, so switching modes mid-session is one tap.
• /permissions builds your allowlist. Every rule you add — git diff, the test runner, your build command — is one less buzz on your wrist. The prompts that still arrive are then the ones that genuinely deserve a human.
• Plan mode is a phone superpower. Dictate the goal, let Claude draft the plan while you walk, and read it as prose — far more pleasant on a small screen than reviewing code. Approve the plan, switch modes, and let it run.

The goal isn't zero notifications; it's that every notification you do get is worth answering from a lock screen.

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 ships four speech engines — Parakeet (fast, on-device, the recommended default for English and many European languages), Apple SpeechAnalyzer (iOS 26+, zero setup), a local Whisper model (broadest language coverage), and a hosted Cloud engine (max accuracy, metered) — and two modes:

• Chat mode composes a prompt you can edit before sending — best for detailed instructions. Drafts persist until sent, and sent prompts are kept in History.
• Command mode types straight into the shell — best for short commands.

Hold the mic to push-to-talk, or tap to toggle. 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. Engine setup and language notes in Voice and dictation, and the workflow deep-dive in the voice guide.

To go a step further, Chat View renders the whole Claude Code or Codex session as a native chat — tool calls, plans, and approvals become cards, with voice and image paste built in.

The Claude shortcut panel

Moshi ships a shortcut panel tuned for Claude Code — its slash commands as one-tap buttons above the keyboard, reorderable and extensible with your own:

There are panels for tmux, Zellij, Herdr, Ctrl-chords, and the other agents too — plus custom multi-line text shortcuts with optional auto-Enter. See Keyboard and shortcuts.

The toolbar, D-pad, and hardware keys

For the characters phones hide — |, ~, -, arrows, Esc, Ctrl — Moshi adds a terminal toolbar and a draggable D-pad with configurable corner slots. Pair a hardware keyboard and you get the full chord set: hold ⌘ for the shortcut overlay, ⌘1–9 to jump sessions, ⌘V to paste — including images. Typing in Japanese, Korean, or Chinese? iOS IMEs work in the terminal and in chat mode; see CJK input.

Paste images and files directly

Hit a visual bug? Attach a screenshot, photo, clipboard image, or file straight into a prompt — Moshi copies it to the host over SCP and hands Claude a local file path, exactly like pressing Ctrl+V in Claude Code on a desktop. There's even a red-pen editor to circle the broken part before you send. Great for "here's the broken layout, fix it." See Image and file 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, all served by the host's own daemon — contents never leave your machine.

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, staged/unstaged/untracked sections, and rendering tuned for a phone screen. It's far easier than squinting at git diff output. See Diff viewer.

Browse the whole repo

The same viewer has a Browse tab that walks the entire file tree — at the working tree or any past commit — and opens any file as syntax-highlighted source. When Claude references a file it didn't touch, you're not boxed into the patch; you can go read it.

Browser preview

If the agent is running a dev server, Moshi lists it — with its git branch and dirty state — and opens it in an in-app browser forwarded over your own SSH session. No public tunnel, no port juggling; extra localhost ports the page requests get forwarded automatically. You can even stop a runaway dev server from the app. 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 and Clipboard.

Part 6 — Watch your usage

Claude Code meters usage in two windows — a 5-hour window and a 7-day window — and Moshi tracks both per account. The inbox's Usages tab shows each window with a pace marker ("5h usage pace normal · 7d usage pace faster"), the home screen condenses every agent into activity-style rings, and a watch complication keeps the gauge on your wrist. When you're deciding whether to kick off one more big refactor tonight, the answer is a glance away. See Agents & Usages.

Inside a session, the /usage button on the Claude shortcut panel asks Claude itself. The stamina ring on each inbox card covers the other budget — the context window — so you know when a /compact is due before Claude starts forgetting things.

Part 7 — 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

Resume a closed conversation

Inbox cards carry Claude's own session ID, copyable from the detail view. If a conversation ended — or you killed the window — start it back up exactly where it left off:

$claude --resume <session-id>
# or tap /resume on the Claude shortcut panel and pick from the list

Part 8 — 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, and they don't even have to be the same agent: the kanban from Part 3 holds Claude Code and Codex cards side by side. Moshi's session picker and per-multiplexer shortcut panels keep the sessions straight, and Herdr gives Claude Code agents their own workspace model. That's its own deep dive: see Running a fleet of agents.

Going further

• Completion pushes via CLAUDE.md. Moshi's notification settings include a ready-made prompt snippet to paste into your CLAUDE.md — Claude then pings your phone when a long task completes, even in setups where hooks can't run. See Notifications.
• Custom webhooks. The same push pipeline takes plain curl — wire CI failures or deploy completions into the same lock screen your approvals use.
• Make the terminal yours. Themes, fonts with CJK fallback, cursor styles, and per-gesture bindings (double-tap to send Esc, two-finger swipe for window switching) are all configurable. See Personalization and Gestures.

Troubleshooting

Approvals never reach my phone

Check moshi-hook status on the host — the gateway must be connected, not just the daemon running. The status dot on the connection row in Moshi tells you the same thing at a glance. 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 moshi-hook install 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.

Diff or preview buttons are missing

Both ride on the daemon's local gateway. If they've gone quiet, walk through Debugging the gateway — it's almost always an outdated daemon or a port mismatch.

Where to go next

• Moshi with Codex — approval modes, AGENTS.md, and session resume for OpenAI's agent
• 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
• Moshi with an always-on Mac — a host that's never asleep
• Hooks and Agents & Usages — the event pipeline in depth