pi-gh-cli

A pi coding agent extension that wraps the GitHub gh CLI as a single typed tool — directly, not via an MCP server.

What it provides

• a gh custom tool with typed parameters (subcommand + args map + repo + jsonFields + jq + limit + timeoutSeconds + forceDangerous)
• a bundled SKILL.md documenting the tool and common gh commands
• per-turn prompt guidance when a prompt mentions GitHub, PRs, issues, repos, releases, workflows, or gists
• graceful detection of the "not authenticated" failure with actionable guidance
• a safety guard that refuses repo delete, release delete, and codespace delete (unrecoverable) unless forceDangerous: true is set

Why not MCP?

The gh CLI already exposes the full GitHub API (repos, PRs, issues, releases, Actions, gists) and uses the user's existing gh auth login credentials. Wrapping it in a typed pi tool gives structured, discoverable parameters and output truncation without an extra server process.

Requirements

• gh CLI on PATH — cli.github.com
• Authenticated via gh auth login

Installation

Drop the extension into ~/.pi/agent/extensions/ (global) or .pi/extensions/ (project-local), then reload:

/reload

Or install from git:

pi install git:github.com/sfroment/pi-gh-cli

Tool parameters

Parameter	Type	Description
subcommand	string	The full gh subcommand path (e.g. "pr list", "repo view", "issue view 42"). Top-level — never nest inside args.
args	object	A key/value object of flags ONLY — never an array, and do not nest subcommand/jsonFields/jq/repo/limit here. Booleans → bare --flag ({web: true} → --web). Strings/numbers → --flag value ({state: "open"} → --state open). Arrays → repeated --flag value pairs ({label: ["bug","urgent"]} → --label bug --label urgent).
repo	string	Target repository as owner/repo (→ --repo owner/repo).
jsonFields	string[]	Fields to return as JSON (→ --json field1,field2).
jq	string	jq expression to filter JSON output (→ --jq expr).
limit	integer	Maximum results (→ --limit N). Only list-style commands accept it — view commands reject it; the tool strips the flag and runs (noted in the output) instead of failing the call.
timeoutSeconds	integer	Command timeout (default 30, max 120).
forceDangerous	boolean	Opt-in for destructive commands (repo delete, release delete, codespace delete).

Examples

List open PRs in a repo:

{
  "subcommand": "pr list",
  "args": { "state": "open" },
  "repo": "owner/repo",
  "jsonFields": ["number", "title", "state"],
  "limit": 10
}

View a specific issue:

{
  "subcommand": "issue view 42",
  "repo": "owner/repo",
  "args": { "comments": true }
}

Development

bun test          # pretest links pi runtime deps automatically
bunx tsc --noEmit # type-check

License

GPL-3.0

Links

• Author: Sacha Froment
• Source: https://github.com/sfroment/pi-gh-cli
• Issues: https://github.com/sfroment/pi-gh-cli/issues