# Show HN: Baloo, self-hosted AI code review for GitHub

> Source: <https://github.com/bluebear-io/baloo-bear>
> Published: 2026-10-04 21:01:45+00:00

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](https://www.bluebear.io)

- **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

- **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

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,))`

| Feature | Description | 
|---|---|
| **Agentic review** | Uses [PI](https://github.com/mariozechner/pi-coding-agent) 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`](https://github.com/bluebear-io/baloo-bear/blob/main/scripts/local_review.py) against a local git diff — no GitHub webhook or posted comments | 

| 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 | 

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

```
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
docker compose up --build
```

Install the GitHub App on your repositories. Open a PR — Baloo will review it automatically.

📖 **Full setup guide**: [docs/getting-started.md](https://github.com/bluebear-io/baloo-bear/blob/main/docs/getting-started.md)

📖 **Get sharper reviews**: [docs/how-to-get-the-most.md](https://github.com/bluebear-io/baloo-bear/blob/main/docs/how-to-get-the-most.md) — conventions, per-PR review briefs, and workflows that turn Baloo into a context-aware reviewer

```
┌──────────────┐     webhook      ┌───────────────────┐
│   GitHub     │ ───────────────→ │   FastAPI         │
│   (PR event) │                  │   webhook_handler │
└──────────────┘                  └────────┬──────────┘
                                           │
                                  ┌────────▼──────────┐
                                  │   PI Agent (RPC)  │
                                  │   read / grep /   │
                                  │   find / ls       │
                                  └────────┬──────────┘
                                           │
                                  ┌────────▼──────────┐
                                  │   Processor       │
                                  │   filter → route  │
                                  │   → decide        │
                                  └────────┬──────────┘
                                           │
                              ┌────────────┼────────────┐
                              ▼            ▼            ▼
                        ┌──────────┐ ┌──────────┐ ┌──────────┐
                        │ Review   │ │ Checks   │ │ Dashboard│
                        │ comments │ │ API      │ │ (opt.)   │
                        └──────────┘ └──────────┘ └──────────┘
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
```

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](https://github.com/bluebear-io/baloo-bear/blob/main/docs/configuration.md)

📖 **[Full documentation](https://github.com/bluebear-io/baloo-bear/blob/main/docs/README.md)** — Feature guides, configuration reference, and more

Feature guides:

- [How to Get the Most Out of Baloo](https://github.com/bluebear-io/baloo-bear/blob/main/docs/how-to-get-the-most.md) — Conventions, per-PR review briefs, high-signal workflows
- [Review Agent](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/review-agent.md) — How the agentic review works
- [Guidelines Enforcement](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/guidelines.md) — Repo convention checking
- [Fidelity Analysis](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/fidelity.md) — Plan-vs-implementation scoring
- [Documentation Drift](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/documentation-drift.md) — PR-time stale docs detection
- [Models](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/models.md) — Supported providers, models, and tiers
- [Severity Routing](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/severity-routing.md) — How findings reach developers
- [Discussion Tracking](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/discussions.md) — Thread follow-ups across iterations
- [FP Verification](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/fp-verification.md) — False-positive reduction
- [Dashboard](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/dashboard.md) — Review history UI

```
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.

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):
uv run python scripts/local_review.py --git-workdir /path/to/other-repo --base origin/main --head HEAD
```

See [docs/development.md](https://github.com/bluebear-io/baloo-bear/blob/main/docs/development.md) for the full contributor guide.

Yes. Baloo runs as your own service and GitHub App. You control deployment, repository installation scope, database persistence, and model credentials.

No. Baloo does not require a Baloo-hosted backend. The running service reads repository content through your GitHub App installation and sends review context to the LLM provider you configure.

Baloo supports Anthropic, Amazon Bedrock, Google, OpenAI, and Databricks AI Gateway providers. The selected provider applies to every agent. See [docs/features/models.md](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/models.md) and [docs/features/databricks.md](https://github.com/bluebear-io/baloo-bear/blob/main/docs/features/databricks.md).

No. Baloo is a review agent that complements static analysis. Keep deterministic scanners for known patterns and use Baloo for reasoning-heavy findings, project conventions, and PR-level review context.

Yes. Use [`scripts/local_review.py`](https://github.com/bluebear-io/baloo-bear/blob/main/scripts/local_review.py) to run a dry review against a local git diff.

- **Issues & Bug Reports** :[GitHub Issues](https://github.com/Blue-Bear-Security/baloo-bear/issues)
- **Feature Requests** :[GitHub Issues](https://github.com/Blue-Bear-Security/baloo-bear/issues)
- **Questions** : Open a[GitHub Discussion](https://github.com/Blue-Bear-Security/baloo-bear/discussions) or file an issue

Contributions are welcome! See [CONTRIBUTING.md](https://github.com/bluebear-io/baloo-bear/blob/main/CONTRIBUTING.md) for workflow and conventions, and [AGENTS.md](https://github.com/bluebear-io/baloo-bear/blob/main/AGENTS.md) for AI-agent-specific guidance.

Please read [SECURITY.md](https://github.com/bluebear-io/baloo-bear/blob/main/SECURITY.md) before reporting vulnerabilities.

MIT — see [LICENSE](https://github.com/bluebear-io/baloo-bear/blob/main/LICENSE).