pw_ghish#

GitHub CLI-like interface for Gerrit code reviews and CI checks

Experimental Go

  • GitHub CLI syntax for Gerrit, LUCI, and Buganizer: Interact with Gerrit code reviews (gh pr), LUCI Buildbucket tryjobs (gh run), and Buganizer issues (gh issue) using standard gh commands.

  • Built for humans and coding agents: Developers and AI agents already familiar with the GitHub CLI can create changes, reply to review threads, inspect CI logs, and manage bugs without custom REST scripts.

  • Worktree and Bazel cache pooling: Manage isolated Git worktrees backed by a shared pool of warm Bazel output bases and IDE workspace synchronization via ./gh wt.

  • Repository wrapper: Run ./gh from the repository root with automatic per-commit compilation and local binary caching in out/gh/.

pw_ghish (invoked via the ./gh wrapper at the repository root) provides GitHub CLI commands on top of Gerrit Code Review, LUCI Buildbucket, Google Issue Tracker (Buganizer), and local Git/Bazel worktree pools.

Warning

EXPERIMENTAL: pw_ghish is experimental for upstream Pigweed and is not ready for other projects yet. Despite its broad functionality, the tool is still very fresh and under active iteration—commands, flags, and workflows may change. See Status & roadmap for current status and upcoming milestones.

Getting started#

Run the ./gh repository wrapper from anywhere in your Pigweed checkout:

# View review status for the active branch and your open CLs:
$ ./gh pr status

# Push a new patchset on the current branch to Gerrit:
$ ./gh pr push --cq

# Watch LUCI tryjob builders and print step failure logs on failure:
$ ./gh pr checks --watch --fail-fast

# Inspect step execution trees or rerun failed builders via LUCI:
$ ./gh run view -j pigweed-lintformat
$ ./gh run rerun --failed

# File a Buganizer issue and add 'Bug: b/<id>' to your HEAD commit:
$ ./gh issue create --title "pw_foo: Fix bar overflow" --body "..." --amend

# Allocate an isolated warm worktree slot for an issue or feature:
$ ./gh wt use --issue 315378787

# Enable automated submission once review and CI checks pass:
$ ./gh pr merge --auto

The ./gh wrapper compiles and caches the //pw_ghish:gh-ish binary in out/gh/ keyed by Git commit hash, reusing the cached binary when HEAD has not changed.

Root-level aliases and global flags#

For common commands, ./gh provides top-level aliases and global flags:

  • Root aliases: ./gh push (pr push), ./gh status (pr status), ./gh view (pr view), ./gh diff (pr diff), ./gh checks (pr checks), and ./gh worktree (wt).

  • Global flags: --host <domain> (override Gerrit host), --profile <name> (force pigweed, fuchsia, or generic profile), and -v, --verbose (enable debug logging).

Documentation#

Life of a PR

Step-by-step walkthrough of creating a CL, running LUCI presubmits, addressing review comments, and landing via Commit-Queue or Auto-Submit.

Life of a PR
Subcommands

Reference for gh pr, gh run, gh issue, gh auth, gh hook, and gh wt, including comparisons with upstream gh.

Subcommands
Agent setup

Multi-harness rules/skills discovery (Antigravity/Jetski, Claude Code, Codex, Cursor, OpenCode) and optional local PreToolUse hook setup.

Agent setup
Agent workflows

Workflows for agent pair programming: private draft steering, staged review replies, CL handoffs, CI failure repair, and parallel agents.

Agent workflows
Project setup

Building standalone binaries, setting up repository wrappers, and configuring project profiles.

Project setup
Developing

Building and testing pw_ghish, flag compatibility policy, agent evaluation runbook, and status & roadmap.

Developing