Journal

The Vision

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

Architecture

Vesper 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 moved toward quieter docs: 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.

Operational learnings (real PR tests)

• Minimum GitHub App permissions: Metadata + Pull requests + Issues + Contents
• Webhook events matter: Issue comment vs Pull request review comment
• Skip empty PR reviews 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)
• /apply is intentionally permission-gated: authoring must be enabled and the commenter must have write/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

Commands

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

Commands work from Conversation comments, and (when enabled) inline file comments. Write-capable commands still depend on repository permissions and feature flags.

Next

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

See Support for the L2 troubleshooting runbook.