remote-claude-code

name	remote-claude-code
description	Run Claude Code on a remote host over SSH — a persistent expect-driven login session, headless claude -p with the stdin fix, the interactive TUI inside a remote tmux driven by send-keys/capture-pane (one keystroke at a time, capture-verified; relayed user messages go through verbatim), and multi-turn continuity via --session-id/--resume or stream-json; hosts and credentials are placeholders resolved at runtime from the user or the vault, never hardcoded.
short_description	Run Claude Code on remote hosts over SSH.
short_description_zh	在远程主机上通过 SSH 运行 Claude Code（持久会话 / headless / tmux 交互 / 多轮续接）。
preinstall	false
version	2
updated	2026-08-18T00:00:00.000Z

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).

3.4 Model and thinking level are two separate settings

A switch request that names a model plus a level word — "switch to fable5 max", "use opus high", "切换到 fable5 max" — means two settings: switch the model to the named one (Fable 5) and the thinking level to the named level (max). Never read the pair as one unknown model name, and never forward it as chat text for Claude Code to answer — it is session control you execute in the TUI (section 4).

The rule is about the shape of the request, not about those three examples. It fires on any message naming a model, a thinking level, or both, in any language — "换成 opus 高", "改成 max", "set thinking to high", "用 sonnet":

• Level words are max, high, medium/med, low, none/off and their Chinese equivalents (最高/最大, 高, 中/中等, 低, 关/不思考). A level word sitting next to a model name is always the thinking level — never part of the model's name.
• Model + level ("fable5 max") → set both, model first.
• Level only ("改成 max", "set thinking to high") → change the thinking level, leave the model alone.
• Model only ("switch to opus", "用 sonnet") → change the model, leave the level alone.
• Names arrive shortened, unspaced, or in the wrong case (fable5 → Fable 5, opus → the Opus entry). Match them against the rows the picker actually shows; if nothing matches, say what the picker offers and ask — never pick the nearest-looking row.

Use Claude Code's own controls: type /model (-l, then Enter as its own key) and walk the picker one keystroke at a time per §3.3; when the build exposes the thinking level as its own entry or toggle rather than a per-model variant, set it in a second step the same way. Finish with a capture that shows both the new model and the new thinking level before telling the user the switch is done — for a level-only or model-only request, that the requested one changed and the other did not.

4. Relaying a conversation — the user's words go through verbatim

Once the session is up and the user is talking to Claude Code through you, you are a message pipe — nothing more:

• Forward every user message to Claude Code verbatim: the exact wording, unchanged — no answering it yourself, no rephrasing or translating, no summarizing, no doing any part of the task locally. Even when you know the answer or the task looks trivial: the user is talking to Claude Code, not to you.
• Deliver the message (§3.2), wait out the turn (§3.1), then report what Claude Code said — faithfully, without your own analysis, edits, or additions. Read the reply with scrollback (capture-pane -p -S -200), not | tail -30: a long answer runs off the visible pane and a tail hands the user a fragment presented as the whole reply.
• Questions travel back, not to you. When Claude Code asks something — a permission prompt, a clarifying question, a plan to approve — carry it to the user with its options and send the answer they give (§3.3). You never answer on their behalf; that is their conversation.
• A message that arrives mid-turn waits. If the footer still shows esc to interrupt, don't type into the running turn: hold the message, wait the turn out (§3.1), deliver it then, and tell the user it is queued behind the current run. If they clearly want to stop or redirect now ("stop", "停", "别做了"), send Escape as its own key, capture to confirm the working footer is gone, then deliver. Escape twice in a row is not a stronger interrupt — it opens Claude Code's rewind-to-an-earlier-message UI, so send one and check.
• The only requests you act on yourself are session control: model / thinking-level switches (§3.4), interrupting a stuck turn (Escape), attaching, detaching, or closing the session, and connection repair. Execute those against the TUI; everything else goes into the conversation verbatim.
• Split by subject, not by phrasing. Questions about the session — is it still running, what's on the screen, is the connection alive, did the turn finish — you answer yourself from a capture. Anything about the work goes through unchanged, including questions you could answer. A message that does both ("is it still going? when it's done have it add the tests too") goes to Claude Code in full, and you answer the session half locally.
• When in doubt whether a message is task or control, relay it verbatim — a mis-relayed control request is easy to recover; work silently done in Claude Code's place is not.

5. Continuous (multi-turn) conversation

Three verified ways to keep context across calls:

a) Same session across headless invocations (simplest):

SID=$(uuidgen)
claude -p "Remember: my name is Alex." --session-id "$SID" < /dev/null
claude -p "What is my name?" --resume "$SID" < /dev/null   # answers: Alex

b) stream-json real-time protocol (programmatic):

echo '{"type":"user","message":{"role":"user","content":"Hello"}}' \
  | claude -p --verbose --input-format stream-json --output-format stream-json

Returns system/init (carrying the session_id), assistant, and result events; reuse the session_id to continue. --output-format stream-json requires --verbose.

c) The interactive tmux session (section 3) — the true REPL-style continuous conversation.

6. Troubleshooting

Symptom	Cause / fix
claude -p runs forever, no output, no TCP connections	stdin pipe never closes → add < /dev/null
TUI renders once then ignores keys; Enter shows up literally	pipe input treated as a paste → drive it with tmux send-keys
Trust dialog on every launch	hasTrustDialogAccepted unset for that project dir → set it to true (back up ~/.claude.json first)
TUI garbled / no colors	TERM=dumb → set xterm-256color at expect spawn or tmux launch
expect stuck producing no output	a prompt regex never matched → replace it with sleep + fixed sends
Connection timed out during banner exchange	busy server / transient → wait a few seconds and retry; keep one persistent session instead of hammering new ones
New SSH connections crawl while old ones work	connection pressure → route commands through the persistent session
Input line shows text you didn't type	a Claude Code suggestion, common right after a turn ends — not pending user input (see §3.2) → don't submit or edit it; send-keys -l "<message>" then Enter
Menu key acts on the wrong item (Up and s sent together)	keys batched faster than the TUI processes them → one key per send-keys call, capture-pane between keys (§3.3)
User asks for "fable5 max" / "opus high" / "改成 max"	model and/or thinking level — session control in the TUI (§3.4), not one unknown model, not a chat message to relay
Relayed message arrived split in two, or lost its last character	send-keys -l delivered an embedded newline as Return, or tmux ate a trailing ; → deliver anything non-trivial with load-buffer + paste-buffer -d -p (§3.2)
capture-pane fails: can't find pane / no server running	the tmux session or server is gone → confirm with tmux has-session -t <sess>, tell the user, rebuild with ; never keep relaying into a fresh, context-less session (§3)

7. Verification checklist

• Persistent session: the probe returns whoami/hostname/pwd, and the prompt comes back after each command.
• Headless: claude -p "..." < /dev/null prints the answer and exits.
• Interactive: capture-pane shows your message on the input line, then the response, then the prompt again.
• Relay: what reached Claude Code's input line is word-for-word what the user sent — nothing merged in from a suggestion, no line split off, no character dropped — and the reply you report back is Claude Code's, read with scrollback so it isn't a truncated tail.
• Decisions: every permission prompt and question Claude Code raised was answered by the user, not by you.
• Menus: every keystroke was its own send-keys call, and a capture confirmed the expected state before the next key.
• Switches: after a model and/or thinking-level request, one final capture shows the requested value(s) changed and the untouched one unchanged.
• Continuity: a follow-up that requires memory answers correctly (or the remote ~/.claude/projects/**/*.jsonl shows the user entry).
• Sanitization: no real host, user, or password appears in temp scripts left on disk or in your final answer — real values only ever come from the user or the vault at runtime.