swain-stage

Stage

swain 用の tmux ワークスペースマネージャーです。ペインレイアウトを作成し、アニメーション付きの MOTD ステータスパネルを管理して、エージェントがビジュアルワークスペースを直接操作できるようにします。

前提条件： tmux セッション内で実行する必要があります（$TMUX が設定されていること）。サブコマンドを実行する前に、スクリプトが tmux の有無を確認します。詳しくは「エラー処理」を参照してください。

スクリプトの場所

Swain プロジェクトのスキルは、プロジェクトルートの skills/ にあります。このスキルでは、次を使用します。

• skills/swain-stage/scripts/swain-stage.sh — tmux のメインレイアウトおよびペインマネージャー
• skills/swain-stage/scripts/swain-motd.py — MOTD ステータスパネル（Textual TUI。uv run 経由で実行）
• skills/swain-stage/scripts/swain-motd.sh — 従来の bash MOTD（uv/Textual を利用できない場合のフォールバックとして保持）
• skills/swain-stage/references/layouts/ — レイアウトプリセット
• skills/swain-stage/references/yazi/ — fileBrowser が yazi に解決される場合に使用する、同梱の Yazi 設定

コマンド

レイアウトプリセット

名前を指定してレイアウトを適用します。利用可能なプリセットは skills/swain-stage/references/layouts/ にあります。

レイアウト	説明
focus	エージェントのペイン＋右上の MOTD＋右下のファイルブラウザー
review	エージェント＋エディター（変更したファイル）＋MOTD
browse	エージェント＋ファイルブラウザー＋MOTD

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout review
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout browse
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout focus

デフォルトのレイアウトは、swain.settings.json の stage.defaultLayout で設定されています（デフォルト：focus）。

ユーザーは swain.settings.json の stage.layouts.<name> でレイアウト定義を上書きできます。

個別のペインを開く

レイアウト全体を適用せずに、特定の種類のペインを開きます。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane editor file1.py file2.py   # editor with specific files
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser                      # file browser at repo root
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser /some/path           # file browser at specific path
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane motd                         # MOTD status panel
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane shell                        # plain shell

MOTD の管理

MOTD ペインには、次の情報を含む動的なステータスパネルが表示されます。

• プロジェクト名、ブランチ、変更状態
• エージェントの作業中に表示されるアニメーションスピナー（点字、ドット、またはバーのスタイル）
• 現在のエージェントのコンテキスト（実行中の作業）
• アクティブなエピックと進捗率（swain-status キャッシュから取得）
• アクティブな tk タスク
• 準備完了（実行可能）な成果物の数
• 最後のコミット情報
• 担当する GitHub イシューの数
• 変更したファイルの数

MOTD は、uv run 経由で起動される Textual TUI アプリ（swain-motd.py）です。利用可能な場合は .agents/status-cache.json（swain-status が書き込み）からプロジェクトデータを読み込み、キャッシュがない場合や古い場合（5 分超）は、直接 git/tk に問い合わせます。エージェントの状態（スピナー、コンテキスト）は、リアルタイムの応答性を保つため、常に .agents/stage-status.json から読み込みます。Textual は Unicode の幅を正しく処理し、角丸の適切な枠線表示を実現するほか、色のテーマ設定をサポートします。

状態ファイルの場所：

• .agents/status-cache.json — swain-status のキャッシュ（エピックの進捗、準備完了項目、タスクデータ）。swain-status.sh が書き込みます
• .agents/stage-status.json — エージェントのライブ状態（スピナーの動作、現在のコンテキスト）。stage-status-hook.sh が書き込みます

フックによるリアクティブなステータス更新： .claude/settings.json では、stage-status-hook.sh が Claude Code のフック（PostToolUse、Stop、SubagentStart、SubagentStop）として設定されています。このフックは .agents/stage-status.json を自動的に書き込み、手動で motd update を呼び出さなくても、MOTD のスピナーにエージェントの実際の動作を反映します。

MOTD を操作します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd start                        # start MOTD in a new pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd stop                         # kill the MOTD pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "reviewing auth module"  # update context
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "idle"                # mark as idle
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "done"                # mark as done/idle

ペインを閉じる

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close right     # close the right pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close bottom    # close the bottom pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close all       # reset to single pane

ステータス

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" status          # show current layout info

リセット

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" reset           # kill all panes except current

エージェント起動のペイン操作

エージェントは作業中に swain-stage を直接使用してください。推奨パターンは次のとおりです。

変更後 — レビューを開く

ファイルの変更が完了したら、ユーザーがレビューできるようにファイルを開きます。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "changes ready for review"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane editor file1.py file2.py

調査中 — ファイルブラウザーを開く

コードベースを調べるときに使用します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser src/components/

作業中にコンテキストを更新する

現在の作業内容が MOTD に反映されるようにします。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "analyzing test failures"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "writing migration script"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "done"

完了時にクリーンアップする

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close right
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "idle"

設定

swain.settings.json（プロジェクト）と~/.config/swain/settings.json（ユーザーによる上書き設定）から読み込みます。ユーザー設定が優先されます。

キー	型	デフォルト	説明
editor	string	auto	エディターコマンドです。autoは次の順に検出します：micro > helix > nano > vim
fileBrowser	string	auto	ファイルブラウザーコマンドです。autoは次の順に検出します：yazi > nnn > ranger > mc
stage.defaultLayout	string	focus	デフォルトで適用されるレイアウトです
stage.motd.refreshInterval	number	5	MOTDの更新間隔（秒単位、アイドル時）です
stage.motd.spinnerStyle	string	braille	スピナーのアニメーションです：braille、dots、bar
stage.layouts	object	{}	ユーザー定義のレイアウト上書き設定です（プリセットファイルと同じスキーマ）

エラー処理

• tmuxバイナリがインストールされていない場合、スクリプトは"tmux not found"で終了します。インストールを提案してください："tmux is not installed. Install it now? I can run \brew install tmux` for you."ユーザーが承諾した場合は、brew install tmux`を実行してから、元のサブコマンドを再実行してください。
• tmuxはインストールされているものの、tmuxセッション内ではない場合（$TMUXが未設定）、スクリプトは"tmux not active — swain-stage requires a tmux session. Start tmux first."で終了します。ユーザーに知らせ、インストールは提案しないでください（tmuxはすでにインストールされています）。
• エディターまたはファイルブラウザーがインストールされていない場合は、ユーザーに警告し、代替手段またはswain.settings.jsonでの上書き設定を提案してください。
• ファイルブラウザーがyaziと判定された場合、swain-stageはskills/swain-stage/references/yazi/にある同梱の設定を適用し、テキストファイルがシステムのデフォルトアプリで開き、ディレクトリの色が暗いターミナルでも読みやすくなるようにします。
• jqが使用できない場合は、設定を読み込めないことを警告し、ハードコードされたデフォルト値を使用してください。
• ペイン操作はベストエフォートで実行します。ペインを作成または検出できない場合は警告しますが、セッションは失敗させないでください。