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

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

Baloo Compared

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

docker compose up --build

3. Install the App

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

📖 Full setup guide: docs/getting-started.md

Architecture

┌──────────────┐     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/      # Environment-based settings
├── 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

All settings are environment variables. Key ones:

Full reference: docs/configuration.md

Documentation

📖 Full documentation — Feature guides, configuration reference, and more

Feature guides:

• 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 models and fallback
• 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):
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.

FAQ

Is Baloo self-hosted?

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

Does Baloo send code to a hosted Baloo service?

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.

Which models does Baloo support?

Baloo supports Claude models through Anthropic and Gemini models through Google, including fallback model configuration. See docs/features/models.md.

Is Baloo a replacement for CodeQL, Semgrep, Ruff, or other static analysis tools?

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.

Can I try Baloo without posting comments to GitHub?

Yes. Use scripts/local_review.py to run a dry review against a local git diff.

Support

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