tuicr

tuicr レビューワークフロー

デフォルトのエージェントインターフェースとして tuicr review を使用します。人間がコードをレビューする場所は TUI です。CLI は、エージェントがアクティブなセッションを見つけ、ユーザーのコメントを読み取り、適切な場合に限ってエージェントが作成したコメントを追加するために使用します。

基本ルール

まず、ユーザーがどのワークフローを求めているかを判断します。

1. エージェントが生成した変更をユーザー主導でレビューする

   • ユーザーはパッチを確認し、tuicr でコメントを作成したいと考えています。
   • あなたの役割はセッションを開くか見つけることです。その後、ユーザーがコメントの準備ができたと伝えたら、tuicr review comments でユーザーのコメントを取得します。ユーザーのレビューを待つよう明示的に指示された場合は、同じコマンドを定期的に実行し、新しいコメント ID を探します。
   • 独自のレビューコメントを追加したり、自分のパッチを先回りしてレビューしたり、ユーザーのコメントになりすましたりしないでください。

2. AI が生成したパッチをエージェントがレビューする

   • ユーザーはパッチを理解、批評、または要約することを求めています。
   • パッチを確認し、指摘事項を提案できます。
   • このワークフローと対象のセッションを確信を持って特定できる場合は、エージェントを識別する明示的な --username を指定して、tuicr review add で指摘事項を直接追加します。ワークフローまたはセッションが曖昧な場合は、先に確認してください。

ユーザーの意図が曖昧な場合は、どちらのワークフローを希望するか尋ねてください。

セッションに接続する

1. ユーザーの依頼、現在の作業ディレクトリ、または最近のファイル操作からリポジトリのディレクトリを特定します。曖昧な場合は確認してください。

2. 保存済みセッションを一覧表示します。

   tuicr review list --repo /path/to/repo   # checkout + its repo's PR sessions
   tuicr review list --repo owner/repo      # all sessions for a forge repo
   tuicr review list --all                  # every session across all repos
   

   --repo はセレクターです。チェックアウトのパスを指定すると、そのチェックアウトの origin リポジトリに対する PR セッションも表示されます。また、owner/repo のような forge の座標を指定すると、owner/repo が一致するローカルセッションと PR セッションが表示されます。各行には kind（local または pr）と、使用可能な slug が含まれます。リポジトリがわからない場合は --all を使用してください。

   終了コードが 0 で [] が返る場合、「リポジトリのルートではない」という意味でもあります。サブディレクトリでも同様の結果になります。何も開いていないと結論づける前に、ルートを渡してから --all を指定してください。

3. セッションを選択します。

   • CLI が関連するアクティブなセッションを 1 つだけ "active": true と明確に報告した場合は、そのセッションに接続します。
   • 複数のセッションがアクティブな場合、または正しいセッションが明確でない場合は、使用する slug をユーザーに確認してください。1 つのリポジトリで、worktree セッションと commit-range セッションが同時に存在することがあります。誤ったセッションに追加しても終了コードは 0 です。
   • ユーザーが slug またはセッション JSON のパスを指定した場合は、それを直接使用します。
   • PR レビューでは、一覧表示から PR の slug（例：gh:owner/repo/pr/N）を取得し、--session に渡します。slug に必要な情報がすべて含まれているため、--repo は不要です。
   • アクティブなセッションがない場合は、以下の説明に従ってセッションを開始するか、開始を待ちます。
   • アクティブセッションの検出が安定したプロトコルとして正式化されるまでは、"active": true は便宜上の目印として扱ってください。slug の解決に失敗した場合は、セッションで使用した slug またはリポジトリのパスをユーザーに確認してください。

エージェントが tmux、Zellij、または Herdr 内で実行されていなくても CLI は動作します。そのため、既存のアクティブなセッションに接続するだけの目的で、マルチプレクサーの使用を必須にしないでください。

セッションを開始する

ユーザーが対話型の tuicr ペインを必要としていて、アクティブなセッションがない場合：

環境	アクション
$CMUX_WORKSPACE_ID が設定されている	tuicr-wrapper-cmux.sh /path/to/repo -- <scope> を実行します
$TMUX が設定されている	tuicr-wrapper.sh /path/to/repo -- <scope> を実行します
$ZELLIJ が設定されている	tuicr-wrapper-zellij.sh /path/to/repo -- <scope> を実行します
$HERDR_ENV が 1	tuicr-wrapper-herdr.sh /path/to/repo -- <scope> を実行します
いずれも設定されていない	ユーザーに、リポジトリ内で tuicr を起動するまで待機していると伝え、準備ができたと言われたら tuicr review list でアタッチします

<scope> は、未コミットの作業ツリーの変更には -w、コミット範囲には -r <revset> を指定します。TUI でステージ済み／未ステージの変更／コミット範囲を手動で選ばせることがないよう、必ずどちらかを明示的に指定してください。

複数のマルチプレクサーマーカーが設定されている場合、内側のマルチプレクサーが明らかであればそれを優先し、そうでなければ確認してください。cmux は Ghostty ターミナルをホストするため、cmux 内では $TERM_PROGRAM は ghostty になります。ターミナル名ではなく、$CMUX_WORKSPACE_ID を確認してください。

tuicr は git と Jujutsu（jj）の両方のリポジトリに対応しており、jj のワークスペースには .git ディレクトリがない場合があります。git rev-parse でディレクトリを事前確認したり、git が認識しないことを理由に起動を拒否したりしないでください。必ずラッパーを実行し、リポジトリの検証はラッパーに任せてください。

ラッパーのパスは、このスキルのディレクトリからの相対パスです。

<skill-directory>/tuicr-wrapper-cmux.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-zellij.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-herdr.sh /path/to/repo -- -w

Herdr ラッパーは、Herdr の JSON レスポンスからペイン ID と完了結果を読み取るために jq を必要とします。

すべてのラッパーは、-- の後に tuicr の引数を渡せます。これにより、ユーザーにスコープセレクターを入力させずにレビュー範囲を指定できます。たとえば、未コミットの作業ツリーの変更には -- -w、コミット範囲には -- -r <revset> を指定します。レビュー用ペインを起動するときは、必ずこれらのいずれかを明示的に指定してください。

ツールでコマンドのタイムアウトを設定できる場合は、10 分などの長いタイムアウトを使用してください。tmux、Zellij、Herdr のラッパーは TUI が終了するまで待機するためです。例外は cmux ラッパーで、ペインが起動するとすぐに戻り、新しいサーフェス参照を === TUICR SURFACE === マーカーで囲んで出力します。この参照を取得してください。後で cmux close-surface --surface <ref> を使ってペインを閉じる際に必要です。TUI がアクティブなセッションを作成したら、tuicr review list --repo /path/to/repo を使ってスラッグを取得します。ブロッキング中のラッパーの待機中に環境から別のコマンドを実行できない場合は、ユーザーが tuicr を終了した後にコメントを読んでください。

差分を再構築する

パッチを自分でレビューするには、ユーザーに表示される差分を再構築します。どの差分かは、スラッグのソースセグメントで判断できます。

スラッグのセグメント	差分
worktree/<head>, staged-and-unstaged/<head>	git diff HEAD
staged/<head>	git diff --cached
unstaged/<head>	git diff
commits/<base>..<head>	git diff <base>~1..<head>
pr/<n>	gh pr diff <n>
pristine	なし。追跡対象の各ファイル全体が表示されます

範囲の終点は両端を含み、古い順に出力されるため、~1 のない <base> を指定すると最初のコミットが抜け落ちます。ファイル数を一覧行の file_count と照合してください。一致しない場合、算出したすべての行番号が誤りになります。

ユーザーコメントを読む

これは、ユーザー主導のレビューにおけるメインのレビューループです。

tuicr からエージェントへのプッシュストリームはありません。必要に応じて CLI を実行してコメントを読み取ります。ユーザーがコメントの準備ができたと伝えた後、または TUI が終了した後に、次を実行します。

tuicr review comments --repo /path/to/repo --session <slug>

このコマンドは JSON を出力します。各コメントには、次のようなフィールドが含まれます。

• id
• location
• path
• start_line
• end_line
• side
• comment_type
• author
• lifecycle_state
• content

これらのコメントは、ユーザーからのレビューのフィードバックとして扱います。

• issue：先に修正すべき重大な問題
• suggestion：実装を検討するか、実装しない理由を説明する
• note：回答または受領を伝える
• praise：対応不要

レビュー中に待機している場合は、約 30 秒ごとにこのコマンドをポーリングし、コメント ID を前回の結果と比較します。ユーザーがコメントの準備ができたと伝えたら、すぐに読み取ります。ユーザーがレビューの完了を伝えたとき、またはツールの使用によって他の作業が妨げられる場合は、ポーリングを停止します。

結果が空でも、それだけでレビューが行われなかったことを意味するわけではありません。終了時に、tuicr は常に tuicr-summary: reviewed 3/3 files, 0 comments added のような行を stderr に出力します（ペインのスクロールバックに表示されます）。また、tuicr review list には、そのセッションの同じ reviewed_count／file_count が表示されます。reviewed_count が file_count と等しく、コメントが 0 件の場合は、「指摘事項なし」という正当な結果です。レビューは完了したものとして扱い、ユーザーに確認を求めないでください。reviewed_count が file_count より少ない場合（ユーザーがすべてをレビューする前に終了した場合）、または tuicr-summary: 行が見つからない場合に限り、ユーザーが意図したセッションにコメントを保存したか、別のアクティブなセッションを選択すべきかを確認してください。作業中にレビューが続けられた可能性がある場合は、完了を報告する前に tuicr review comments を再実行してください。

エージェントのコメントを追加する

ワークフローで許可されている場合にのみコメントを追加してください。また、エージェントが作成したレビューコメントについては、tuicr への書き込みをユーザーが承認した後に限ります。

デフォルト：

• 特定のファイルと行がわかっている場合は、行コメントを優先します。
• ファイル単位のフィードバックには、ファイルコメントを使用します。
• レビュー全体の要約に限り、レビュー全体へのコメントを使用します。
• 問題には、デフォルトで --type issue を使用します。
• 意図により適している場合は、suggestion、note、または praise を使用します。
• エージェントのコメントを区別できるように、--username を指定します。

例：

tuicr review add --repo /path/to/repo --session <slug> \
  --target-file src/main.rs \
  --line 42 \
  --side new \
  --type issue \
  --username "Codex" \
  "Handle the empty case here."

tuicr review add --repo /path/to/repo --session <slug> \
  --target-file src/main.rs \
  --type suggestion \
  --username "Codex" \
  "Consider splitting this file-level concern into a helper."

レビュー全体へのコメントには --target-file を省略します。範囲コメントには --end-line を追加します。削除された行には --side old を使用し、新しいファイルの追加行または変更されていない行には --side new を使用します。

構造化入力には、リテラル JSON、@path/to/file.json、または標準入力を示す - を指定して --input を使用します。1 回の呼び出しにつきオブジェクトは 1 つです。配列は解析エラーになります。ファイルのキーは path ではなく file です。target.type は、存在するフィールドから推定されます。

tuicr review add --session <slug> --username "Codex" --input \
  '{"file":"src/main.rs","line":42,"side":"new","comment_type":"issue","content":"Handle the empty case."}'

その後、確認します。差分に含まれない行でも保存され、出力され、終了コード 0 で終了しますが、表示はされません。ユーザーには見えず、成功したように見えるだけです。tuicr review comments を再度読み込み、指定した側（追加行または変更されていない行には new、削除された行には old）に各 start_line が存在することを確認してください。author を確認して自分のコメントとユーザーのコメントを区別し、後で正確なコメントを特定できるよう、返された id を控えておいてください。

レガシーエクスポートの出力

古いラッパー駆動のフローでは、次のような出力が行われることがあります。

=== TUICR INSTRUCTIONS ===
...
=== END TUICR INSTRUCTIONS ===

出力がある場合は、その指示に従って処理します。ない場合は、主なレビューのフィードバック元である tuicr review comments を優先してください。ラッパーがクリップボードへのエクスポートに言及している場合は、CLI のコメントを取得できないときに限り、ユーザーに貼り付けを依頼してください。

マルチプレクサーのヒント

cmux：

• ペインを切り替える：ペインをクリックするか、cmux focus-pane --pane <ref> を実行します
• tuicr を閉じる：q を押します。ペインは自動的に閉じます。強制的に閉じるには、cmux close-surface --surface <ref> を実行します
• ペインを一覧表示する：cmux list-panes
• フォーカスを移さずにペインを読み取る：cmux read-screen --surface <ref>

tmux：

• ペインを切り替える：Ctrl-b を押してから矢印キーを押します
• tuicr を閉じる：q を押します
• ペインのサイズを変更する：Ctrl-b を押してから Ctrl-arrow を押します
• ペインをズームする：Ctrl-b を押してから z を押します

zellij：

• ペインを切り替える：Alt と矢印キーを押します
• tuicr を閉じる：q を押します
• ペインのサイズを変更する：Ctrl-n を押してから矢印キーを押します
• 全画面表示を切り替える：Alt-f
• スタックされたペインを切り替える：Alt と [ / ] を押します

Herdr：

• ペインを選択する：Herdr の UI でペインをクリックします
• tuicr を閉じる：q を押します。ラッパーがレビュー用ペインを閉じます

エラー処理

状況	対応
アクティブなセッションの候補が複数ある	使用するセッションのスラッグを確認します
アクティブなセッションがなく、cmux/tmux/Zellij/Herdr が利用可能	対応するラッパーで新しい tuicr ペインを開始します
アクティブなセッションがなく、マルチプレクサーもない	ユーザーが tuicr を起動するのを待っていることを伝えます
cmux ラッパーがサーフェス参照を出力しなかった	cmux list-panes を実行してペインを探すか、ユーザーに tuicr を起動してもらいます
tuicr がインストールされていない	tuicr のインストールをユーザーに伝えます
リポジトリではない	正しいリポジトリディレクトリを尋ねます
コメントが空で、reviewed_count == file_count	フラグすべき点がないレビュー完了として扱います。確認は不要です
コメントが空で、reviewed_count < file_count	選択したセッションを確認するか、コメントの保存・追加をユーザーに依頼します

使用しない場合

• ユーザーが生の git diff 出力のみを求めている場合。
• ユーザーが tuicr を使わないレビューのワークフローを明示的に求めている場合。
• リモート PR のレビュー作業で、tuicr の PR セッションが関与していない場合。