Skip to main content
This guide takes you from a fresh BugViper instance to your first automated pull request review. You’ll install the GitHub App, configure your credentials, index a repository into the knowledge graph, and trigger the AI agent on a pull request — all in about fifteen minutes.
1

Install the GitHub App

BugViper needs a GitHub App to receive webhook events, clone your repositories, and post inline review comments on pull requests.Follow the GitHub App setup guide to create and install the app on your account or organization. At the end of that guide you’ll have three values ready: your App ID, the path to your private key .pem file, and your webhook secret.
If you’re testing locally, use ngrok to expose your BugViper instance to the internet so GitHub can deliver webhook events. Reserve a static domain in the ngrok dashboard for a stable webhook URL across restarts.
2

Configure environment variables

BugViper is configured through environment variables. Copy the example file and fill in your values:
cp .env.example .env
The three variables you must set before BugViper will start:
VariableWhat it does
NEO4J_URIConnection string to your Neo4j instance (e.g. bolt://localhost:7687)
OPENROUTER_API_KEYAPI key from openrouter.ai — used for LLM calls and embeddings
GITHUB_APP_IDThe numeric App ID shown in your GitHub App settings
See the full environment variable reference for every available option, including the Firebase service account path, review model selection, and optional observability settings.
3

Index a repository

With the API running, send a POST request to /api/v1/ingest/github to begin indexing. BugViper clones the repository, parses it with Tree-sitter across all 17 supported languages, and writes nodes and relationships into Neo4j.Replace YOUR_FIREBASE_TOKEN with a valid Firebase ID token from your authenticated session, and set owner and repo_name to match your target repository:
curl -X POST https://your-bugviper-instance/api/v1/ingest/github \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner": "acme-corp", "repo_name": "my-api", "branch": "main"}'
BugViper returns immediately with a job ID and a poll URL so you can track progress without blocking:
{
  "job_id": "a3f1c2d4-7e89-4b12-9f03-d8c21b5e6a70",
  "status": "pending",
  "poll_url": "/api/v1/ingest/jobs/a3f1c2d4-7e89-4b12-9f03-d8c21b5e6a70"
}
Poll the poll_url until status becomes completed. A typical mid-sized repository finishes in under two minutes.
Poll the /api/v1/ingest/jobs/{job_id} endpoint every few seconds until status reaches "completed". You can also monitor progress from the BugViper dashboard.
4

Trigger a review

Once a repository is indexed, BugViper can review any pull request in that repository. Open a pull request on GitHub and post the following comment:
@bugviper review
GitHub delivers the comment to BugViper via webhook. BugViper acknowledges with a 🚀 reaction on your comment, then the AI agent:
  1. Fetches the PR diff
  2. Explores the knowledge graph for context — call chains, class hierarchies, complexity scores
  3. Synthesizes findings into structured issues with confidence scores
  4. Posts each issue as an inline diff comment on the exact line where the problem was found
For a complete review of all files in the PR (not just changed lines), use:
@bugviper full review
The repository must be indexed before you trigger a review. If it isn’t, BugViper will post a comment explaining that you need to ingest the repository first and link you to the dashboard.

​
What happens next

After your first review, explore the other capabilities BugViper provides from the same indexed graph:

Code search

Search your codebase by symbol name, content, or natural language intent — with an inline peek viewer anchored to the exact source line.

Ask Agent

Ask natural language questions about your codebase and get answers with cited source files and code.