Zellij（ターミナルマルチプレクサ）

概要

UZU プロジェクトでは、開発環境のターミナルマルチプレクサとして Zellij を採用しています。

複数サービスの一括起動（task mdms_jp:dev、task uzu_code:dev など）で使用しており、今後他のモジュールの開発環境でも Zellij への移行を進めていく方針です。

なぜ Zellij か

• レイアウトファイル（KDL）による宣言的なペイン構成 — シェルスクリプトで split-window を並べるより保守しやすい
• AI エージェントとの親和性 — zellij action list-panes や zellij action dump-screen で、セッション外からペインの出力を読み取れる。Claude Code などの AI がログを直接確認してデバッグに活用できる
• モード表示 UI — 画面下部に現在のモードと使えるキーが常に表示されるため、キーバインドを暗記する必要がない
• セッション復元 — プロセスが終了してもセッション情報が残り、再 attach で復元できる

インストール

brew install zellij

task doctor でインストール状況を確認できます。

使い方

開発環境の起動

task mdms_jp:dev          # マダミス.jp の全サービスを一括起動
task uzu_code:dev   # uzu_code の開発環境を起動

起動すると Zellij セッションが作成され、各サービスが個別のペインで立ち上がります。

基本操作

操作	キー
ペイン間移動	Alt + ←↑↓→ または Alt + h/j/k/l
デタッチ（セッションを残して抜ける）	Ctrl+o → d
セッション終了	Ctrl+q
ペイン操作モード	Ctrl+p（新規ペイン、ペイン閉じるなど）
タブ操作モード	Ctrl+t（新規タブ、タブ切り替えなど）
スクロールモード	Ctrl+s（ログを遡って確認）

TIP

デタッチしたセッションには task mdms_jp:dev を再実行するだけで再接続できます。

セッション管理

zellij list-sessions              # セッション一覧
zellij attach <session-name>      # セッションに再接続
zellij delete-session <name>      # dead セッションの削除
zellij delete-session <name> -f   # active セッションの強制削除

AI エージェントからのログ確認

Zellij の大きな利点として、セッション外からペインの出力をプログラム的に読み取れる点があります。

# ペイン一覧の取得
zellij --session mdms-jp-dev-0 action list-panes

# 特定ペインの出力を取得（スクロールバック含む）
zellij --session mdms-jp-dev-0 action dump-screen --pane-id terminal_1 --full

Claude Code などの AI エージェントがこれらのコマンドを使うことで、開発サーバーのログやエラーメッセージを直接確認し、デバッグを支援できます。

レイアウトファイル

各モジュールの開発環境レイアウトは taskfiles/ 配下に KDL 形式で定義されています。

• taskfiles/mdms_jp_dev.kdl — マダミス.jp 開発環境
• taskfiles/uzu_code_dev.kdl — uzu_code 開発環境

新しいモジュールの開発環境を追加する際は、これらを参考にレイアウトファイルを作成してください。