Safe Start and Reconnect

Two things cause the most confusion: accidentally starting Claude Code twice, and seeing stale output after reconnecting. This page covers how to avoid both.

Safe start

Before tapping Start, check the session status indicator:

• Green (Running): Claude Code is already active. Don't tap Start.
• Gray (Stopped): Claude Code is not running. Tap Start to launch it.

The app has built-in duplicate-start protection -- tapping Start while Claude is already running does nothing. But checking the indicator first avoids any confusion.

If you're unsure whether Claude is running

Open the session selector, re-select your session. The terminal view refreshes and shows the current state. If you see Claude Code's prompt, it's running. If you see a plain shell prompt, it's not.

Reconnecting

When you reopen the app after it was backgrounded or after a network interruption:

1. Automatic reconnect: The app reconnects to the server automatically. This usually takes 1-3 seconds.
2. Session restore: The terminal output from your tmux session is re-streamed to your phone.

If the terminal looks blank or stale

This can happen after long background periods. Fix:

1. Open the session selector (top-left).
2. Re-select your current session.
3. The terminal view refreshes.

If the session was deleted

If someone (or a server restart) removed the tmux session:

• The app shows an empty state.
• Create a new session and start fresh.

Long-running tasks

For tasks that take minutes or longer:

1. Don't keep the app open. iOS will eventually suspend the network connection.
2. Use notifications instead. Claude Code hook events trigger push notifications on your iPhone when a task completes.
3. When the notification arrives, open the app, reconnect, and review the output.

This is more reliable than trying to maintain a permanent foreground connection on iOS.

Daily routine

1. Open the app. It reconnects automatically.
2. Check the session status. If Claude Code is running, continue where you left off.
3. If it's stopped, tap Start.
4. Send your prompts. For long tasks, lock the phone and wait for notifications.
5. When done, you can leave the session running or tap Stop.