# Github Remote

> Read-first wrapper around the GitHub REST API. Single-call PR/branch overviews (PR state + checks + reviews + workflow runs + mergeable) for triage. Use whenever the user wants the state of a PR, a branch's CI, or a failing run — without you chaining `gh pr view`, `gh pr checks`, `gh run view`, `gh pr list --head` per investigation. Resolves PRs and issues by branch/title. `run wait` polls on a r…

- **Type:** Skill
- **Install:** `agentstack add skill-osouthgate-agent-plus-skills-github-remote`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [osouthgate](https://agentstack.voostack.com/s/osouthgate)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [osouthgate](https://github.com/osouthgate)
- **Source:** https://github.com/osouthgate/agent-plus-skills/tree/main/github-remote/skills/github-remote

## Install

```sh
agentstack add skill-osouthgate-agent-plus-skills-github-remote
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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`):

```bash
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:

```json
{
  "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](https://github.com/osouthgate)
- **Source:** [osouthgate/agent-plus-skills](https://github.com/osouthgate/agent-plus-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-osouthgate-agent-plus-skills-github-remote
- Seller: https://agentstack.voostack.com/s/osouthgate
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.