CattyBug

CattyBug is a private GitHub App that reviews pull requests with OpenRouter models. It listens to GitHub webhooks, reads PR diffs, posts review summaries and inline comments, and tracks usage so organizations can control monthly AI spend.

What It Is For

• Automated pull request review for GitHub repositories.
• Inline findings with confidence filtering and duplicate detection.
• Review summaries grouped by file, with code score and flow overview.
• Model policy and budget controls for organizations, repositories, and individual users.
• Per-user monthly spend limits, attributed to the GitHub login that triggers each review.
• Admin dashboard for runs, usage, budgets, per-user limits, model settings, audit logs, and repository installation.

Tech Stack

• Backend: Node.js, TypeScript, Fastify
• Web UI: React, Vite, TanStack Router, TanStack Query
• 3D login visual: Three.js with a .glb model
• AI provider: OpenRouter
• GitHub integration: GitHub App webhooks and installation tokens
• Persistence: Postgres in production, JSON store fallback for local development
• Local stack: Docker Compose with API, web UI, and Postgres

Project Structure

src/             Fastify API, GitHub webhook handling, review logic, persistence
apps/web/        React admin dashboard
migrations/      Postgres migrations
docs/            Development, deployment, and requirement notes
docker/          Dockerfiles for local services

Setup

Copy the environment file:

cp .env.example .env

For local dashboard development, Docker supplies safe placeholder values. Real PR reviews need real GitHub App and OpenRouter credentials:

GITHUB_APP_ID
GITHUB_PRIVATE_KEY
GITHUB_WEBHOOK_SECRET
OPENROUTER_API_KEY
DATABASE_URL
CATTYBUG_ADMIN_TOKEN
CATTYBUG_WEB_ORIGIN

For GitHub OAuth login, also set:

GITHUB_OAUTH_CLIENT_ID
GITHUB_OAUTH_CLIENT_SECRET
GITHUB_OAUTH_CALLBACK_URL
CATTYBUG_SESSION_SECRET
CATTYBUG_GITHUB_ALLOWED_ORGS

Run Locally

Docker Compose:

npm run dev:docker

Open:

• Web UI: http://localhost:5174
• API: http://localhost:3000
• Postgres: localhost:5432

Default local admin token:

cattybug-local-admin

Compose supplies placeholder secrets so the dashboard can boot locally, but real GitHub PR reviews require real GitHub App and OpenRouter values in .env.

Direct Node workflow:

npm install   # installs all workspaces (API, apps/web, packages/catty-agent)
npm run dev

This repo is an npm workspace: a single npm install at the root sets up the API, the web dashboard (apps/web), and the review agent (packages/catty-agent).

Run migrations when using Postgres directly:

npm run db:migrate

CLI

CattyBug includes a CLI for manually kicking off PR reviews from your terminal, similar to a review bot command:

npm run cli -- review owner/repo#123 --effort quick
npm run cli -- review https://github.com/owner/repo/pull/123 --effort deep
npm run cli -- doctor

The npm package name is cattycall. After publishing, install it globally with:

npm install -g cattycall
cattycall login --provider https://cattybug.your-org.com
cattycall doctor
cattycall review owner/repo#123 --effort standard

The package also exposes cattybug as a command alias:

cattybug review owner/repo#123 --effort standard

The recommended team setup is one shared CattyBug provider/backend for the org. Team members authenticate with GitHub OAuth through cattycall login, and the backend uses the single configured GitHub App and OpenRouter provider to create Check Runs and PR reviews. Team members do not need local GitHub App private keys or OpenRouter API keys.

For local development only, the CLI can still run direct mode with the same environment values as the server. If DATABASE_URL is unset, it writes to the JSON store fallback at CATTYBUG_STORE_PATH.

GitHub App Setup

Create a GitHub App with:

• Webhook URL: https://YOUR_API_DOMAIN/webhooks/github
• Setup URL: https://YOUR_WEB_DOMAIN/install
• Webhook content type: application/json
• Events: pull_request, issue_comment, check_run, installation, installation_repositories
• Permissions: Metadata read, Contents read, Pull requests read/write, Checks read/write, Issues read/write

Generate a private key, set it in GITHUB_PRIVATE_KEY, then install the app on target repositories.

Repository Config

Repositories can override review behavior with .cattybug.yml. If no slash command or cattybug:* label sets the effort, CattyBug now chooses effort from review size: quick for small PRs (≤5 files and ≤250 changed lines), standard for medium PRs (≤20 files and ≤2,000 changed lines), and deep for larger PRs. defaultEffort is the fallback when size is unavailable:

version: 1
reviews:
  autoRun: true
  defaultEffort: standard
  draftPRs: false
  maxFiles: 200
  maxChanges: 20000
budget:
  repoMonthlyUsd: 100
models:
  allowed:
    - deepseek/deepseek-v4-flash
agent:
  engine: openrouter # or "catty-agent" for agentic review on a full checkout
  toolsEnabled: true
  maxToolCalls: 3

Review Engines

CattyBug can run reviews with one of two engines, selected by agent.engine in .cattybug.yml (or the CATTYBUG_REVIEW_ENGINE env default):

• openrouter (default): a direct OpenRouter chat loop with a small set of patch-inspection tools. Fast, sees the diff plus bounded file context.
• catty-agent: spawns the vendored coding agent (packages/catty-agent, a fork of pi) as a subprocess in a fresh checkout of the PR head. The agent explores the whole repository with read-only tools (read/grep/find/ls), then emits the same JSON review report. It runs with --no-approve --no-extensions --no-skills and no bash tool, so PR-authored content cannot execute code in the reviewer. The GitHub token is injected via a git http header (not the clone URL or argv) and the OpenRouter key via env, so neither lands in process argv or the checkout's .git/config.

The agent engine requires the agent to be built first (its deps are already installed by the root npm install):

npm run build:agent

Override per run/host with CATTYBUG_AGENT_CLI (path to the agent cli.js) and CATTYBUG_AGENT_TIMEOUT_MS (default 240000).

Build And Test

npm run typecheck
npm test
npm run build

Production:

npm run build
npm start

More details are in docs/local-development.md, docs/railway-deployment.md, and docs/project-structure.md.