Github Remote

github-remote

Project-scoped CLI that wraps the GitHub REST API into a read-first, JSON-output triage tool. Stdlib-only Python 3 (no pip installs, no venvs). Designed for agent-driven PR/CI inspection — one call returns PR state + checks + reviews + runs so you don't burn tool calls chaining gh pr view / gh pr checks / gh run view per investigation.

Lives at ${CLAUDE_SKILL_DIR}/../../bin/github-remote; the plugin auto-adds bin/ to PATH, so just run github-remote ....

Prerequisites

• GITHUB_TOKEN set in project .env / .env.local / shell env, OR gh logged in (the CLI falls back to gh auth token). Get a PAT at https://github.com/settings/tokens.
• Repo resolution: pass --repo owner/name, or set GITHUB_REPO, or run from a git checkout whose origin points at github.com.

The CLI bails with a clear missing-config message if neither auth nor repo is resolvable.

When to reach for this

• User asks "is this PR green / mergeable" → run overview --pretty. One call → PR + checks + reviews + runs + mergeable + review comment count.
• User asks "why did CI fail on " → run overview to see failing job names, then run logs --errors-only --tail 100.
• User asks "resolve the PR for " → run pr resolve . Exits non-zero with candidates on ambiguity; never auto-picks.
• User asks "wait for the run on main" → run run wait main --timeout 1800. Accepts a branch or a run ID. Exits non-zero on timeout or non-success conclusion.
• User asks "post a comment on PR 498" → run pr comment 498 --body '…'. Posts via /issues/{n}/comments (issue-style comments on PRs, which is what gh pr comment does).

Headline commands

github-remote pr list [--state open|closed|merged|all] [--base ] [--author ] [--limit 50]
github-remote pr resolve 
github-remote pr show 
github-remote pr comment  --body 

github-remote issue list [--state open|closed|all] [--assignee ] [--label ] [--limit 50]
github-remote issue resolve 
github-remote issue show 

github-remote run list [--branch ] [--status in_progress|completed|queued] [--limit 20]
github-remote run show 
github-remote run logs  [--job ] [--errors-only] [--tail 50]
github-remote run wait  [--timeout 1800] [--poll-interval 10]

github-remote overview 

github-remote whoami [--json]   # identity for `agent-plus refresh` ("what's my github identity")

All list/show commands emit JSON to stdout. Use --pretty for indentation.

jq-friendly. Default compact JSON pipes cleanly into jq. Every dict payload also carries a top-level tool: {name, version} field (injected by _with_tool_meta) so agents can self-diagnose version drift from the output alone — no extra --version subprocess call needed. Prefer jq against stable keys (.pr.number, .checks.failing_jobs[], .runs[].conclusion) rather than parsing human output.

Offloading large responses with --output

GitHub responses balloon quickly — run logs on a failing build, long pr list, run show with dozens of check annotations. Pulling the full payload through the model's context wastes tokens when you only need a slice.

Pass --output before the subcommand (it's a top-level flag, same position as --pretty):

github-remote --output /tmp/run.json run logs 1234567890 --errors-only
github-remote --output /tmp/prs.json pr list --state open --limit 100

Stdout returns a compact envelope instead of the full payload:

{
  "tool": {"name": "github-remote", "version": "..."},
  "payloadPath": "/tmp/run.json",
  "bytes": 93420,
  "fileLineCount": 2104,
  "payloadKeys": ["run_id", "jobs", "failing_jobs"],
  "payloadShape": {
    "run_id": {"type": "number"},
    "jobs": {"type": "list", "length": 12,
      "sample": {"type": "dict", "keys": 6,
        "shape": {"name": {"type": "string", "length": 8},
                  "conclusion": {"type": "string", "length": 7},
                  "annotations": {"type": "list", "length": 23}}}},
    "failing_jobs": {"type": "list", "length": 2}
  }
}

How to act on it:

1. payloadShape tells you what's in the file without reading it. Agent sees jobs[0].annotations.length: 23 and knows the interesting data is nested under each job.
2. Use Read with offset/limit to pull only the slice you need.
3. For list-shaped responses (pr list, run list), the envelope has payloadType: "list" + payloadLength + sampleShape.

--shape-depth controls recursion depth. Default is 3 (two layers — surfaces checks[0].annotations.length or prs[0].head.sha). --shape-depth 1 gives a minimal top-level-only envelope.

When NOT to use --output: small responses (pr resolve, issue show for a single item), or when you need the data in the same turn to act on.

Design rules (agent-plus patterns)

1. Aggregate server-side. overview returns PR state + mergeable + check-runs rollup + review summary + latest runs in one call — replaces 4-6 gh invocations.
2. Resolve by name. pr resolve feat/foo and issue resolve 'flaky test' — you never copy PR numbers between commands. Ambiguity never auto-picks: exits non-zero with up to 10 candidates so the agent can re-query.
3. --wait on async flows. run wait polls on a run ID or branch name with a 30-min default timeout and 10s poll interval. On timeout: non-zero exit with partial JSON including last-known state. Never hangs.
4. --json is the default. No human-prose output paths. Pipe to jq freely.
5. Zero token leakage. Every API response walks through _scrub(), which redacts token, password, authorization, client_secret, private_key, webhook_url_with_secret, access_token, refresh_token, secret, api_key. Free-text log blobs from run logs are regex-scrubbed for ghp_…, github_pat_…, gho_…, ghu_…, ghs_…, ghr_…, AKIA…, and Bearer … patterns. A canary no-leak test asserts a known secret substring cannot appear on any output path.

Overview output caps

Documented in --help and honoured by the CLI so agents can budget context:

• Reviews: 10 latest
• Failing jobs: 20
• Workflow runs tied to head SHA: 5

Config precedence (highest first)

1. --token / --repo CLI flags
2. --env-file if passed
3. .env.local / .env walked up from cwd (closest wins)
4. Shell env

Only GITHUB_* prefixed vars are picked up.

Auth precedence (highest first)

1. GITHUB_TOKEN env var (explicit, CI-friendly; fine-grained and classic PATs both flow here)
2. gh auth token subprocess (inherits your local gh login — best DX on dev machines)
3. Fail with a missing-config message pointing at .env, ~/.claude/settings.json, and gh auth login.

Rate limits

• X-RateLimit-Remaining / X-RateLimit-Reset headers are read on every response. When remaining , gh workflow list, or POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches. github-remote run *` is read-only (list/show/logs/wait).
• Releases, tags, team/repo admin, branch protection, secrets management. → gh release ..., gh api ..., or the dashboard. Entirely out of wrapper scope.
• GitHub Enterprise Server (non-api.github.com hosts). → gh with GH_HOST set, or curl against your GHES base URL. GITHUB_API_URL is reserved but not wired up in v1.
• Git operations — cloning, checkouts, pushing, branch creation, local diffs. → plain git and gh repo clone. The wrapper has no git surface at all.

Don't get stuck in a loop. If the user's request obviously needs a write github-remote doesn't support (merge, create, dispatch, close), immediately switch to gh or curl rather than hunting for a wrapper flag that doesn't exist. The wrapper exists to make reading PR/CI state faster and safer — it is not a replacement for gh.

What it doesn't do

Deliberately out of scope for v1:

• pr create, pr merge, issue create, issue close (deferred — distinct safety contracts)
• Workflow authoring or workflow dispatch / workflow run
• Team, releases, repo admin, secrets management
• GitHub Enterprise Server (v1 assumes api.github.com; GITHUB_API_URL is reserved for future GHES support)
• GraphQL migration (REST covers every v1 command)

Use the gh CLI or dashboard for those. This plugin is read-first PR/CI triage plus one write.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: osouthgate
• Source: osouthgate/agent-plus-skills
• License: MIT

Install and usage instructions live in the source repository linked above.