Getting Started

VGV Bot is a GitHub App. Once it’s installed on a repository you can hand off work the same way you’d hand it off to a teammate: assign an issue, mention it in a comment, or request a PR review.

---

Step 1 — Install the GitHub App

Install the bot from its public page:

https://github.com/apps/very-good-code-bot

1. Click Install (or Configure if it’s already in your org).
2. Pick the org or personal account that owns the repository.
3. Choose Only select repositories and add the repos you want the bot on. You can add more later.
4. Approve the install.

The bot can now receive events from those repos.

Note

The bot needs Issues: Read & Write and Metadata: Read permissions, and subscribes to Issue comment, Pull request review, and Push events. GitHub shows the full list during installation.

---

Step 2 — Configure the bot in the dashboard

Open https://vgv-ai-bot.web.app and sign in with your GitHub account.

Access is gated by an allowlist

If you sign in and see “access denied”, ask whoever runs the bot to add your GitHub user or your whole org to the allowlist.

After sign-in you’ll see every org and repository the bot is installed on (filtered to what your GitHub account can see). Click the gear icon next to the repo you just installed the bot on.

Intent analyzer

Picks the LLM that classifies what you’re asking for when you mention the bot. Choose a provider (Anthropic or Gemini), supply an API key, and pick a model. A small, fast model works well here — this step only categorizes intent.

Task dispatcher

Picks the agent that does the actual coding work.

Option	Description
Cloud Run + Claude	Claude Code running on Google Cloud Run.
Cloud Run + Gemini	Gemini CLI running on Google Cloud Run.
Cloud Run + opencode	opencode running on Google Cloud Run. Pick a sub-provider (go, zen, big-pickle, anthropic, or gemini) — go/zen use opencode’s paid plans billed through opencode, big-pickle is opencode’s free model and ignores the API key field, and anthropic/gemini are bring-your-own-key. The gemini sub-provider exposes your key to opencode as both GEMINI_API_KEY and GOOGLE_GENERATIVE_AI_API_KEY.
Managed agent	Hand off to a hosted agent service.

Each option asks for an API key and a model identifier.

SDKs

Optional. List development SDKs to install before the coding agent starts. Currently flutter is supported — pick a version and the bot installs Flutter (and Dart) into the workspace so the agent can call flutter analyze, dart format, and so on.

Repository hooks

Shell commands the bot runs after the coding agent finishes but before it pushes. Applies to the “open PR” and “address review” flows only.

Each hook is a name + command pair.

If a hook exits non-zero, the bot hands the output back to the coding agent to fix it and re-runs the hook. After 3 total attempts the task fails and the hook name and error are posted as a PR comment.

A common setup with the Flutter SDK:

Name	Command
format	dart format --set-exit-if-changed .
analyze	flutter analyze
test	flutter test

Claude plugins

If you’re using the Claude dispatcher, you can preload Claude Code plugins — bundles of skills and tool hooks the agent loads at startup. Add the marketplace identifiers and plugin IDs you want. Ignored when the dispatcher is Gemini.

Interaction users

By default only repo admins and maintainers can trigger the bot. Add specific GitHub logins here to let contributors or teammates without admin rights also mention the bot. Matching is case-insensitive.

Auto-update PRs

Off by default. When enabled, every push to the base branch fans out to every open PR targeting it and brings the head branch back in sync. See Auto-Update PRs for the full behavior.

Auto-merge PRs

Off by default. When enabled, the bot auto-merges clean PRs from allow-listed automation authors (Dependabot by default) once their checks pass. See Auto-Merge PRs for the full behavior.

Hit Save when done. Changes can take up to 5 minutes to reach in-flight tasks; new tasks pick them up immediately.

Org-level defaults

If you’re a GitHub org admin, the dashboard sidebar shows Org settings. Config set here applies to every repo in the org that doesn’t have its own override — the easiest way to roll out a default across an org without touching each repo individually.

---

Step 3 — (Optional) Per-branch overrides with very_good_bot.yaml

For settings that vary per branch — SDK version or Claude plugins — add very_good_bot.yaml at the root of your repository:

sdks:
  - sdk: flutter
    version: 3.41.2

claude:
  marketplaces:
    - VeryGoodOpenSource/very_good_claude_marketplace
  plugins:
    - very-good-ai-flutter-plugin@very_good_claude_marketplace

The YAML is read fresh from the cloned branch on every task. When a top-level section (sdks or claude) is present it replaces the dashboard value for that section on that branch. Sections you don’t include fall back to the dashboard config.

API keys, dispatcher choice, the interaction-user allowlist, and auto-update settings are intentionally not in the YAML — those stay in the dashboard.

---

Step 4 — Interact with the bot

See Interacting with the Bot for the full guide on assigning issues, writing mentions, using slash commands, and requesting reviews.

---

Troubleshooting

“This repository has not been configured yet.” A repo or org admin needs to open the dashboard and save a config for that repo or its org.

The bot didn’t react when I mentioned it.

• Make sure the comment starts with @vgvbot.
• Confirm you’re a repo admin/maintainer, or that an admin added your login to the interaction users list.
• Confirm the GitHub App is installed on the repo (check the org’s installed-apps page).

The bot opened a duplicate PR. The bot deduplicates ongoing tasks per issue/PR per intent. If you assigned the bot and also mentioned it in a comment, those are two separate triggers and both may run. Pick one.