takemo101 Pi Issue Runner
GitHub Issueを入力として、Git worktreeを作成し、ターミナルマルチプレクサ（tmux/Zellij）のセッション内で独立したpiインスタンスを起動します。
クイックリファレンス
# Issue実行（メインコマンド）
# デフォルトでpi終了後に自動クリーンアップ
scripts/run.sh <issue-number> [options]
Options:
-i, --issue <number> Issue番号（位置引数の代替）
-w, --workflow <name> ワークフロー名（省略時: workflows セクションがあれば auto、なければ default）
--list-workflows 利用可能なワークフロー一覧を表示
--no-attach バックグラウンドで起動
--no-cleanup 自動クリーンアップを無効化
--reattach 既存セッションにアタッチ
--force 強制再作成
-b, --branch <name> カスタムブランチ名
--base <branch> ベースブランチ
--skip-run run:/call: ステップをスキップ
--no-gates --skip-run のエイリアス（後方互換性）
--agent-args <args> エージェントに渡す追加の引数
--pi-args <args> --agent-args のエイリアス（後方互換性）
-l, --label <label> セッションラベル（識別用タグ）
--ignore-blockers 依存関係チェックをスキップして強制実行
--show-config 現在の設定を表示（デバッグ用）
--list-agents 利用可能なエージェントプリセット一覧を表示
--show-agent-config エージェント設定を表示（デバッグ用）
-v, --verbose 詳細ログを表示
--quiet エラーのみ表示
# バッチ実行（依存関係順）
scripts/run-batch.sh <issue>... [options]
scripts/run-batch.sh 42 43 44 --dry-run # 実行計画のみ表示
scripts/run-batch.sh 42 43 44 --sequential # 順次実行
# タスク提案
scripts/next.sh # 次に実行すべきIssueを提案
scripts/next.sh -n 3 # 次の3件を提案
scripts/next.sh -l feature # featureラベル付きから提案
scripts/next.sh --json # JSON形式で出力
scripts/next.sh -v # 詳細な判断理由を表示
# プロジェクト初期化
scripts/init.sh # プロジェクト初期化（.pi-runner.yaml等を作成）
scripts/init.sh --full # 完全セットアップ（agents/, workflows/ も作成）
scripts/init.sh --minimal # 最小セットアップ（.pi-runner.yaml のみ）
scripts/init.sh --force # 既存ファイルを上書き
scripts/generate-config.sh # AIでプロジェクトを解析し.pi-runner.yamlを生成
scripts/generate-config.sh --dry-run # 結果をプレビュー
scripts/generate-config.sh --no-ai # AI不使用で静的テンプレート生成
scripts/generate-config.sh --validate # 既存設定を検証
# コンテキスト管理
scripts/context.sh show <issue> # Issue固有のコンテキストを表示
scripts/context.sh show-project # プロジェクトコンテキストを表示
scripts/context.sh add <issue> <text> # Issue固有のコンテキストに追記
scripts/context.sh add-project <text> # プロジェクトコンテキストに追記
scripts/context.sh edit <issue> # エディタでIssue固有コンテキストを編集
scripts/context.sh list # コンテキストがあるIssue一覧
scripts/context.sh clean [--days N] # 古いコンテキストを削除
scripts/context.sh export <issue> # Markdown形式でエクスポート
scripts/context.sh remove <issue> # Issue固有のコンテキストを削除
# セッション管理
scripts/list.sh # セッション一覧
scripts/mux-all.sh -w # 全セッションをタイル表示
scripts/dashboard.sh # プロジェクトダッシュボード
scripts/dashboard.sh --compact # サマリーのみ表示
scripts/dashboard.sh --json # JSON出力
scripts/dashboard.sh --watch # 自動更新（5秒ごと）
scripts/attach.sh <session> # セッションにアタッチ
scripts/status.sh <session> # 状態確認
scripts/stop.sh <session> # セッション停止
scripts/sweep.sh # 全セッションのマーカーチェック・cleanup
scripts/sweep.sh --dry-run # 対象セッション表示のみ
scripts/sweep.sh --force # PRマージ確認をスキップ
scripts/sweep.sh --check-errors # ERRORマーカーもチェック
scripts/cleanup.sh <session> # 手動クリーンアップ
scripts/force-complete.sh <session> # セッション強制完了
scripts/force-complete.sh 42 --error # エラーとして完了
scripts/restart-watcher.sh <session> # Watcher再起動
scripts/restart-watcher.sh 42 # Issue番号でも指定可能
# メッセージ送信
scripts/nudge.sh <issue-number> # セッションに続行を促すメッセージを送信
scripts/nudge.sh 42 --message "続けてください"
# ワークフロー選択
# .pi-runner.yaml に workflows セクションがある場合、-w 省略時は auto（AI自動選択）
scripts/run.sh 42 # workflows あり → auto / なし → default
scripts/run.sh 42 -w frontend # 明示的にフロントエンド用ワークフローを指定
scripts/run.sh 42 -w auto # AIがIssue内容から自動選択（明示指定）
scripts/run.sh 42 --workflow ci-fix # CI修正ワークフロー
# 継続的改善
scripts/improve.sh # レビュー→Issue作成→実行→待機のループ
scripts/improve.sh --dry-run # レビューのみ（Issue作成しない）
scripts/improve.sh --review-only # 問題表示のみ
scripts/improve.sh --max-iterations 2 # 最大2回繰り返す
scripts/improve.sh --auto-continue # 自動継続（承認スキップ）
scripts/wait-for-sessions.sh 42 43 # 複数セッション完了待機
前提条件
- Bash 4.0以上 (macOSの場合:
brew install bash) gh(GitHub CLI、認証済み)tmuxまたはzellij(ターミナルマルチプレクサ)pijq(JSON処理)yq(オプション - YAML解析の精度向上。なくても動作します)
非同期実行について
重要: run.sh を実行すると、バックグラウンドで watch-session.sh が自動起動し、完了を監視します。
そのため、wait-for-sessions.sh を呼ぶ必要はありません。
# 推奨: --no-attach でバックグラウンド起動
scripts/run.sh 42 --no-attach
# → 即座に制御が返る
# → 完了時に自動で通知が届く
# 進捗確認が必要な場合
scripts/status.sh 42
scripts/list.sh
wait-for-sessions.sh は特殊なケース（複数セッションの同期待機が必要な場合など）にのみ使用してください。
自動クリーンアップ
タスク完了時またはエラー発生時にAIが特定のマーカーを出力すると、
watch-session.sh が検出して適切な処理を実行します。
マーカー形式
| マーカー | 説明 | 動作 |
|---|---|---|
###TASK_COMPLETE_<issue_number>### |
正常完了 | 自動クリーンアップ実行 |
###TASK_ERROR_<issue_number>### |
エラー発生 | 通知送信、手動対応待ち |
動作フロー
run.shがバックグラウンドでwatch-session.shを起動watch-session.shがセッションの出力を監視- マーカー（例:
###TASK_COMPLETE_42###または###TASK_ERROR_42###）を検出 - 完了マーカーの場合は自動的に
cleanup.shを実行、エラーマーカーの場合は通知を送信
自動クリーンアップの無効化
# 自動クリーンアップを無効化
scripts/run.sh 42 --no-cleanup
メッセージ送信
実行中のセッションにメッセージを送信して、続行を促すことができます。
# セッションにメッセージを送信（続行を促す）
scripts/nudge.sh <issue-number> [options]
scripts/nudge.sh 42 --message "続けてください"
| オプション | 説明 |
|---|---|
-m, --message TEXT |
送信するメッセージ（デフォルト: "続けてください"） |
-s, --session NAME |
セッション名を明示的に指定 |
ワークフロー選択ガイド
-w オプションでワークフローを指定できます。プロジェクトの .pi-runner.yaml に workflows セクションが定義されている場合、-w 省略時は自動的に auto（AI自動選択）になります。
auto モードの動作
auto モードでは2段階で処理されます：
- 事前選択:
pi --print+ 軽量モデル（haiku）でワークフロー名を高速に判定 - プロンプト生成: 選択されたワークフローの
agents/*.mdテンプレートが展開された通常のプロンプトを生成
AI呼び出しが失敗した場合はIssueタイトルのプレフィックス（feat: / fix: / docs: 等）によるルールベース判定にフォールバックします。
判断基準
| 状況 | 推奨する -w |
|---|---|
| Issue内容に応じてAIに任せたい | 省略（auto）または -w auto |
| CI失敗の修正 | -w ci-fix |
| typo・設定変更など小さな修正 | -w simple |
| 特定のワークフローを使いたい | -w <name>（例: -w frontend） |
利用可能なワークフロー確認
scripts/run.sh --list-workflows
詳細ドキュメント
詳しい使い方、設定、トラブルシューティングは README.md を参照してください。