huggy-pr-agent 0.0.0-stage → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +42 -0
- package/INSTALL.md +142 -0
- package/LICENSE +21 -0
- package/README.md +285 -2
- package/action.yml +672 -0
- package/assets/architecture.svg +88 -0
- package/assets/banner-dark.svg +100 -0
- package/assets/banner-light.svg +100 -0
- package/assets/banner.svg +100 -0
- package/assets/huggy-icon.svg +97 -0
- package/assets/huggy-reviewing.svg +235 -0
- package/assets/inline-review-preview.png +0 -0
- package/examples/dependabot.yml +8 -0
- package/examples/google-vertex.yml +73 -0
- package/examples/node-pnpm.yml +61 -0
- package/examples/swift-macos.yml +63 -0
- package/extensions/huggy.ts +150 -0
- package/package.json +53 -4
- package/pi-prompts/huggy-review.md +14 -0
- package/prompts/ask.md +10 -0
- package/prompts/describe.md +22 -0
- package/prompts/fix.md +22 -0
- package/prompts/improve.md +28 -0
- package/prompts/judge.md +61 -0
- package/prompts/review.md +95 -0
- package/scripts/ensure_tools.sh +81 -0
- package/scripts/fetch_pr_context.py +955 -0
- package/scripts/post_progress.py +129 -0
- package/scripts/post_review.py +599 -0
- package/scripts/prepare_command.py +266 -0
- package/scripts/run_review.py +870 -0
- package/skills/huggy-review/SKILL.md +31 -0
- package/skills/setup-huggy-pr-agent/SKILL.md +13 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `huggy-pr-agent` are documented in this file.
|
|
4
|
+
|
|
5
|
+
## [1.8.0] - 2026-11-12
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- **First-class Pi Package (`package.json` + `extensions/huggy.ts` + `pi-prompts/huggy-review.md`)**: installable via `pi install git:github.com/tripplen23/huggy-pr-agent` or `pi install npm:huggy-pr-agent` (`pi-package` gallery metadata included). Adds `/huggy review [base]`, `/huggy review deep [base]`, `/huggy setup`, `/huggy sync`, and the `huggy_prepare_diff` tool inside Pi.
|
|
9
|
+
- **Portable Cross-Harness Review Skill (`skills/huggy-review/SKILL.md`)**: brings Engine v3 local branch review to Claude Code, Codex, Cursor, Windsurf, OpenCode, and Pi via `npx skills add tripplen23/huggy-pr-agent`.
|
|
10
|
+
- **1-Click Update Sync (`examples/dependabot.yml` + `/huggy sync`)**: supports both automatic zero-click updates via `@v1` and 1-click merge PRs via Dependabot / Renovate when pinning `@v1.x.y`.
|
|
11
|
+
|
|
12
|
+
## [1.7.2] - 2026-11-12
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
- **Adaptive Timeout Step-Down (`scripts/run_review.py`)**: steps `thinking` down to `low` after a wall-clock `TimeoutExpired` and degrades the final fallback pass to `--no-tools` diff-only review with a reserved 300s budget so dense multi-endpoint bundles never time out across all attempts.
|
|
16
|
+
- **Balanced Bundle Sizing**: tightened default bundle limits to `8 files / 1,100 changed lines` to avoid lopsided bundles on medium-large PRs.
|
|
17
|
+
|
|
18
|
+
## [1.7.1] - 2026-11-12
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
- **Minimal Dark/Light Wordmark Lockup (`assets/banner-dark.svg`, `assets/banner-light.svg`)**: clean `<picture>` hero adapting automatically to GitHub Dark and Light themes.
|
|
22
|
+
|
|
23
|
+
## [1.7.0] - 2026-11-12
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
- **Engine v3 Precision Judge (`0–100` confidence, `>= 80` inline cutoff)**: verifies findings against ground-truth code and base-branch `AGENTS.md` + path-scoped rules, enforcing 7 Hard Exclusions and demoting `65–79` items to `Low`.
|
|
27
|
+
- **Two-Channel `chill` vs `assertive` Output (`review_profile: chill` default)**: posts `High`/`Medium` defects inline and collapses `Low` items inside `<details><summary>🧹 Nitpicks</summary>`.
|
|
28
|
+
- **Base-Branch Path-Scoped Rules & `.gitattributes` Gate**: collects ancestor `AGENTS.md`/`CLAUDE.md`/`REVIEW.md` and `.github/instructions/*.instructions.md` (`applyTo` globs with brace expansion), and skips `linguist-generated` / `linguist-vendored` files.
|
|
29
|
+
- **Failed CI Check Log Excerpts & Content-Anchored Suggestion Relocation**: extracts `##[error]` lines from failing head-commit GitHub Actions jobs and repairs `1–5` line drift on `suggestion` blocks.
|
|
30
|
+
- **Dual-Lens Deep Mode (`review_depth: deep` / `/review deep`)**: runs parallel Logic/Callers and Security/Spec passes merged through the Judge.
|
|
31
|
+
|
|
32
|
+
## [1.6.3] - 2026-11-12
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
- **Rebrand to Huggy PR Agent (`tripplen23/huggy-pr-agent`)**: stoic 16-bit pixel-art reviewing indicator (`assets/huggy-reviewing.svg`, shown only while running) and static `Review by Huggy` icon (`assets/huggy-icon.svg`). Supports both `@huggy`/`/huggy` and `@pi`/`/pi` triggers.
|
|
36
|
+
- **Native Google Vertex AI & Cross-Provider Failover**: `gcp_project`, `gcp_location`, and `gcp_credentials_json` inputs with automatic `pi update --models` catalog caching.
|
|
37
|
+
- **Agent Installation Playbook (`INSTALL.md` + `skills/setup-huggy-pr-agent/SKILL.md`)**: 1-prompt agent setup for any repository.
|
|
38
|
+
|
|
39
|
+
## [1.5.1] - 2026-11-11
|
|
40
|
+
|
|
41
|
+
### Added
|
|
42
|
+
- **Smart Parallel Bundling for 10k+ LOC PRs, Fact-Checker Judge Pass & Linked Issues (`#4`, `#5`)**: counterpart file bundling, adaptive timeouts, GraphQL `closingIssuesReferences`, collaborator write-access verification (`/collaborators/{username}/permission`) for concealed org members, and rich inline diff context in `.pi-fix-request.md`.
|
package/INSTALL.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Huggy PR Agent — Agent Installation Playbook (`INSTALL.md`)
|
|
2
|
+
|
|
3
|
+
> **Audience:** Coding agents (`Pi`, `Claude Code`, `Codex`, `Cursor`, `Windsurf`, `OpenCode`) asked to set up **Huggy PR Agent** (`tripplen23/huggy-pr-agent@v1`) on a GitHub repository.
|
|
4
|
+
|
|
5
|
+
Follow these steps in order. Do not push directly to the repository's default branch if branch protection is enabled — create a setup branch and open a pull request instead.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Step 1 — Inspect the Target Repository
|
|
10
|
+
|
|
11
|
+
Inspect the repository root (read at most the top-level manifests and existing CI workflows) to determine four values:
|
|
12
|
+
|
|
13
|
+
1. **Runtime toolchain steps** needed *only* for the `command` job (when `@huggy` / `@pi` edits code and runs tests):
|
|
14
|
+
- Node.js (`package.json`): check `.nvmrc`, `engines.node`, `devEngines.runtime`, or existing `.github/workflows/*.yml` / `Dockerfile` for the exact Node version (`actions/setup-node@v4`).
|
|
15
|
+
- Go (`go.mod` or `*/go.mod`): check the `go` directive (`actions/setup-go@v5`).
|
|
16
|
+
- Rust (`Cargo.toml`): `dtolnay/rust-toolchain@stable`.
|
|
17
|
+
- Python (`pyproject.toml` / `requirements.txt`): `actions/setup-python@v5`.
|
|
18
|
+
- Swift / macOS Xcode (`Package.swift` / `*.xcodeproj`): set `runs-on: macos-15` on the `command` job while keeping `review` on `ubuntu-latest`.
|
|
19
|
+
2. **`setup_cmd`**: command that installs dependencies cleanly without mutating lockfiles (e.g. `corepack enable pnpm && pnpm install --frozen-lockfile`, `npm ci`, `uv sync --frozen`, or `""` for Go/Rust/Swift).
|
|
20
|
+
3. **`verify_cmd`**: fast deterministic check suite that must pass before `@huggy` is allowed to commit and push a fix (e.g. `pnpm typecheck && pnpm lint && pnpm test`, `cargo clippy && cargo test`, `go vet ./... && go test ./...`, `pytest`). Copy any required placeholder env vars (such as dummy `DATABASE_URL`) from existing CI workflows.
|
|
21
|
+
4. **`guarded_paths`**: space-separated paths `@huggy` must never modify automatically. Always include `.github`, plus lockfiles/manifests/migrations/deploy configs present in the repo (e.g. `".github Dockerfile package.json pnpm-lock.yaml migrations"`).
|
|
22
|
+
|
|
23
|
+
**Done when:** You have concrete, repository-verified values for toolchain steps, `setup_cmd`, `verify_cmd`, and `guarded_paths`.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Step 2 — Choose Provider & Verify GitHub Actions Secrets
|
|
28
|
+
|
|
29
|
+
Ask the user which model provider they want **only if** they have not already stated one and `gh secret list` shows none of the secrets below.
|
|
30
|
+
|
|
31
|
+
| Provider Choice | Workflow `with:` Inputs | Required GitHub Actions Secret(s) |
|
|
32
|
+
| :--- | :--- | :--- |
|
|
33
|
+
| **OpenCode Go (Default)** | `api_key: ${{ secrets.OPENCODE_GO_KEY }}` *(uses default `opencode-go/deepseek-v4.1-flash` + fallback `opencode-go/glm-5.3-flash`)* | `OPENCODE_GO_KEY` |
|
|
34
|
+
| **Google Vertex AI + Cross-Provider Fallback** | `model: google-vertex/gemini-4-carbon`<br>`fallback_model: opencode-go/deepseek-v4.1-flash`<br>`gcp_project: <PROJECT_ID>`<br>`gcp_location: global`<br>`gcp_credentials_json: ${{ secrets.GOOGLE_VERTEX_CREDENTIALS }}`<br>`api_key: ${{ secrets.OPENCODE_GO_KEY }}`<br>`max_parallel_bundles: "2"` | `GOOGLE_VERTEX_CREDENTIALS` *(Service Account JSON with `roles/aiplatform.user`)* + optional `OPENCODE_GO_KEY` |
|
|
35
|
+
| **OpenRouter** | `api_key: ${{ secrets.OPENROUTER_API_KEY }}`<br>`api_key_env: OPENROUTER_API_KEY`<br>`model: openrouter/anthropic/claude-sonnet-4` | `OPENROUTER_API_KEY` |
|
|
36
|
+
| **Anthropic** | `api_key: ${{ secrets.ANTHROPIC_API_KEY }}`<br>`api_key_env: ANTHROPIC_API_KEY`<br>`model: anthropic/claude-sonnet-4-5` | `ANTHROPIC_API_KEY` |
|
|
37
|
+
| **OpenAI** | `api_key: ${{ secrets.OPENAI_API_KEY }}`<br>`api_key_env: OPENAI_API_KEY`<br>`model: openai/gpt-5` | `OPENAI_API_KEY` |
|
|
38
|
+
|
|
39
|
+
Check existing repository secrets without reading values:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
gh secret list --repo OWNER/REPO
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- If `OPENCODE_GO_KEY` is missing and Pi is authenticated locally with `opencode-go`, offer or run (with user confirmation):
|
|
46
|
+
```bash
|
|
47
|
+
pi auth print-api-key --provider opencode-go | tr -d '\r\n' | gh secret set OPENCODE_GO_KEY --repo OWNER/REPO
|
|
48
|
+
```
|
|
49
|
+
- If using Google Vertex AI and `~/.config/gcloud/pi-vertex-sa.json` exists locally, set `GOOGLE_VERTEX_CREDENTIALS` without printing the file:
|
|
50
|
+
```bash
|
|
51
|
+
gh secret set GOOGLE_VERTEX_CREDENTIALS --repo OWNER/REPO < ~/.config/gcloud/pi-vertex-sa.json
|
|
52
|
+
```
|
|
53
|
+
- Otherwise, give the user the exact `gh secret set <SECRET_NAME>` one-liner to paste their key safely.
|
|
54
|
+
|
|
55
|
+
**Done when:** `gh secret list` shows the required secret(s), or the user has the exact `gh secret set` command ready.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Step 3 — Write `.github/workflows/huggy.yml`
|
|
60
|
+
|
|
61
|
+
Create `.github/workflows/huggy.yml` using the canonical template below, substituting the toolchain steps, `setup_cmd`, `verify_cmd`, `guarded_paths`, and provider inputs from Steps 1–2:
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
name: Huggy
|
|
65
|
+
on:
|
|
66
|
+
pull_request:
|
|
67
|
+
types: [opened, synchronize, reopened]
|
|
68
|
+
issue_comment:
|
|
69
|
+
types: [created]
|
|
70
|
+
pull_request_review_comment:
|
|
71
|
+
types: [created]
|
|
72
|
+
|
|
73
|
+
jobs:
|
|
74
|
+
review:
|
|
75
|
+
if: >-
|
|
76
|
+
github.event_name == 'pull_request' &&
|
|
77
|
+
github.event.pull_request.head.repo.full_name == github.repository
|
|
78
|
+
runs-on: ubuntu-latest
|
|
79
|
+
timeout-minutes: 60
|
|
80
|
+
permissions:
|
|
81
|
+
contents: read
|
|
82
|
+
pull-requests: write
|
|
83
|
+
concurrency:
|
|
84
|
+
group: huggy-review-${{ github.event.pull_request.number }}
|
|
85
|
+
cancel-in-progress: true
|
|
86
|
+
steps:
|
|
87
|
+
- uses: tripplen23/huggy-pr-agent@v1
|
|
88
|
+
with:
|
|
89
|
+
mode: review
|
|
90
|
+
api_key: ${{ secrets.OPENCODE_GO_KEY }}
|
|
91
|
+
|
|
92
|
+
command:
|
|
93
|
+
if: >-
|
|
94
|
+
(github.event_name == 'pull_request_review_comment' ||
|
|
95
|
+
(github.event_name == 'issue_comment' && github.event.issue.pull_request)) &&
|
|
96
|
+
github.event.comment.user.type != 'Bot' &&
|
|
97
|
+
(contains(github.event.comment.body, '@huggy') ||
|
|
98
|
+
contains(github.event.comment.body, '/huggy') ||
|
|
99
|
+
contains(github.event.comment.body, '@pi') ||
|
|
100
|
+
contains(github.event.comment.body, '/pi') ||
|
|
101
|
+
contains(github.event.comment.body, '/fix') ||
|
|
102
|
+
contains(github.event.comment.body, '/review') ||
|
|
103
|
+
contains(github.event.comment.body, '/describe') ||
|
|
104
|
+
contains(github.event.comment.body, '/improve') ||
|
|
105
|
+
contains(github.event.comment.body, '/ask'))
|
|
106
|
+
runs-on: ubuntu-latest
|
|
107
|
+
timeout-minutes: 90
|
|
108
|
+
permissions:
|
|
109
|
+
contents: write
|
|
110
|
+
pull-requests: write
|
|
111
|
+
issues: write
|
|
112
|
+
concurrency:
|
|
113
|
+
group: huggy-cmd-${{ github.event.issue.number || github.event.pull_request.number }}
|
|
114
|
+
cancel-in-progress: false
|
|
115
|
+
steps:
|
|
116
|
+
# Insert repo toolchain setup steps from Step 1 here (e.g. actions/setup-node@v4)
|
|
117
|
+
- uses: tripplen23/huggy-pr-agent@v1
|
|
118
|
+
with:
|
|
119
|
+
mode: comment
|
|
120
|
+
api_key: ${{ secrets.OPENCODE_GO_KEY }}
|
|
121
|
+
setup_cmd: "<FROM_STEP_1>"
|
|
122
|
+
verify_cmd: "<FROM_STEP_1>"
|
|
123
|
+
guarded_paths: "<FROM_STEP_1>"
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Critical Invariants (Do Not Alter)
|
|
127
|
+
|
|
128
|
+
1. Keep `review` job `timeout-minutes: 60` and `command` job `timeout-minutes: 90` so large 10k+ LOC multi-bundle PRs have headroom to finish and run the Fact-Check Judge pass.
|
|
129
|
+
2. Do **not** add `author_association` checks to the `command` job's `if:` expression — GitHub redacts concealed organization memberships (`MEMBER` → `CONTRIBUTOR`/`NONE`) in webhook payloads. `tripplen23/huggy-pr-agent@v1` verifies true repository `write`/`maintain`/`admin` permission upstream via `/collaborators/{username}/permission`.
|
|
130
|
+
3. If the repository has an `AGENTS.md` or `CLAUDE.md` on its default branch, `huggy-pr-agent` loads it automatically as the review and fix rubric (`rubric_file` defaults to `AGENTS.md` with automatic fallback to `CLAUDE.md`).
|
|
131
|
+
|
|
132
|
+
**Done when:** `.github/workflows/huggy.yml` parses cleanly (`python3 -c "import yaml; yaml.safe_load(open('.github/workflows/huggy.yml'))"` or `actionlint`) and contains zero leftover `<FROM_STEP_1>` placeholders (`! grep -q '<FROM_STEP_1>' .github/workflows/huggy.yml`).
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Step 4 — Verify & Report
|
|
137
|
+
|
|
138
|
+
1. Validate the workflow YAML locally.
|
|
139
|
+
2. Summarize the configured provider/models, `verify_cmd`, `guarded_paths`, and how the team can trigger Huggy on any PR:
|
|
140
|
+
- Automatic inline review on every PR push
|
|
141
|
+
- `@huggy <instruction>` (or `@pi <instruction>` / `/fix <instruction>`) on any diff line or PR comment to push a verified fix and auto-resolve the review thread
|
|
142
|
+
- `/describe`, `/improve`, `/ask <question>`, `/review`
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Binh Duc Nguyen
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,286 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<br />
|
|
4
|
+
|
|
5
|
+
<picture>
|
|
6
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/main/assets/banner-dark.svg" />
|
|
7
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/main/assets/banner-light.svg" />
|
|
8
|
+
<img alt="Huggy" src="https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/main/assets/banner-dark.svg" height="68" />
|
|
9
|
+
</picture>
|
|
10
|
+
|
|
11
|
+
<p><strong>Repository-aware pull request reviews and <code>@huggy</code> fixes, powered by Pi.</strong></p>
|
|
12
|
+
|
|
13
|
+
[](https://www.npmjs.com/package/huggy-pr-agent)
|
|
14
|
+
[](https://github.com/tripplen23/huggy-pr-agent/actions/workflows/ci.yml)
|
|
15
|
+
[](https://github.com/tripplen23/huggy-pr-agent/releases)
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
|
|
18
|
+
[Quick Start](#quick-start) · [Providers & Vertex AI](#model-providers--google-vertex-ai) · [Commands](#commands--capabilities) · [How It Works](#how-it-works) · [Configuration](#configuration--inputs) · [Agent Install Spec](https://github.com/tripplen23/huggy-pr-agent/blob/main/INSTALL.md)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Preview
|
|
25
|
+
|
|
26
|
+
While a review pipeline is running, Huggy shows a compact pixel-art status indicator, then replaces it with a clean summary and inline diff comments once finished:
|
|
27
|
+
|
|
28
|
+
<div align="center">
|
|
29
|
+
<img src="https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/main/assets/huggy-reviewing.svg" alt="Huggy reviewing animation" width="208" />
|
|
30
|
+
</div>
|
|
31
|
+
|
|
32
|
+
<br />
|
|
33
|
+
|
|
34
|
+
<div align="center">
|
|
35
|
+
<img src="https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/main/assets/inline-review-preview.png" alt="Huggy inline review on GitHub" width="96%" />
|
|
36
|
+
</div>
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Quick Start
|
|
41
|
+
|
|
42
|
+
### Option A — Install as a Pi Package or Cross-Harness Skill
|
|
43
|
+
|
|
44
|
+
Use Huggy locally inside your terminal **and** set up GitHub Actions in one command:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# In Pi (adds /huggy review, /huggy review deep, /huggy setup, /huggy sync, and huggy_prepare_diff):
|
|
48
|
+
pi install npm:huggy-pr-agent
|
|
49
|
+
|
|
50
|
+
# In Claude Code, Codex, Cursor, Windsurf, or OpenCode (Agent Skills standard):
|
|
51
|
+
npx skills add tripplen23/huggy-pr-agent
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Or paste this single prompt into **any** coding agent inside your repository:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
Read https://raw.githubusercontent.com/tripplen23/huggy-pr-agent/v1/INSTALL.md and set up Huggy PR Agent on this repository, tailoring setup_cmd, verify_cmd, and guarded_paths to our stack.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
### Option B — Manual 2-Minute GitHub Action Setup
|
|
63
|
+
|
|
64
|
+
#### Step 1 — Add Your Model API Key Secret
|
|
65
|
+
|
|
66
|
+
Using the GitHub CLI (`gh`), set your [OpenCode Go](https://opencode.ai/console/go), OpenRouter, Anthropic, or OpenAI key on the target repository:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# If you already connected opencode-go in Pi locally:
|
|
70
|
+
pi auth print-api-key --provider opencode-go | tr -d '\r\n' | gh secret set OPENCODE_GO_KEY --repo OWNER/REPO
|
|
71
|
+
|
|
72
|
+
# Or paste a key interactively:
|
|
73
|
+
gh secret set OPENCODE_GO_KEY --repo OWNER/REPO
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
#### Step 2 — Add `.github/workflows/huggy.yml`
|
|
77
|
+
|
|
78
|
+
Create `.github/workflows/huggy.yml` in your repository (see more ready-made templates in [`examples/`](examples/)):
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
name: Huggy
|
|
82
|
+
on:
|
|
83
|
+
pull_request:
|
|
84
|
+
types: [opened, synchronize, reopened]
|
|
85
|
+
issue_comment:
|
|
86
|
+
types: [created]
|
|
87
|
+
pull_request_review_comment:
|
|
88
|
+
types: [created]
|
|
89
|
+
|
|
90
|
+
jobs:
|
|
91
|
+
review:
|
|
92
|
+
if: >-
|
|
93
|
+
github.event_name == 'pull_request' &&
|
|
94
|
+
github.event.pull_request.head.repo.full_name == github.repository
|
|
95
|
+
runs-on: ubuntu-latest
|
|
96
|
+
timeout-minutes: 60
|
|
97
|
+
permissions:
|
|
98
|
+
contents: read
|
|
99
|
+
pull-requests: write
|
|
100
|
+
concurrency:
|
|
101
|
+
group: huggy-review-${{ github.event.pull_request.number }}
|
|
102
|
+
cancel-in-progress: true
|
|
103
|
+
steps:
|
|
104
|
+
- uses: tripplen23/huggy-pr-agent@v1
|
|
105
|
+
with:
|
|
106
|
+
mode: review
|
|
107
|
+
api_key: ${{ secrets.OPENCODE_GO_KEY }}
|
|
108
|
+
|
|
109
|
+
command:
|
|
110
|
+
if: >-
|
|
111
|
+
(github.event_name == 'pull_request_review_comment' ||
|
|
112
|
+
(github.event_name == 'issue_comment' && github.event.issue.pull_request)) &&
|
|
113
|
+
github.event.comment.user.type != 'Bot' &&
|
|
114
|
+
(contains(github.event.comment.body, '@huggy') ||
|
|
115
|
+
contains(github.event.comment.body, '/huggy') ||
|
|
116
|
+
contains(github.event.comment.body, '@pi') ||
|
|
117
|
+
contains(github.event.comment.body, '/pi') ||
|
|
118
|
+
contains(github.event.comment.body, '/fix') ||
|
|
119
|
+
contains(github.event.comment.body, '/review') ||
|
|
120
|
+
contains(github.event.comment.body, '/describe') ||
|
|
121
|
+
contains(github.event.comment.body, '/improve') ||
|
|
122
|
+
contains(github.event.comment.body, '/ask'))
|
|
123
|
+
runs-on: ubuntu-latest
|
|
124
|
+
timeout-minutes: 90
|
|
125
|
+
permissions:
|
|
126
|
+
contents: write
|
|
127
|
+
pull-requests: write
|
|
128
|
+
issues: write
|
|
129
|
+
concurrency:
|
|
130
|
+
group: huggy-cmd-${{ github.event.issue.number || github.event.pull_request.number }}
|
|
131
|
+
cancel-in-progress: false
|
|
132
|
+
steps:
|
|
133
|
+
- uses: tripplen23/huggy-pr-agent@v1
|
|
134
|
+
with:
|
|
135
|
+
mode: comment
|
|
136
|
+
api_key: ${{ secrets.OPENCODE_GO_KEY }}
|
|
137
|
+
# Replace with your repo's test command (e.g. "cargo test", "go test ./...", "pytest"):
|
|
138
|
+
verify_cmd: "pnpm typecheck && pnpm lint && pnpm test"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
> **macOS / Swift projects**: keep `review` on `ubuntu-latest` (fast & low-cost) and run `command` on `macos-15` so `swift test` gates `@huggy` commits — see [`examples/swift-macos.yml`](examples/swift-macos.yml).
|
|
142
|
+
|
|
143
|
+
#### Step 3 — Merge to Default Branch & Stay Up to Date
|
|
144
|
+
|
|
145
|
+
- **Automatic PR review (`pull_request`)** works immediately — including on the PR that adds `.github/workflows/huggy.yml`.
|
|
146
|
+
- **Interactive comment commands (`issue_comment`, `pull_request_review_comment`)** activate as soon as `.github/workflows/huggy.yml` lands on your default branch.
|
|
147
|
+
- **Staying in sync with upstream updates:**
|
|
148
|
+
- **Zero-click automatic updates:** Referencing `tripplen23/huggy-pr-agent@v1` automatically picks up every engine, Judge, and prompt improvement as soon as a new `v1.x` release ships.
|
|
149
|
+
- **1-click PR approval updates:** Prefer explicit version review before upgrading? Pin `uses: tripplen23/huggy-pr-agent@v1.8.0` and drop [`examples/dependabot.yml`](examples/dependabot.yml) into `.github/dependabot.yml` (or use Renovate) — GitHub opens a 1-click Merge PR with full release notes whenever a new version is published.
|
|
150
|
+
- **Local Pi package updates:** Run `pi update --extensions` (and `/huggy sync` inside any repo to refresh workflow templates).
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Model Providers & Google Vertex AI
|
|
155
|
+
|
|
156
|
+
By default, `huggy-pr-agent` uses `opencode-go/deepseek-v4.1-flash` with `opencode-go/glm-5.3-flash` as an automatic retry fallback. You can switch to **Google Cloud Vertex AI** (to spend GCP credits without recurring `gcloud` RAPT re-login prompts) or any provider supported by Pi:
|
|
157
|
+
|
|
158
|
+
### Using Google Vertex AI + Cross-Provider Fallback
|
|
159
|
+
|
|
160
|
+
1. Create a least-privilege GCP Service Account with `roles/aiplatform.user` only:
|
|
161
|
+
```bash
|
|
162
|
+
gcloud iam service-accounts create huggy-vertex --display-name="Huggy PR Agent" --project=YOUR_GCP_PROJECT --quiet
|
|
163
|
+
gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT --member="serviceAccount:huggy-vertex@YOUR_GCP_PROJECT.iam.gserviceaccount.com" --role="roles/aiplatform.user" --quiet
|
|
164
|
+
gcloud iam service-accounts keys create /tmp/huggy-vertex-sa.json --iam-account="huggy-vertex@YOUR_GCP_PROJECT.iam.gserviceaccount.com" --project=YOUR_GCP_PROJECT --quiet
|
|
165
|
+
gh secret set GOOGLE_VERTEX_CREDENTIALS --repo OWNER/REPO < /tmp/huggy-vertex-sa.json
|
|
166
|
+
rm -f /tmp/huggy-vertex-sa.json
|
|
167
|
+
```
|
|
168
|
+
*(Or authenticate keyless via `google-github-actions/auth@v2` Workload Identity Federation and omit `gcp_credentials_json`.)*
|
|
169
|
+
2. Pass `gcp_project`, `gcp_location: global`, and `gcp_credentials_json` — and optionally keep `api_key` (`OPENCODE_GO_KEY` / `OPENROUTER_API_KEY`) for **cross-provider failover** if Vertex hits quota (`429`) or regional downtime (`503`):
|
|
170
|
+
```yaml
|
|
171
|
+
- uses: tripplen23/huggy-pr-agent@v1
|
|
172
|
+
with:
|
|
173
|
+
mode: review
|
|
174
|
+
model: google-vertex/gemini-4-carbon
|
|
175
|
+
fallback_model: opencode-go/deepseek-v4.1-flash
|
|
176
|
+
gcp_project: your-gcp-project-id
|
|
177
|
+
gcp_location: global
|
|
178
|
+
gcp_credentials_json: ${{ secrets.GOOGLE_VERTEX_CREDENTIALS }}
|
|
179
|
+
api_key: ${{ secrets.OPENCODE_GO_KEY }}
|
|
180
|
+
max_parallel_bundles: "2"
|
|
181
|
+
```
|
|
182
|
+
See [`examples/google-vertex.yml`](examples/google-vertex.yml) for a full workflow file.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Why `huggy-pr-agent`?
|
|
187
|
+
|
|
188
|
+
Generic AI reviewers fail in two predictable ways: **single-call diff wrappers** cannot search callers outside the diff, while **unconstrained general agents** suffer from line-number drift, skipped files on large PRs, and slow token-burning loops.
|
|
189
|
+
|
|
190
|
+
`huggy-pr-agent` combines **deterministic pre/post-processing** with the **[Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)**:
|
|
191
|
+
|
|
192
|
+
| Capability | Single-Call Diff Bots | GitHub Copilot Review | **`huggy-pr-agent`** |
|
|
193
|
+
| :--- | :---: | :---: | :---: |
|
|
194
|
+
| Reads `AGENTS.md` / `CLAUDE.md` from **base** branch | ❌ | ⚠️ Partial | ✅ **Enforced & isolated** |
|
|
195
|
+
| Searches callers across the full repo (`rg` + `read`) | ❌ | ⚠️ Limited | ✅ **Full worktree access** |
|
|
196
|
+
| Scales to 10k+ LOC PRs via counterpart bundling + Judge | ❌ | ⚠️ Truncates | ✅ **Parallel + Fact-Checked** |
|
|
197
|
+
| Multi-line inline comments + 1-click `Commit suggestion` | ⚠️ | ✅ | ✅ **With syntax & hunk guard** |
|
|
198
|
+
| Remembers prior review threads & linked Issues | ❌ | ❌ | ✅ **Full `<pr_context>`** |
|
|
199
|
+
| Auto-resolves addressed threads on next push | ❌ | ❌ | ✅ **Via GraphQL** |
|
|
200
|
+
| `@huggy` / `@pi` edits code, runs tests & pushes commit | ❌ | 💰 Paid Enterprise | ✅ **Built-in (`verify_cmd`)** |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## How It Works
|
|
205
|
+
|
|
206
|
+
1. **Deterministic Context Preparation (`scripts/fetch_pr_context.py`)**
|
|
207
|
+
- Reads root and path-scoped `AGENTS.md` / `CLAUDE.md` / `REVIEW.md` / `.github/instructions/*.instructions.md` (`applyTo` globs) strictly from the **base** branch (`git show base:...`) so an untrusted PR cannot rewrite its own review checklist.
|
|
208
|
+
- Honors `.gitattributes` `linguist-generated` / `linguist-vendored` rules alongside lockfile/codegen filters (`pnpm-lock.yaml`, `Cargo.lock`, `*.pb.go`, `*.gen.*`, `*.min.js`, `*.snap`), builds an explicit `<review_files>` checklist, and prefixes every new-side diff line with `L<num>`.
|
|
209
|
+
- Fetches PR title, linked GitHub issues (`closingIssuesReferences`), description, commit messages, CI check status + failed GitHub Actions error excerpts (`statusCheckRollup`), and open/resolved review threads into `<pr_context>`.
|
|
210
|
+
2. **Smart Parallel Bundling & Review-Shaped Agent Pass (`scripts/run_review.py`)**
|
|
211
|
+
- Small/medium PRs run in a single fast pass; massive PRs (10k+ lines / dozens of files) are deterministically grouped into semantic counterpart bundles (`foo.ts` + `contracts/foo.ts` + `foo.test.ts`) and reviewed concurrently (`review_timeout_minutes: auto`), with an optional `review_depth: deep` (`/review deep`) dual-lens pass (Logic/Callers + Security/Spec).
|
|
212
|
+
- Uses review-shaped tool discipline (`--tools read,grep,find,ls --thinking high`): forms hypotheses from the diff first, batches `grep`/`find` caller discovery, then reads narrow `offset`/`limit` ranges.
|
|
213
|
+
3. **Confidence-Scored (`≥ 80`) Judge Pass & Two-Channel Output (`prompts/judge.md`, `scripts/post_review.py`)**
|
|
214
|
+
- An independent tool-free **Judge pass** scores every candidate `0–100` against ground-truth file lines and the `AGENTS.md` rubric, enforcing hard exclusions (no pre-existing code, no ungrounded speculation, no hallucinated rules) so only `confidence ≥ 80` defects reach inline diff threads.
|
|
215
|
+
- Under `review_profile: chill` (default), `High` and `Medium` defects are posted inline while `Low` nitpicks are collapsed inside `<details><summary>🧹 Nitpicks</summary>` in the sticky summary.
|
|
216
|
+
- Content-anchored sliding-window relocation repairs minor `1–5` line drift on `suggestion` blocks, disarms unsafe/unbalanced blocks, auto-resolves fixed threads, and replaces the live reviewing sprite with the static `Review by Huggy` summary.
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Commands & Capabilities
|
|
221
|
+
|
|
222
|
+
Comment any of these in the **PR conversation**, inside an **inline diff review thread**, or at the bottom of a **Quote reply** (`@pi` and `/pi` aliases work identically to `@huggy` and `/huggy`):
|
|
223
|
+
|
|
224
|
+
| Trigger / Command | Mode | What it does |
|
|
225
|
+
| :--- | :--- | :--- |
|
|
226
|
+
| **PR open / sync** *(or `/review`, `/review deep`)* | Read-only | Reviews `base...HEAD` against `AGENTS.md` / `CLAUDE.md` & path-scoped rules, posts verified `High` / `Medium` inline diff comments (`confidence ≥ 80`) with 1-click `suggestion` blocks, collapses `Low` nitpicks in the summary (`chill`), and auto-resolves fixed threads. (`/review deep` runs parallel Logic + Security specialist passes.) |
|
|
227
|
+
| **`/describe`** *(or `@huggy /describe`)* | Read-only | Generates a structured PR summary (`Type`, overview, and file-by-file walkthrough table) and updates the PR description. |
|
|
228
|
+
| **`/improve`** *(or `@huggy /improve`)* | Read-only | Scans the PR diff for self-contained code improvements and posts inline committable ` ```suggestion ` blocks. |
|
|
229
|
+
| **`/ask <question>`** *(or `@huggy /ask ...`)* | Read-only | Answers questions about the PR or surrounding codebase directly in the conversation or diff review thread, citing exact `path:line` references. |
|
|
230
|
+
| **`@huggy <instruction>`** *(or `@pi ...`, `/fix ...`)* | Write + Gate | Edits the PR branch to address the request, runs your `verify_cmd` test gate, blocks changes to `guarded_paths`, commits + pushes to the PR branch, and auto-resolves the diff thread. |
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Configuration & Inputs
|
|
235
|
+
|
|
236
|
+
| Input | Default | Description |
|
|
237
|
+
| :--- | :--- | :--- |
|
|
238
|
+
| `mode` | `auto` | `review`, `comment` (`fix`), or `auto` (`pull_request` → review, comment events → slash/`@huggy`/`@pi` commands). |
|
|
239
|
+
| `api_key` | `""` | API key for the model provider (optional when using Google Vertex AI). |
|
|
240
|
+
| `api_key_env` | `OPENCODE_API_KEY` | Environment variable Pi reads for `api_key` (`OPENCODE_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.). |
|
|
241
|
+
| `gcp_project` | `""` | Google Cloud project ID when using `google-vertex/*` models (auto-detected from `gcp_credentials_json` if omitted). |
|
|
242
|
+
| `gcp_location` | `global` | Google Cloud region or `global` when using `google-vertex/*` models. |
|
|
243
|
+
| `gcp_credentials_json` | `""` | Google Cloud Service Account JSON key for `google-vertex/*` models (omit when using Workload Identity Federation). |
|
|
244
|
+
| `model` | `opencode-go/deepseek-v4.1-flash` | Primary model ID passed to `pi --model`. |
|
|
245
|
+
| `fallback_model` | `opencode-go/glm-5.3-flash` | Fallback model tried automatically when `model` is overloaded (`429`/`5xx`/timeout) — supports cross-provider failover. |
|
|
246
|
+
| `thinking` | `high` | Thinking depth (`off`, `minimal`, `low`, `medium`, `high`). |
|
|
247
|
+
| `review_tools` | `read,grep,find,ls` | Built-in Pi tools enabled during read-only PR reviews. |
|
|
248
|
+
| `review_timeout_minutes` | `auto` | Review timeout budget in minutes, or `auto` to scale dynamically with PR size (24m on small PRs up to 50m on massive multi-bundle PRs). |
|
|
249
|
+
| `fix_timeout_minutes` | `25` | Per-attempt timeout in minutes for interactive `@huggy` / `@pi` / `/fix` commands (and `/describe`, `/improve`, `/ask`). |
|
|
250
|
+
| `max_parallel_bundles` | `3` | Max concurrent Pi workers when reviewing large multi-bundle PRs (> 10 files or > 1,800 changed lines). |
|
|
251
|
+
| `judge_pass` | `true` | Run an independent tool-free `0–100` confidence Judge pass (`≥ 80` inline cutoff) to drop false positives and duplicates. |
|
|
252
|
+
| `review_profile` | `chill` | `chill` posts `High`/`Medium` inline and collapses `Low` nitpicks inside the sticky summary; `assertive` posts all severities inline. |
|
|
253
|
+
| `review_depth` | `standard` | `standard` runs one unified pass per bundle; `deep` runs parallel Logic/Callers + Security/Spec passes merged via the Judge. |
|
|
254
|
+
| `skip_bots` | `true` | Skip automatic `pull_request` reviews when the PR author is a bot (e.g. Renovate, Dependabot). |
|
|
255
|
+
| `skip_drafts` | `false` | Skip automatic `pull_request` reviews while the PR is in draft state. |
|
|
256
|
+
| `rubric_file` | `AGENTS.md` | File read from the **base** branch as the system-prompt rubric (falls back to `CLAUDE.md` if absent). |
|
|
257
|
+
| `extra_instructions` | `""` | Extra repository-specific review/fix rules appended to the prompt. |
|
|
258
|
+
| `setup_cmd` | `""` | Shell command run in a secret-free step before a `@huggy` / `@pi` edit (e.g. `corepack enable pnpm && pnpm install --frozen-lockfile`). |
|
|
259
|
+
| `verify_cmd` | `""` | Shell command that must pass before a `@huggy` / `@pi` edit is committed and pushed. |
|
|
260
|
+
| `guarded_paths` | `.github .woodpecker Dockerfile ...` | Space-separated paths that `@huggy` / `@pi` is forbidden from staging or pushing. |
|
|
261
|
+
| `github_token` | `${{ github.token }}` | Token used to post reviews/comments and push fixes. |
|
|
262
|
+
|
|
263
|
+
### Customizing the Rubric per Repo
|
|
264
|
+
|
|
265
|
+
1. **Zero-config (`AGENTS.md` / `CLAUDE.md`)** — `huggy-pr-agent` automatically loads `AGENTS.md` (or `CLAUDE.md`) from your base branch into Pi's system prompt.
|
|
266
|
+
2. **Inline rules (`extra_instructions`)** — pass `extra_instructions:` in `with:` for quick repo-specific checks.
|
|
267
|
+
3. **Full prompt override** — commit `.github/pi-review-prompt.md` or `.github/pi-fix-prompt.md` to your default branch to replace the built-in prompt while keeping the inline diff publisher and thread sync.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Security Model
|
|
272
|
+
|
|
273
|
+
See [SECURITY.md](SECURITY.md) for the full threat model. Key invariants:
|
|
274
|
+
|
|
275
|
+
- **Write-permission verification** — interactive `@huggy` / `@pi` commands verify true repository `write`/`maintain`/`admin` access via `/repos/{owner}/{repo}/collaborators/{username}/permission` before checking out code or running `setup_cmd` (working seamlessly even when organization memberships are Private).
|
|
276
|
+
- **Base-branch rubric isolation** — `AGENTS.md` / `CLAUDE.md` and custom prompt files are read from `base` via `git show`, and Pi runs with `--no-context-files --no-approve`. A PR cannot poison its own review checklist or auto-load `.pi/` extensions.
|
|
277
|
+
- **Step-scoped credentials** — `github_token` is never exposed to the step that runs Pi or project tests; `api_key` and `gcp_credentials_json` are scoped strictly to the `pi` invocation step, shredded on exit, and redacted from all published output.
|
|
278
|
+
- **Git hook & path guards** — before committing a `@huggy` fix, `.git/hooks`, `core.fsmonitor`, and `core.hooksPath` are cleared, default branches (`main`/`master`) are refused, and any staged change touching `guarded_paths` aborts the push.
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## Contributing & License
|
|
283
|
+
|
|
284
|
+
Contributions, bug reports, and prompt improvements are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and testing instructions.
|
|
285
|
+
|
|
286
|
+
Licensed under the [MIT License](LICENSE).
|