wezterm

WezTerm — 大容量 RAM 向けエージェントスウォーム管理

基本原則： WezTerm mux は tmux に代わるものです。大容量 RAM（512GB 以上）を活用して、エージェントスウォームを実行します。マルチプレクサーを入れ子にしないでください。

---

簡易診断

# One-liner status
echo "Mux: $(ps aux | grep -c '[w]ezterm-mux') procs | $(wezterm cli list --format json 2>/dev/null | jq length) panes | RSS: $(ps -eo rss,args | grep '[w]ezterm-mux' | awk '{sum+=$1} END {printf "%.1fGB", sum/1024/1024}')"

# Is mux running?
ps aux | grep wezterm-mux | grep -v grep

# Memory usage
ps -eo pid,rss,args | grep wezterm-mux | awk '{printf "%.1fGB\n", $2/1024/1024}'

# Recent logs
tail -20 /run/user/$(id -u)/wezterm/wezterm-mux-server-log-*.txt

# Connection test
wezterm cli list --format json | jq length

# Socket status
ls -la /run/user/$(id -u)/wezterm/sock

---

エージェントスウォームの課題

20 以上の AI エージェント（Claude Code、Codex、Gemini CLI）を実行すると、各エージェントは継続的に出力し、何時間も動作し、サブプロセスを起動して、並列に動作します。このため、WezTerm のデフォルト設定では処理しきれなくなります。

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                          THE FAILURE CASCADE                                  ┃
┃                                                                               ┃
┃  1. Output buffer fills        →  parser falls behind                         ┃
┃  2. Coalesce delay accumulates →  lag builds up                               ┃
┃  3. Caches thrash              →  CPU spikes on render                        ┃
┃  4. Socket buffers fill        →  connection hangs                            ┃
┃  5. You restart mux            →  ALL SESSIONS DIE (use reptyr first!)        ┃
┃                                                                               ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

デフォルトの想定と実際の状況

WezTerm の想定	エージェントスウォームでの実際の状況
約 100 行/秒	ペイン全体で毎秒 1,000 行以上
スクロールバックには時々アクセス	スクロールバックが主要なデバッグツール
ペインは少数	20 以上のペインがすべてアクティブ
キャッシュヒットが一般的	コンテキストの切り替えが頻繁なためキャッシュミスが発生

---

パフォーマンスのチューニング（大容量 RAM）

正確なプロンプト — RAM に合わせて自動調整

# Auto-tune using linear interpolation (recommended)
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/misc_coding_agent_tips_and_scripts/main/wezterm-mux-tune.sh | bash

# Preview without applying
./wezterm-mux-tune.sh --dry-run

# Calculate for specific RAM
./wezterm-mux-tune.sh --ram 200

# Use exact fixed profile
./wezterm-mux-tune.sh --profile 512

# Restore from backup
./wezterm-mux-tune.sh --restore

正確なプロンプト — 512GB 手動プロファイル

return config の前に ~/.wezterm.lua に追加します。

-- 512GB HIGH-RAM PROFILE
config.scrollback_lines = 10000000
config.mux_output_parser_buffer_size = 16 * 1024 * 1024
config.mux_output_parser_coalesce_delay_ms = 1
config.ratelimit_mux_line_prefetches_per_second = 1000
config.shape_cache_size = 65536
config.line_state_cache_size = 65536
config.line_quad_cache_size = 65536
config.line_to_ele_shape_cache_size = 65536
config.glyph_cache_image_cache_size = 4096

設定の早見表

設定	デフォルト	512GB	目的
scrollback_lines	3,500	10M	ペインごとの履歴
mux_output_parser_buffer_size	128KB	16MB	PTY バッチバッファー
mux_output_parser_coalesce_delay_ms	3	1	解析レイテンシー
ratelimit_mux_line_prefetches_per_second	50	1000	スクロール速度
shape_cache_size	1,024	65,536	フォントキャッシュ
line_state_cache_size	1,024	65,536	行属性キャッシュ
line_quad_cache_size	1,024	65,536	GPU ジオメトリ
glyph_cache_image_cache_size	256	4,096	ラスタライズ済みグリフ

RAM 別プロファイル

RAM	scrollback	buffer	caches	prefetch	メモリ使用量
64GB	1M	2MB	8K	500	3-8 GB
128GB	2M	4MB	16K	750	5-15 GB
256GB	5M	8MB	32K	500	8-25 GB
512GB	10M	16MB	64K	1000	15-60 GB

適用後： 新しい設定を読み込むため、mux を再起動します。

---

緊急時のセッション復旧

シナリオ： mux が応答しないものの、エージェントはまだ動作しています。まだ mux を終了しないでください！

正確なプロンプト — reptyr による復旧ワークフロー

# 1. Connect via plain SSH (bypass broken mux)
ssh user@host

# 2. Setup
sudo apt-get install -y reptyr
sudo sysctl -w kernel.yama.ptrace_scope=0

# 3. Create rescue session
tmux new-session -d -s rescue -x 200 -y 50

# 4. Find agents
ps -eo pid,args | grep -E 'claude --dangerously|codex --dangerously' | grep -v grep

# 5. Migrate each agent
for pid in $(ps -eo pid,args | grep -E 'claude --dangerously|codex --dangerously' | grep -v grep | awk '{print $1}'); do
  tmux new-window -t rescue -n "agent-$pid"
  tmux send-keys -t "rescue:agent-$pid" "reptyr -T $pid" Enter
  sleep 0.5
done

# 6. Verify migrations
for win in $(tmux list-windows -t rescue -F "#{window_name}" | grep agent); do
  tmux capture-pane -t "rescue:$win" -p | grep -qE "bypass|Claude" && echo "✓ $win" || echo "✗ $win"
done

# 7. NOW safe to kill mux
pkill -9 -f wezterm-mux

# 8. Restore security
sudo sysctl -w kernel.yama.ptrace_scope=1

# 9. Restart mux
wezterm-mux-server --daemonize

# 10. Access rescued agents
tmux attach -t rescue  # Ctrl-b w to browse

reptyr の失敗パターン

エラー	原因	対処方法
"Operation not permitted"	ptrace がブロックされている	sudo sysctl -w kernel.yama.ptrace_scope=0
"shares process group"	プロセスに子プロセスがある	通常の reptyr ではなく reptyr -T を使用します
"Unable to attach"	追加の保護機能	移行できません。セッションは失われます

成功率： 50～70％。多くのサブプロセスを実行中のセッションより、古いセッションやアイドル状態のセッションのほうが移行しやすいです。

---

Mux サーバーの操作

起動／停止

# Start (daemonized)
wezterm-mux-server --daemonize

# Stop gracefully
pkill -f wezterm-mux-server

# Force stop (kills sessions!)
pkill -9 -f wezterm-mux-server

# Restart (loses sessions unless rescued first)
pkill -9 -f wezterm-mux; wezterm-mux-server --daemonize

# Restart via systemd (if configured)
systemctl --user restart wezterm-mux-server

停止したプロキシプロセスを終了する

安全に終了できます。mux セッションには影響しません。

pkill -f 'wezterm cli.*proxy'

Mux のパフォーマンスが時間とともに低下する理由

原因	症状	対処方法
バッファーのオーバーフロー	接続タイムアウト	mux_output_parser_buffer_size を増やします
キャッシュスラッシング	スクロール時の CPU 使用率が高い	キャッシュサイズを増やします
セッションの蓄積	メモリ使用量の増加	定期的に mux を再起動します
スクロールバックの蓄積	GB 単位の RAM 使用量	scrollback_lines を減らすか、再起動します

---

永続セッションのセットアップ

リモートサーバー（初回のみ）

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/wezterm-mux-server.service << 'EOF'
[Unit]
Description=WezTerm Mux Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/wezterm-mux-server --daemonize=false
Restart=on-failure
RestartSec=5
Environment=WEZTERM_LOG=warn

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now wezterm-mux-server
sudo loginctl enable-linger $USER

ローカル設定（SSH ドメイン）

config.ssh_domains = {
  {
    name = 'myserver',
    remote_address = '10.0.0.1',
    username = 'ubuntu',
    multiplexing = 'WezTerm',  -- Key setting
    assume_shell = 'Posix',
  },
}

---

CLI 早見表

タスク	コマンド
ペインを一覧表示	wezterm cli list
ペインを一覧表示（JSON）	wezterm cli list --format json
右に分割	wezterm cli split-pane --right
下に分割	wezterm cli split-pane --bottom
テキストを送信	wezterm cli send-text --pane-id N "cmd\n"
新しいタブ	wezterm cli spawn
ドメイン内に新しいタブ	wezterm cli spawn --domain-name SSH:host
mux に接続	wezterm connect unix
ズームの切り替え	wezterm cli zoom-pane --toggle

---

メンテナンスチェックリスト

• 毎週： mux のメモリ使用量を確認し、RSS が 50GB を超える場合は再起動を検討します
• 再起動前： アクティブなエージェントがあるか確認します（必要に応じて reptyr を使用します）
• 設定変更後： 新しい設定を適用するため、mux を再起動します
• バージョン不一致： クライアントとサーバーのバージョンは完全に一致している必要があります

# Check version match
wezterm --version                    # local
ssh host 'wezterm --version'         # remote

# Check mux memory
ps -eo rss,args | grep '[w]ezterm-mux' | awk '{printf "RSS: %.1fGB\n", $1/1024/1024}'

---

トラブルシューティング

症状	原因	対処方法
接続タイムアウト	バッファーオーバーフロー	mux_output_parser_buffer_size を増やします
スクロールの遅延	プリフェッチ率が低い	ratelimit_mux_line_prefetches_per_second を増やします
描画時の CPU 使用率が高い	キャッシュスラッシング	すべてのキャッシュサイズを増やします
履歴の切り詰め	スクロールバックが小さい	scrollback_lines を増やします
ログに「Broken pipe」と表示される	クライアントの切断	ネットワークの安定性を確認します
「Checking server version」で停止する	mux の過負荷	セッションを救出し、mux を再起動します
バージョン不一致エラー	クライアントとサーバーのバージョンが異なる	両方を同じバージョンに更新します

ログの場所

# Mux server log
/run/user/$(id -u)/wezterm/wezterm-mux-server-log-*.txt

# Socket path
/run/user/$(id -u)/wezterm/sock

---

参考資料

トピック	ファイル
CLI コマンドの全一覧	COMMANDS.md
永続セッションの詳細	PERSISTENT-SESSIONS.md
パフォーマンスチューニングの詳細	PERFORMANCE-TUNING.md