zmx

zmx プロセス管理

セッションのルール

• セッションを作成する前に zmx list --short を確認します。重複するとポートの競合や分かりにくい出力が発生します
• git rev-parse --show-toplevel からセッション名を決めます。名前を固定すると、複数のエージェントインスタンスが同時に実行されたときに衝突します
• アタッチせずにコマンドを送るには zmx run を使います。zmx attach はエージェントのシェルをブロックし、応答しなくなる原因になります
• 複数のプロセスには、共通のプロジェクトプレフィックスを持つ別々のセッションを使います

1 つのプロジェクトにつき 1 つのセッションプレフィックスを使います。複数のプロセスには、プレフィックスを共有する複数のセッションを使います。

セッション名

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")

以降の例では、PROJECT が設定されていることを前提とします。セッション名は ${PROJECT}-<role> の形式です。

• myapp-server、myapp-tests、myapp-tilt

プロセスの起動

SESSION="${PROJECT}-server"

# Idempotent: skip if already running
if ! zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
  zmx run "$SESSION" 'npm run dev'
fi

複数のプロセスを起動する場合は、名前とコマンドのペアをループします。

for name_cmd in "server:npm run dev" "tests:npm run test:watch"; do
  name="${name_cmd%%:*}"
  cmd="${name_cmd#*:}"
  SESSION="${PROJECT}-${name}"
  if ! zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
    zmx run "$SESSION" "$cmd"
  fi
done

コマンドの送信

# Run a command in a session (creates session if needed)
zmx run "${PROJECT}-main" 'cat README.md'

# Pipe via stdin
echo "ls -lah" | zmx r "${PROJECT}-main"

出力の監視

zmx history "${PROJECT}-server"                              # full scrollback
zmx history "${PROJECT}-server" | tail -50                   # last 50 lines
zmx history "${PROJECT}-server" | rg -i "error|fail"         # check for errors
zmx history "${PROJECT}-server" | rg -i "listening|ready"    # check for ready

完了待ち

zmx wait "${PROJECT}-tests"                                  # block until done
zmx wait "${PROJECT}-build" "${PROJECT}-lint"                 # wait for multiple

ライフサイクル

zmx list                                                     # all sessions
zmx list --short                                             # names only
zmx kill "${PROJECT}-server"                                 # kill one session

# Kill all project sessions
zmx list --short 2>/dev/null | grep "^${PROJECT}-" | while read -r s; do
  zmx kill "$s"
done

分離

• 現在のプロジェクトプレフィックスに一致するセッションのみを終了します。他のエージェントインスタンスが独自のセッションを実行している可能性があります
• 終了操作の前に、必ずセッション名を確認します

zmx を使う場面

シナリオ	zmx を使いますか？
tilt up	はい、常に
開発サーバー（npm run dev、rails s）	はい
ファイルウォッチャー（npm run watch）	はい
テストウォッチャー（npm run test:watch）	はい
データベースサーバー	はい
1 回限りのビルド（npm run build）	いいえ
短時間のコマンド（10 秒未満）	いいえ
会話に標準出力を直接表示する必要がある場合	いいえ

準備完了の確認

for i in {1..30}; do
  if zmx history "${PROJECT}-server" 2>/dev/null | tail -20 | rg -q "listening|ready"; then
    echo "Server ready"
    break
  fi
  sleep 1
done