Journal

Why

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

Architecture

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

Design shift

The UI moved toward quieter documentation: fewer walls of text, clearer sections, and operational details kept 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.

Lessons

• Minimum GitHub App permissions: metadata, pull requests, issues, contents
• Webhook events matter: issue_comment versus pull_request_review_comment
• Skip empty PR reviews when there are no inline suggestions
• Optional range comments enable block-level feedback
• /apply needs diff block parsing that handles deletions
• /apply is intentionally permission-gated: authoring must be enabled and the commenter must have write or admin access
• Per-PR controls: /pause, /resume, /status
• Quota handling: temporary cooldown on auto-runs with manual override via /analyze
• Quiet prose replies for normal, blocked, paused, and no-op states

Next

Continue tightening reliability: better diff anchoring for inline suggestions and calmer defaults for high-traffic repos.

See Support for the troubleshooting runbook.