cmux-team-gh

cmux-team-gh: GitHub issue/PR キャッシュ経由の読み取り

このスキルは cmux-team plugin に同梱される GitHub issue/PR キャッシュの 使い方リファレンスです。gh issue / gh pr の 読み取り系 は cmux-team issue / cmux-team pr に置き換えてください。

なぜ gh を直接使わないか

• gh を叩くたびに GitHub API を呼ぶため、複数 issue を走査する用途 （レビュー待ち一覧、最近 close された PR の確認等）で rate limit を 消費しやすい。
• cmux-team gh sync は ETag (If-None-Match) + since= による差分同期で、 変更がなければ 304 Not Modified（rate limit 消費 0）で返る。
• 同一プロジェクト内で複数エージェントが同じ issue を参照する場合、 キャッシュから読むため何度でも同じコストで読める。

トリガー判定（Claude 向け）

以下のいずれかの場合にこのスキルを適用してください:

• ユーザーが issue/PR 番号に言及（#272, issue 272, PR #42, T042 等）
• ユーザーが gh issue list / gh pr view 等を実行したがっている
• ユーザーが ghe ...（企業 GitHub）を実行したがっている — 同じキャッシュで読める
• 「レビュー待ち」「open な PR」「直近 closed」「自分にアサインされた issue」等、 issue/PR の問い合わせ全般
• @me に割り当てられた issue を探している
• 特定ラベル（bug, help wanted 等）の絞り込みをしたい

置換表

代わりに	使うもの
gh issue list --state open --limit 20	cmux-team issue list --state open --limit 20
gh issue list --assignee @me	cmux-team issue list --assignee @me
gh issue list --label bug	cmux-team issue list --label bug
gh issue view 272	cmux-team issue show 272
gh issue view 272 --json title,body,labels	cmux-team issue show 272 --json title,body,labels
gh pr list --state open	cmux-team pr list --state open
gh pr view 42	cmux-team pr show 42
gh pr view 42 --json state,title,reviews	cmux-team pr show 42 --json state,title,reviews
gh search issues keyword	cmux-team issue search keyword

JSON 出力のキー名は gh --json 互換です（author.login, assignees[].login, labels[].name, createdAt, mergedAt など）。 既存の jq パイプラインをそのまま使えます。

# 例: open PR の author 一覧を取得
cmux-team pr list --state open --json number,title,author.login

キャッシュが古いと感じたら

• 差分同期（ほぼ無料）: cmux-team gh sync
  • 前回同期以降に更新された issue/PR のみ取得
  • 変更がなければ 304 Not Modified
• フル同期: cmux-team gh sync --full
  • 直近 500 件の issue/PR を最初から取得
  • 初回実行 / トークン変更 / 月 1 回の運用推奨
  • 削除・transfer された issue を cleanup する唯一の手段
• 状態確認: cmux-team gh status
  • 最終 sync 時刻、rate limit 残量、viewer login、issue/PR 件数
  • 「最終 full sync から N 日経過」表示に注意
  • 30 日を超えたら --full 推奨

省略コマンドとしての --sync

一発で同期 + 読み取りを行いたい場合は list/show に --sync を付けられます:

cmux-team issue list --state open --sync    # 事前 incremental sync してから表示
cmux-team issue show 272 --sync              # 対象 issue を同期してから表示

TUI Issues タブ

cmux-team start で起動する Manager ダッシュボードには「Issues」タブが あります（キーバインド 5 または I）。

• R — incremental sync を走らせる
• Enter / O — 選択中 issue を markdown ビューアで開く
• B — 選択中 issue の GitHub URL をブラウザで開く
• ↑ / ↓ — カーソル移動

書き込み系は gh を使う

以下の操作は本 skill の対象外です。引き続き gh を使ってください:

• gh issue create — issue 作成
• gh issue comment / gh pr comment — コメント追加
• gh issue close / gh pr close — クローズ
• gh pr merge — マージ
• gh pr review — レビュー送信

書き込みを行った後は cmux-team gh sync でキャッシュを更新してください。

無効化される状況

以下の場合、このスキルは使えません。従来通り gh を直接使ってください:

• 起動ディレクトリが git repo でない（exit 2）
• origin が GitHub / GHE でない（exit 2）
• 認証トークンが無い（exit 3）
  • gh auth login を実行するか、GITHUB_TOKEN / GH_TOKEN を設定

rate limit 到達時（exit 4）

cmux-team gh sync が exit 4 を返した場合、しばらく待って（reset_at 表示を参照）再度実行してください。cmux-team issue list --stale-ok で 警告を抑止して古いキャッシュから読み続けることも可能です。

Exit codes

code	意味
0	成功
1	汎用エラー
2	非 git / 非 GitHub origin
3	認証欠如
4	rate limit 到達

キャッシュの場所

• DB: .team/gh-cache.db（SQLite WAL）
• 本文 / raw JSON は同 DB 内に格納（別ファイルなし）
• トークンハッシュ不一致 / 異なる repo を検出したら自動 purge

プロジェクト毎に独立したキャッシュを持つため、複数リポジトリを横断して 参照する用途には使えません（各リポジトリで個別に cmux-team start / cmux-team gh sync を走らせてください）。