Journal

The Vision

The goal is practical: ship an ergonomic Ruby client for Gemini, then use it to power a PR reviewer (HarperBot) that teams can install once and use across repos.

Architecture

HarperBot runs in two modes: a legacy GitHub Actions workflow and a recommended webhook deployment (Vercel). Webhook mode uses GitHub App installation tokens (scoped, short-lived) and the google-genai client for Gemini requests.

Design Shift

The UI evolved into this "arcade" style to keep docs approachable: fewer walls of text, more scannable cards and checklists. Deeper operational details live in the Support runbook.

Model Choice

Defaulting to Gemini Flash keeps reviews fast and cost-aware. For large diffs, the system can fall back to a more capable model when needed.

Operational learnings (real PR tests)

• Minimum GitHub App permissions: Metadata + Pull requests + Issues + Contents
• Webhook events matter: Issue comment vs Pull request review comment
• Always create a PR review entry, even when there are no inline suggestions
• Optional range comments: enable "comment on lines +X to +Y" for block feedback
• /apply needs robust parsing (simplified diff blocks + deletions)
• Per-PR controls: /pause, /resume, /status
• Quota handling: temporary cooldown on auto-runs with manual override via /analyze

Commands

/analyze        (/analyze --force-review)
/apply
/pause   /resume   /status
/merge   /squash   /rebase

Commands work from Conversation comments, and (when enabled) inline file comments.

Next

Continue tightening reliability: better diff anchoring for inline suggestions, clearer notices when a command is ignored, and smoother "quiet mode" defaults for high-traffic repos.

See Support for the L2 troubleshooting runbook.