cmux-team-gh

cmux-team-gh: Reading via GitHub issue/PR cache

This skill cmux-team This is a usage reference for the GitHub issue/PR cache bundled with the plugin.gh issue / gh pr の Read operations は cmux-team issue / cmux-team pr replace with this.

Why gh Do not use this directly, or

• gh Because the GitHub API is called every time this is invoked, rate limits are easily consumed for use cases that scan multiple issues (waiting-for-review lists, checking recently closed PRs, etc.).
• cmux-team gh sync は ETag (If-None-Match) + since= with differential sync, if there are no changes it returns 304 Not Modified(0 rate limit consumption).
• When multiple agents within the same project reference the same issue, reading from the cache allows reading at the same cost any number of times.

Trigger determination (for Claude)

Apply this skill in any of the following cases:

• The user mentions an issue/PR number (#272, issue 272, PR #42, T042 etc.)
• The user gh issue list / gh pr view etc.)
• The user ghe ...(enterprise GitHub) — can be read from the same cache
• General issue/PR inquiries such as "waiting for review", "open PRs", "recently closed", "issues assigned to me", etc.
• @me Looking for issues assigned to
• Want to filter by a specific label (bug, help wanted etc.)

Replacement table

Instead	What to use
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

The JSON output key names are gh --json compatible (author.login, assignees[].login, labels[].name, createdAt, mergedAt etc.). Existing jq pipelines can be used as-is.

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

If you feel the cache is stale

• Differential sync (nearly free): cmux-team gh sync
  • Fetch only issues/PRs updated since the last sync
  • 304 Not Modified if there are no changes
• Full sync: cmux-team gh sync --full
  • Fetch the most recent 500 issues/PRs from scratch
  • First run / token change / once-a-month operation recommended
  • The only way to clean up deleted or transferred issues
• Status check: cmux-team gh status
  • Last sync time, remaining rate limit, viewer login, issue/PR counts
  • Pay attention to the "N days since last full sync" display
  • If it exceeds 30 days, --full recommended

As an abbreviated command, --sync

If you want to sync + read in one shot, you can add this to list/show: --sync :

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

TUI Issues tab

cmux-team start The Manager dashboard started with has an "Issues" tab (keybinding 5 or I）。

• R — run incremental sync
• Enter / O — open the selected issue in the markdown viewer
• B — open the selected issue's GitHub URL in the browser
• ↑ / ↓ — move cursor

For write operations, use gh use this

The following operations are outside the scope of this skill. Continue using gh :

• gh issue create — create issue
• gh issue comment / gh pr comment — add comment
• gh issue close / gh pr close — close
• gh pr merge — merge
• gh pr review — Submit review

After writing, update the cache with cmux-team gh sync .

Conditions under which it is disabled

This skill cannot be used in the following cases. Use gh directly as before:

• The startup directory is not a git repo (exit 2)
• origin is not GitHub / GHE (exit 2)
• No authentication token (exit 3)
  • gh auth login or run,GITHUB_TOKEN / GH_TOKEN set

When the rate limit is reached (exit 4)

cmux-team gh sync returns exit 4, wait a while (reset_at see the display) and run it again.cmux-team issue list --stale-ok You can also suppress the warning and keep reading from the old cache with

Exit codes

code	Meaning
0	Success
1	Generic error
2	Non-git / non-GitHub origin
3	Missing authentication
4	Rate limit reached

Cache location

• DB: .team/gh-cache.db（SQLite WAL）
• The body / raw JSON is stored in the same DB (no separate file)
• Automatically purge when a token hash mismatch or a different repo is detected

Because each project has an independent cache, it cannot be used for referencing across multiple repositories (run cmux-team start / cmux-team gh sync individually in each repository).