Tutorial 3: Working From Your Phone

Goal: your iPhone gets a push when Claude needs input; tap it, attach, answer.

ccmux’s narrow layout fits a phone-width terminal — the full TUI collapses to a single-column view designed for small screens.

ccmux — phone

Setup (one-time)

ccmux moshi-setup

This installs moshi-hook, then runs moshi-hook host setup. A QR code appears in your terminal. Open the Moshi iOS app, tap Add Host → Scan QR, point your phone at the terminal. Done.

The wizard also wires Claude Code’s hook entries so notifications fire automatically.

How it works

After pairing:

• The Moshi app lists every tmux session on your Mac
• When Claude pauses (needs_input), your phone vibrates with a categorized push: approval_required or task_complete
• Tap the notification → Moshi picker → attach → answer → swipe away

BEL fallback (non-Moshi)

A terminal client may support local notifications for terminal bells. Availability depends on the client, its settings, and whether the connection remains active. This is separate from Moshi’s native push notifications.

Suppress duplicate notifications

By default the laptop bell rings even when Moshi is paired (complementary, not duplicate). To mute the bell when Moshi is reporting:

# ~/.config/ccmux/config.toml
[notifications]
moshi_suppresses_bell = true

Headless / scripted setup

ccmux moshi-setup --token <token>

Bypasses the QR flow — useful for remote machines without a display.

Build your own mobile client

ccmuxd exposes an HTTP API — list sessions, attach to a live terminal (a WebSocket-bridged PTY), send keys, stream events, read notes and usage, plus a pairing + push (APNs/FCM) flow. The Moshi app is the mobile path today; the same API is open for any client to integrate. See the HTTP API reference.

Spotted an error or something out of date? Edit this page on GitHub.