bluebear-io/baloo-bear

AI-powered code review agent for GitHub pull requests. Self-hosted GitHub App using PI. - bluebear-io/baloo-bear

37 stars · 4 forks

README

Baloo: self-hosted AI code review for GitHub pull requests

Baloo is an open source GitHub App for AI pull request review. It installs on your repositories, reads PR diffs and relevant project context, and posts actionable review comments that catch bugs, security issues, missing error handling, and repository guideline violations before humans review the code. Baloo is built for teams that want a self-hosted AI code review agent instead of a hosted SaaS reviewer. You run the service, control the GitHub App installation scope, and provide your own model API keys for Claude or Gemini. Website: BlueBear Security Why Baloo?

Catches what linters can't — logic errors, silent failures, security antipatterns, missing error handling Respects your conventions — reads AGENTS.md and CONTRIBUTING.md from your repo and enforces them Follows per-PR review briefs — when a PR includes ## Review guidance for Baloo, Baloo verifies those falsifiable, context-aware checks and cites them in findings Posts like a teammate — inline comments on specific lines, severity labels, approval/request-changes decisions Runs on every push — new commits get reviewed automatically, with discussion thread tracking across iterations Self-hosted & private — your code never leaves your infrastructure; bring your own API keys

Use Cases

AI code review for GitHub pull requests — review opened, reopened, synchronized, and ready-for-review PRs Security review assistance — flag injection risks, unsafe auth patterns, secret handling mistakes, and missing validation Repository guideline enforcement — apply project-specific rules from AGENTS.md and CONTRIBUTING.md Dependency update review — use Dependabot-aware prompts for dependency PRs Plan fidelity checks — compare an implementation against plan documents before approval Local review before opening a PR — run the same review pipeline against a local git diff

What It Looks Like When a PR is opened or updated, Baloo posts a review: 🐻 Baloo review completed in 45s. Found 2 issue(s): 0 critical, 1 high, 1 medium, 0 low.

Inline comments appear on the exact lines:

[HIGH] Security — src/auth.py:55 SQL query uses string concatenation instead of parameterized bindings. This is vulnerable to SQL injection. Recommendation: Use parameterized queries: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

Features

Feature Description

Agentic review Uses PI to read files, grep patterns, and explore the repo — not just the diff

Multi-provider Runs every agent through the configured Anthropic, Amazon Bedrock, Google, OpenAI, or Databricks AI Gateway provider

Severity routing CRITICAL/HIGH → request changes; MEDIUM → Checks annotations + collapsible PR digest; LOW → filtered

Guideline enforcement Reads repo-level AGENTS.md / CONTRIBUTING.md and flags violations

Per-PR review briefs Reads ## Review guidance for Baloo in the PR description and verifies falsifiable, diff-specific checks

Discussion tracking Follows up on existing threads, skips duplicates, detects addressed feedback

Fidelity analysis Optionally compares PR against design plan documents

Documentation drift Optionally asks authors to update mapped docs when implementation changes make them stale

FP reduction Optional second LLM pass to verify findings and drop false positives

Dashboard Optional PostgreSQL-backed review history UI with cost tracking

Dependabot-aware Specialized review logic for dependency update PRs

Local dry-run Run scripts/local_review.py against a local git diff — no GitHub webhook or posted comments

Baloo Compared

Need Baloo's fit

Hosted AI reviewer alternative Self-host Baloo as your own GitHub App and choose the model credentials

Static analysis complement Baloo reviews intent, behavior, edge cases, and repo-specific conventions that linters may not express

GitHub Copilot review complement Baloo runs automatically as an app on every PR update and can route findings to reviews or Checks

Security review workflow Baloo combines LLM review with severity routing, false-positive verification, and GitHub-native comments

Quick Start 1. Create a GitHub App Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App:

Webhook URL: Your public HTTPS endpoint (e.g. https://baloo.example.com/webhook) Permissions: Pull requests (read/write), Contents (read), Checks (read/write) Events: Pull request, Check run, Check suite (the last two power the Re-run button) Download the private key .pem file

2. Deploy with Docker git clone https://github.com/Blue-Bear-Security/baloo-bear.git cd baloo-bear cp .env.example .env

Edit .env with your GitHub App ID, private key path, webhook secret, and API keys

baloo/ ├── agent/ # PI runtime, prompts, structured output parsing ├── config/ # Settings (env + DB runtime overlay) ├── db/ # PostgreSQL models + migrations (optional) ├── dashboard/ # Review history UI (optional) ├── documentation/ # Documentation drift analysis (optional) ├── fidelity/ # Plan-vs-implementation analysis (optional) ├── github/ # Webhooks, API client, auth, Checks API └── processor/ # Findings filter, severity routing, decisions, FP verification

Configuration Settings are configured via environment variables; allowlisted agent knobs can also be overridden at runtime when DATABASE_ENABLED=true. Key variables:

Variable Default Description

GITHUB_APP_ID — Numeric GitHub App ID

GITHUB_PRIVATE_KEY — Path to .pem file or inline PEM

GITHUB_WEBHOOK_SECRET — Webhook signature secret

ANTHROPIC_API_KEY — Anthropic API key

GEMINI_API_KEY — Google Gemini API key (when using the Google provider)

AGENT_PROVIDER anthropic LLM provider for all agents: anthropic, google, openai, amazon-bedrock, databricks

AGENT_MODEL sonnet Model short name: flash, haiku, sonnet, gemini-pro, opus

REVIEW_AUTO_APPROVE false Auto-approve PRs with no blocking findings (opt-in)

REVIEW_MIN_SEVERITY MEDIUM Minimum severity to post

FP_VERIFICATION_ENABLED true Enable LLM false-positive verification

DATABASE_ENABLED false Enable PostgreSQL review history

DASHBOARD_ENABLED true Enable review dashboard UI (needs DATABASE_ENABLED + credentials)

REPO_CACHE_ENABLED true Check out the PR repo so the agent reads real code, not just the diff

REPO_SANDBOX_MODE bwrap Sandbox the agent subprocess to the review worktree (falls back to off if unavailable)

FIDELITY_ENABLED true Compare PRs against plan docs

DOCUMENTATION_DRIFT_ENABLED false Enable PR-time documentation drift checks

Full reference: docs/configuration.md Documentation 📖 Full documentation — Feature guides, configuration reference, and more Feature guides:

How to Get the Most Out of Baloo — Conventions, per-PR review briefs, high-signal workflows Review Agent — How the agentic review works Guidelines Enforcement — Repo convention checking Fidelity Analysis — Plan-vs-implementation scoring Documentation Drift — PR-time stale docs detection Models — Supported providers, models, and tiers Severity Routing — How findings reach developers Discussion Tracking — Thread follow-ups across iterations FP Verification — False-positive reduction Dashboard — Review history UI

Development uv sync && npm install # install deps uv run python main.py # run locally uv run pytest # test uv run ruff check baloo # lint uv run black --check baloo # format check When changing Python dependencies, regenerate the hash-pinned production requirements before committing: uv export --frozen --no-dev --no-emit-project --no-header --output-file requirements-prod.txt CI checks this file against uv export, and the Docker image installs production dependencies from it. Local review (dry run) You can run the same review pipeline against your working tree before opening a PR. The script builds a synthetic pull request from a git diff (base...head), loads AGENTS.md / CONTRIBUTING.md from the head ref when present, and prints findings to stdout — nothing is posted to GitHub. Requires the same LLM credentials as production (for example ANTHROPIC_API_KEY or GEMINI_API_KEY in your environment). uv run python scripts/local_review.py uv run python scripts/local_review.py --base origin/main --head HEAD uv run python scripts/local_review.py --json uv run python scripts/local_review.py --fail-on-blocking # exit 1 if CRITICAL/HIGH findings

Review another clone while cwd is baloo-bear (e.g. uv --directory this repo):

Issues & Bug Reports: GitHub Issues Feature Requests: GitHub Issues Questions: Open a GitHub Discussion or file an issue

Contributing Contributions are welcome! See CONTRIBUTING.md for workflow and conventions, and AGENTS.md for AI-agent-specific guidance. Security Please read SECURITY.md before reporting vulnerabilities. License MIT — see LICENSE.

source