リモートサーバーで Claude Code をきちんと使う — ローカルクローンを捨て、tmux とスクリーンショット自動転送まで

Docker で立ち上げた Magento が Ubuntu サーバー上にある。作業するときは VS Code の Remote-SSH でサーバーに入り、モジュールフォルダのなかで Claude Code を走らせる。このワークフローを磨くなかで悩んだことと、その結論をまとめておく。同じように「リモートサーバー + AI コーディングエージェント」で働いている人の役に立ちそうだ。

ローカルにクローンして作業すればいいのでは?

最初に浮かんだ考えがこれだ。コードをローカルにクローンしておいて、そこで快適に作業してからサーバーへ送ればいいのでは? 結論は よくない。そして、その理由こそがこの記事の出発点になっている。

ひとつめ、コミットが「テストの前提条件」になってしまう。 ローカルを原本にして git で同期すると、一行直して確認するたびに commit → push → サーバーで pull をやることになる。コミットが「動くか見てみよう」の手段になった瞬間にループが遅くなり、git の履歴は wip、fix、もう一度 fix で汚れていく。コミットは「確認済み、保存」を意味するべきだ。

ふたつめ、そしてこれが決定的なのだが — ローカルには Magento がないので Claude Code が bin/magento を実行できない。 Claude Code の本当の力は、コードを直すことだけではなく、その場でコマンドを実行して結果を確認できる点にある。compile を回し、ログを見て、エラーを捕まえてまた直す、というループ。ローカルではエージェントが自分の作業を検証できない。明らかなダウングレードだ。

そこでメンタルモデルを2つに分けた。インナーループ(開発)は Magento が動いているサーバー上で直接編集 + 即テスト、コミットなし。 アウターループ(デプロイ)は動作確認のあと push → 本番で pull。 ここでの git push は「staging→prod のゲート」であって「ローカル→staging の同期」ではない。サーバーを直接編集すれば staging は常に最新なので、「ローカル→staging の自動同期」という問題そのものが消える。それはローカル編集を選んだときにだけ生まれる、自分で招いた問題だった。

「修正のたびに compile を打たないといけない?」— ほとんどの場合は不要

サーバー作業の面倒さとして感じていたこと。ふたを開けてみれば誤解だった。Magento でコマンドが必要な変更は一部だけだ。

.phtml テンプレート、ブロック/モデル内部の PHP ロジック、JS、Tailwind ソースは 保存してリロードすればすぐ反映される(developer モード + Docker の bind-mount なら、コンテナがホストのファイルをそのまま見ている)。.xml レイアウトや翻訳は cache:flush だけで済む。di:compile が本当に必要なのは、di.xml に新しい依存・プラグイン・preference を追加するときや、新しいモジュールを setup:upgrade するときだけだ。

つまり普段のロジック書きやテンプレートいじりはコマンド0個。修正のたびに compile を打つのは不要な習慣だった。テーマ作業のときは npm run watch(Tailwind の watch)を立ち上げておけば、CSS は保存するそばからビルドされる。full static deploy は本番デプロイのときだけ。

そして compile/flush が本当に必要な場面では、Claude Code に「直して、必要な Magento コマンドまで実行して結果を見て」と言えば、自分で判断して回し、エラーまで確認してくれる。手で打つ必要はない。これこそがサーバー上でエージェントを走らせる理由そのものだ。

VS Code 拡張機能が不便だった本当の理由

新しい会話を開くにはウィンドウ/パネルを行き来しないといけないし、Warp や Conductor のようなツールで使うより不便だった。だいぶ迷ったあとで原因に気づいた。不便さの原因は「サーバー作業」ではなく「VS Code 拡張機能を経由すること」だった。

Claude Code はもともとターミナルネイティブなツールだ。VS Code 拡張機能は付属物で、本体は CLI だ。Warp が快適なのはターミナルから直接立ち上げるからだ。だとすれば解決の方向は明確だ — 拡張機能を経由せず、サーバーのターミナルで Claude Code を複数、直接立ち上げればいい。

tmux: マルチセッション + SSH が切れても生きている

答えは tmux だった。SSH でサーバーに一度入って tmux を立ち上げれば、そのなかでペインを分割して、それぞれ Claude Code を走らせられる。新しいセッションごとに SSH を開き直す必要がない。

ssh server (一度)
└─ tmux
   ├─ ペイン1: ModuleA で claude
   ├─ ペイン2: ModuleB で claude
   └─ ペイン3: tail -f var/log/  (ログ)

本当の強みは別にある。tmux セッションは SSH ではなくサーバー自体に紐づいているので、インターネットが切れてもノートパソコンを閉じても死なない。 カフェで作業してノートを閉じ、家から再接続して tmux attach すれば、やっていた Claude Code の会話がそのまま続く。GUI ツールにはない、サーバーベースの作業ならではの強みだ。

それから隔離(git worktree)の話 — Conductor のようなツールがブランチ/worktree を作るのは、複数のエージェントが同じファイルを同時に踏むときの衝突を防ぐためだ。だが、モジュールごとにフォルダが分かれた独立した作業は worktree なしでも衝突しない。さらに Magento はコードを worktree で分離しても、それが動くインスタンス(DB・キャッシュ・compiled)はひとつなので、結局はそこがボトルネックになる。隔離が必要ない作業なら、素の tmux で十分だ。

画像の貼り付け問題、そして ss + cc

VS Code を捨てきれなかった理由のひとつがクリップボード画像の貼り付けだった。Magento の画面が崩れたところをキャプチャしてそのまま入れれば、Claude Code が見てくれる。純粋なターミナルでは、これがデフォルトでは効かない。

CleanShot の公開 URL を貼る方法もあるが、Magento の管理画面・注文・API キーの画面が公開インターネットに上がるのが気になった。そこでローカル同期方式に振った。スクリーンショット(ss)フォルダをサーバーへリアルタイムでミラーリングし、サーバー側には「最新のスクリーンショットを自動でつかむ」ラッパー関数を置く。ファイル名を自分が知る必要がないのがポイントだ。

# サーバー ~/.bashrc
SHOT_DIR="$HOME/ss"
cc() {
  local latest
  latest=$(ls -t "$SHOT_DIR"/*.png 2>/dev/null | head -1)
  if [ -n "$latest" ]; then
    echo "🖼  添付: $(basename "$latest")"
    claude "$@" "$latest"
  else
    claude "$@"
  fi
}

Mac で CleanShot の保存先を同期フォルダに設定し(Mutagen でサーバーの ~/ss へ一方向ミラーリング)、tmux で cc "このレイアウト、なんで崩れてる?" と打てば、さっき撮った画像が自動で入る。操作は「キャプチャ → cc」の2ステップだけ。トークンは転送方式(URL/ファイル)とは無関係で、画像の解像度が効いてくるので、領域キャプチャの習慣がそのままトークン節約になる。

tmux ベースのセッションマネージャーはすでに存在する

「隔離ベース(Conductor 系)ではなく、自分が欲しい tmux のマルチセッション管理ツールはないのか?」と探したら、あった。素の tmux は「どのセッションが終わったか」を見せてくれないが、その空白を埋めてくれるツールたちだ。

craftzdog/tmux-claude-session-manager はプロジェクトごとのセッションを立ち上げ、終了/作業中の状態をポップアップで見せてくれる(Claude Code の hooks で状態を tmux に書き込む)。NTM(Named Tmux Manager)は名前付きセッション・ブロードキャスト・衝突検知に加えて、リモートサーバーで動かすときに SSH が切れてもセッションが維持されるよう設計されている — リモート環境に特に合う。nielsgroen/claude-tmux は tmux のポップアップ TUI でセッションの切り替え・モニタリングを提供する。

順番はこう決めた。まずは素の tmux から始めて感覚をつかみ、セッションが増えて「何が動いていて何が終わったんだ?」がもどかしくなったら、そのときマネージャーを一枚かぶせる。

まとめ

リモートサーバーで Claude Code を使うのは不便なのではなく、通り道を間違えると不便になる。サーバー上で直接作業すること自体は維持しつつ(DB・Magento へのアクセス、エージェントの自己検証という大きな利点はそのまま)、通り道を VS Code 拡張機能からターミナル + tmux に変えれば、マルチセッションとセッションの永続性が手に入る。そこに ss 同期 + cc 関数で画像入力まで埋めれば、GUI ツールがうらやましくなることはない。教訓をひとつだけ残すなら — 隔離が必要ない作業に隔離ツールを使うな。その場合は tmux が正解だ。