Remote Claude Code

Remote Claude Code

Drive Claude Code on a remote Linux host over SSH. Three modes, in increasing interactivity:

1. Persistent SSH session — one long-lived expect-driven connection you keep feeding commands across turns.
2. Headless (claude -p) — one-shot or scripted calls, with the stdin fix that naive invocations need.
3. Interactive TUI — the real Claude Code UI inside a remote tmux session, driven with tmux send-keys / tmux capture-pane. tmux is the way to do interactive use.

Reach for this skill when the user wants to run or drive Claude Code on a server, keep an SSH connection open across turns, or hold a continuous conversation with Claude Code on a remote box. In a relayed conversation you are a pure message pipe — the user's words go to Claude Code verbatim (section 4).

Before you start

If the user's message only invokes this skill without a concrete task, ask what they want — at minimum the remote host, the SSH user, and what Claude Code should do there.

Credential rules — non-negotiable:

• This document contains no real credentials: <ssh-user>, <remote-host>, <target-user>, <sess> are placeholders you substitute at runtime from what the user provides or from this agent's key vault (suggested keys: REMOTE_SSH_HOST, REMOTE_SSH_USER, REMOTE_SSH_PASSWORD). Vault values reach your shell environment on the next task — check with [ -n "$REMOTE_SSH_PASSWORD" ] && echo ok || echo missing, and if missing ask the user to add the keys to the key vault (gear icon on the agent card → settings → key vault tab) or to provide the values in chat.
• Never hardcode a password into scripts left on disk, deliverables, or your final answer. Have expect read it from the environment ($env(...)); if the user pasted it in chat, export it only into the running process's environment, scrub it from logs and replies, and delete any temp file that embeds it as soon as the session is done.
• Prefer SSH keys when they are already set up — then no password tooling is needed at all.
• Back up remote config before modifying it, and never copy remote credential stores (~/.claude/.credentials.json, OAuth fields of ~/.claude.json, private keys) anywhere.

1. Persistent SSH session (expect)

One long-lived connection with password auto-login and an optional user switch, held open by interact. expect ships with macOS and is a one-command install on Linux; sshpass is usually absent, so expect is the password-interactive tool of choice.

The full expect template plus its operating notes live in reference/persistent-session.md — read that file when setting up this mode. In short: write the template to your scratchpad, fill the placeholders at runtime (the password comes from $env(REMOTE_SSH_PASSWORD), never hardcoded), start it with exec_command, and drive the held-open connection through its process_id with input_command. Reuse this one session for most remote commands rather than opening a new connection each time.

2. Headless Claude Code (claude -p) — the stdin gotcha

claude -p "<prompt>" hangs forever when its stdin is an open pipe that never closes — which is exactly what agent harnesses and the expect session above provide. The process idles with no output and no network connections. Fix: redirect stdin from /dev/null:

claude -p "Reply with exactly: all good" < /dev/null

Same for --resume, --session-id, --output-format stream-json, and the rest. Exception: when input is meant to come from stdin (--input-format stream-json), feed it through a pipe that closes (echo '<json>' | claude ...) and do not add < /dev/null — that would override the pipe.

Symptom checklist: process running + no output + no TCP connections → stdin starvation; add < /dev/null.

3. Interactive TUI — tmux is the way

Launching claude interactively inside the expect/pipe session renders the welcome screen, but pipe input is treated as a paste: text lands in the input box and Enter (\r) is inserted literally, so the message is never submitted (the remote transcript ~/.claude/projects/<dir>/*.jsonl gains no user entry). Run Claude Code inside a remote tmux session instead and drive it with tmux send-keys, which delivers discrete keypresses:

# start detached, then read the screen
TERM=xterm-256color tmux new-session -d -s <sess> "claude"
sleep 8
tmux capture-pane -t <sess> -p | tail -25

# converse: type the message, confirm it landed, submit — text and Enter as separate calls (§3.3)
tmux send-keys -t <sess> -l "Introduce yourself in one sentence"
tmux capture-pane -t <sess> -p | tail -5     # exactly your message on the input line?
tmux send-keys -t <sess> Enter
sleep 20
tmux capture-pane -t <sess> -p -S -200       # scrollback: a long reply overflows the visible pane

• Workspace trust dialog: it shows on the first launch in each project directory (-p mode skips it; --dangerously-skip-permissions does not). Answer it once via tmux send-keys -t <sess> Enter and capture to confirm it closed, or pre-accept it by setting hasTrustDialogAccepted: true for that project path in the remote ~/.claude.json — back the file up first (cp ~/.claude.json ~/.claude.json.bak-$(date +%s)) and rewrite it with a JSON-aware tool (python), not sed.
• Tool-permission prompts, and any other question Claude Code puts to the user (clarifying questions, plan approvals): the decision is the user's, not yours. Report the prompt and its options, wait for the user's answer, then send that key (one key, capture-verified, §3.3). Never approve a tool call on the user's behalf — an approved command runs on their host. --dangerously-skip-permissions is the one standing approval you may act on, and only when the user explicitly asked for unattended runs on that host.
• TERM=xterm-256color must be visible to the tmux server (prefix the tmux new-session call that starts it), or the TUI renders garbled and colorless.
• Continuity is real: within one tmux session, follow-ups remember earlier turns ("what was my first question?" gets the right answer).
• The user can join from their own terminal at any time: ssh <ssh-user>@<remote-host> → su - <target-user> → tmux attach -t <sess>.
• The session can die under you (host rebooted, tmux kill-server, someone closed it). A capture-pane that exits non-zero with can't find pane: <sess> or no server running on ... means exactly that — not a slow TUI, so don't retry keys into it. Confirm with tmux has-session -t <sess> (exit 0 alive, 1 gone), tell the user the session is gone, and rebuild it with claude --continue in the same working directory to pick the conversation back up. Never start a bare claude and keep relaying as if the earlier context were still there.

3.1 Waiting out a long turn — don't hold SSH open

A Claude Code turn can run for ten-plus minutes. Instead of keeping an SSH connection open to poll, place a detached watcher on the remote (setsid nohup, so it outlives the launching SSH session): it polls tmux capture-pane every 10s, and once the turn has been idle for 3 consecutive checks — the footer no longer shows esc to interrupt — it writes the final screen plus a DONE marker (or TIMEOUT past a cap). A blocking SSH loop then waits for the marker and returns the final screen, so the tool call effectively hangs until the turn is done. The full watcher script and the wait loop are in reference/completion-watcher.md — read it when you need this.

3.2 Delivering a message — and why input-line text may be a suggestion

When an idle Claude Code TUI shows text on the input line (after ❯) — above all right after a turn finishes — that is usually a Claude-generated suggested next message, not text the user typed and left pending, and a capture-pane dump cannot reliably tell the two apart. So never treat post-run input-line text as pending user input: don't submit it, don't report it to the user as their unsent draft, and don't try to clear or edit it. tmux send-keys only ever adds new text — it does not edit or "complete" that suggestion, and Enter submits what you sent, not the suggestion. When the next message is due, just send it — new text makes the suggestion disappear on its own.

A single plain line goes through send-keys -l (literal mode, so punctuation and words like Enter aren't parsed as key names). Text and Enter are always separate calls, with a capture in between:

tmux send-keys -t <sess> -l "Your full message, punctuation and all"
tmux capture-pane -t <sess> -p | tail -5    # exactly your message on the input line?
tmux send-keys -t <sess> Enter

Anything else — multi-line, pasted, long, or punctuation-heavy — goes through the paste buffer, because send-keys -l corrupts exactly the messages a relay must not corrupt (both verified on tmux 3.3a):

• a newline inside the literal text is delivered as Return, so a two-line argument submits its first line on its own and leaves the second as a fresh draft — one user message becomes two Claude Code turns;
• a ; that ends the argument is swallowed by tmux's own command-sequence parser: -l "ends with semi;" arrives as ends with semi. Characters vanish and nothing reports an error.

Load the text from a quoted heredoc (so neither the shell nor tmux re-parses $, backticks, quotes or backslashes) and paste it as one block. This uses the paste behavior §3 warns about on purpose: a bracketed paste lands in the input box as a draft and does not submit, so the separate Enter keypress stays the thing that sends it.

tmux load-buffer - <<'MSG'
The user's message, exactly as written —
newlines, "quotes", $signs and semicolons; all intact.
MSG
tmux paste-buffer -d -p -t <sess>            # -p bracketed paste (stays a draft), -d drops the buffer after
tmux capture-pane -t <sess> -p | tail -8
tmux send-keys -t <sess> Enter

The landed check is exact, not approximate: the input line must show your message and nothing else. A large paste may collapse to a [Pasted text #N +K lines] placeholder instead of the text — that still counts as landed; check the line count, not the words. Two failures to watch for, both before you press Enter:

• Merged — your text sits next to something else on the line. Don't submit: clear the line (tmux send-keys -t <sess> C-u), send again, and if it still merges, tell the user rather than submitting a message they didn't write.
• Already submitted — the turn started on its own, without your Enter. That pane isn't honoring bracketed paste, so the message went in split across lines. Say so, and deliver the rest one -l line at a time rather than pasting again.

Once the input line is right, send Enter, then capture-pane again to confirm the turn started.

3.3 One keystroke at a time — capture between keys

The TUI processes keys asynchronously, so a batched sequence races it: tmux send-keys -t <sess> Up s delivers s before the menu has processed Up, and s acts on the previous selection. Two back-to-back send-keys calls with no check in between race the same way.

In every menu, picker, or dialog (/model, permission prompts, trust dialog), send one key per send-keys call and verify between keys: send → capture-pane → confirm the expected change (highlight moved, dialog opened or closed, value updated) → only then send the next key.

Know where you are going before you start: capture the picker once, read which row is highlighted now and which row you want, count the moves, and step that many times — never press Up and hope.

tmux send-keys -t <sess> Up
tmux capture-pane -t <sess> -p | tail -15   # highlight moved to the intended entry?
tmux send-keys -t <sess> Enter
tmux capture-pane -t <sess> -p | tail -15   # menu closed, new value shown?

If the capture doesn't show the change yet, wait a second and capture again — never fire the next key on faith. Re-capture up to three times (a few seconds in total), then act on what the screen actually shows instead of sending more keys blindly:

• Nothing changed — the key was swallowed: re-send that same key once, and verify again.
• The wrong thing changed — highlight moved the other way, a different dialog opened, a value flipped that you didn't touch: correct it with the opposite key (Down for a stray Up, Escape for a dialog you didn't want) and verify again. Never "fix" a wrong state by pressing on toward the goal.
• Still not where you want it after two corrections — stop. Show the user the captured screen and ask. A menu whose state you can't read is not something to improvise more keystrokes into: a wrong key in /model changes their model, and a wrong key in a permission prompt runs a command on their host.

Message text is the one exception to one-key-at-a-time: send the whole message in a single call (-l for one plain line, load-buffer/paste-buffer otherwise), confirm it sits on the input line, then Enter as its own keypress (§3.2).