TJ Zhang

Claude Code on iPhone: Fixing Scrolling and Authentication

Basic guides for running Claude Code from your iPhone exist—SSH to your Mac via Termius or Blink, maybe add Mosh for connection resilience. This guide covers the basics well.

But two problems will frustrate you once you get the basics working:

  1. Scrolling doesn't work — swipe gestures show frozen snapshots, repeated fragments, jumps between states
  2. Authentication randomly breaks — you keep having to re-login even though credentials should persist

This guide explains why these happen and how to fix them.

The Solution: tmux (Started from GUI)

Both problems have the same fix: run Claude inside a tmux session that was started from a GUI terminal on your Mac.

Setup

Install tmux if you haven't:

brew install tmux

Create ~/.tmux.conf:

# Enable mouse - makes swipe-scroll work
set -g mouse on

# Large scrollback buffer
set -g history-limit 200000

# Invert scroll direction for iOS natural scrolling
# iOS sends "wheel up" when you swipe up (to see content below)
# tmux interprets this literally and scrolls up (to see content above)
# These bindings swap them
bind -T copy-mode WheelUpPane send -N3 -X scroll-down
bind -T copy-mode WheelDownPane send -N3 -X scroll-up
bind -T copy-mode-vi WheelUpPane send -N3 -X scroll-down
bind -T copy-mode-vi WheelDownPane send -N3 -X scroll-up

On your Mac (from Terminal.app, iTerm, or Ghostty—not over SSH), start the session:

tmux new-session -d -s claude

In Termius, set your startup command to attach:

tmux attach -t claude

Scrolling works, authentication persists.

If you see "no session: claude" in Termius, the tmux session wasn't started yet—run the tmux new-session command from a GUI terminal on your Mac first. You'll also need to do this after a reboot.

Why This Works

If you just want the fix, stop here. This section explains the underlying mechanics.

The Scrolling Problem

Claude Code is a TUI app that uses the terminal's alternate screen buffer—a separate drawing surface for interactive interfaces. When you're in alternate screen, the terminal's normal scrollback is suspended.

On your Mac, terminals like Ghostty and iTerm handle this gracefully. They capture alternate screen content into their own scrollback buffer, so scroll gestures work as expected.

Termius over SSH doesn't have this capability. Instead, it captures periodic snapshots of the alternate screen. When you swipe, you're flipping through frozen frames—not continuous scrollback.

tmux solves this by maintaining its own scrollback buffer. With mouse mode enabled, swipe gestures scroll through tmux's buffer. This works regardless of alternate screen mode.

The Authentication Problem

Claude Code stores credentials in macOS Keychain. Keychain requires a "Security Agent context" that's only established during GUI login. SSH is a separate authentication path—it gets you into the system, but doesn't create a GUI session. The Keychain silently refuses access.

The key insight: processes inherit their parent's security context. If tmux starts from a GUI terminal, it has Keychain access. When you SSH in and attach to that tmux session, commands run inside it still have the original GUI security context—even though you're accessing them via SSH.

With tmux started from GUI and the right config, Claude Code on your iPhone works exactly like it does on your Mac.