cursor-github-cli

A Cursor skill + subagent that teaches the AI to use the gh CLI efficiently — replacing ad-hoc Python parsing with --jq patterns and delegating context-heavy GitHub fetches to a cheap Composer 2 subagent.

What you get:

• ~/.cursor/skills/github-cli/ — pattern reference the AI auto-loads when it sees GitHub work
• ~/.cursor/agents/github-fetch.md — Composer 2 subagent that fetches and summarizes GitHub data without bloating your main chat context
• ~/.cursor/sandbox.json — network allowlist so the subagent's gh calls actually reach GitHub

Install

gh repo clone ben-smith-atg/cursor-github-cli
cd cursor-github-cli
./install.sh

The installer is idempotent. Re-running backs up your existing files to *.bak.<timestamp> rather than overwriting.

sandbox.json safety: if you already have ~/.cursor/sandbox.json, the installer will NOT overwrite it — it'll print the rules you need to add manually. See sandbox.json.example for the reference config.

After install

1. Restart Cursor (or open a fresh chat) so the new agent definition is picked up.
2. Verify gh auth: gh auth status should show you logged in.
3. Verify SSO (if your org requires it):

   gh auth refresh -h github.com -s repo,read:org

4. Test it — paste a prompt from EXAMPLES.md into a fresh Cursor chat.

Usage

The AI auto-loads the skill when it sees GitHub-related work. The subagent auto-delegates when it sees high-volume fetches (10+ comments, multi-PR comparisons, etc.).

You can also force-invoke the subagent:

/github-fetch summarize unresolved review comments on https://github.com/OWNER/REPO/pull/123

See EXAMPLES.md for ready-to-paste prompts.

When it doesn't work

See TROUBLESHOOTING.md. Most common issue: sandbox network blocks → fix in ~/.cursor/sandbox.json.

Update

cd cursor-github-cli
git pull
./install.sh

Uninstall

./uninstall.sh

Backs up to *.removed.<timestamp> rather than deleting outright. Does not touch sandbox.json (it may have rules from other tools).

Required gh setup

• gh v2.85+ installed (brew install gh)
• Authenticated: gh auth login -h github.com
• Token scopes: at minimum repo and read:org
• For SAML-protected orgs (e.g. LIVEauctioneers): gh auth refresh -h github.com -s repo,read:org and complete the SSO flow in your browser

Layout

cursor-github-cli/
├── README.md                # this file
├── EXAMPLES.md              # copy-paste prompts that demo the skill
├── TROUBLESHOOTING.md       # common failure modes + fixes
├── install.sh               # idempotent installer
├── uninstall.sh             # reversal
├── sandbox.json.example     # reference network policy
├── skills/
│   └── github-cli/
│       ├── SKILL.md
│       └── scripts/
│           ├── repo-context.sh
│           └── read-file.sh
└── agents/
    └── github-fetch.md