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

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

• Catches what linters can't — logic errors, silent failures, security antipatterns, missing error handling

• Respects your conventions — readsAGENTS.md andCONTRIBUTING.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 fromAGENTS.md andCONTRIBUTING.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,))

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

📖 Get sharper reviews: 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:

Full reference: docs/configuration.md

📖 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

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

See 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 and 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 to run a dry review against a local git diff.

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

Contributions are welcome! See CONTRIBUTING.md for workflow and conventions, and AGENTS.md for AI-agent-specific guidance.

Please read SECURITY.md before reporting vulnerabilities.

MIT — see LICENSE.