mole

AI-powered PR reviews + developer growth. Self-hosted. One binary or one container.

Digs deep into code, elevates those who write it.

What is Mole · Prerequisites · Install · Setup · Usage · How It Works · Context Files · Dashboard · Config Reference · Stack · Docker · Build

Mole (the animal that digs deep, finding what others miss) is an open-source, self-hosted AI code review and developer growth platform. Install it as a GitHub App, point it at your repos, and every PR gets an automated review powered by Claude — with personality, formal issue taxonomy, quality scoring, and growth tracking.

The full loop, self-hosted:

Review PR → Classify issues → Track patterns → Surface insights → Grow developers

• Standard reviews — triggered automatically on PR open, or manually with /mole review
• Deep reviews — use Claude Opus for thorough analysis with /mole deep-review
• Ignore PRs — skip reviews with /mole ignore
• CLI reviews — review any PR from your terminal with mole review owner/repo#123
• Bot personality — 3 modes: mole (playful), formal (professional), minimal (terse)
• Issue taxonomy — Security, Bugs, Smells, Architecture, Performance, Style (with subcategories)
• Quality score — 0-100 per PR
• Architecture validation — layer enforcement rules via AST analysis
• Security scanner — AST-based detection of common vulnerabilities
• Mermaid diagrams — sequence and class diagrams in deep reviews

• Individual view — issue heat map, score trends, streaks, badges
• Team view — issue distribution, quality trends, training suggestions
• Module view — health score, tech debt tracking, grouped by repository
• Costs view — Claude API usage and estimated costs per model (admin only)
• Gamification — streaks, badges, achievements
• About page — application info and version
• Role-based access — Dev, Tech Lead, Manager, Admin
• i18n — Portuguese (default) and English, switchable via flag selector

• GitHub App — you create one in your GitHub account (Mole runs as a GitHub App)
• MySQL 8.0+ — stores reviews, issues, metrics
• Valkey 7.0+ (or Redis) — job queue and webhook dedup
• Anthropic API key — for Claude-powered reviews

curl -fsSL https://getkaze.dev/mole/install.sh | sudo bash

Or download the binary from Releases and place it in your PATH.

docker pull ghcr.io/getkaze/mole:main

See Docker for full usage.

Go to github.com/settings/apps/new and create a new app:

Download the private key and note the App ID.

cp mole.yaml.example mole.yaml

Fill in your GitHub App ID, private key path, webhook secret, Anthropic API key, and database credentials. All values can be overridden with MOLE_ prefixed environment variables.

mole serve

Mole starts an HTTP server (default port 8080), a worker pool, and a metrics aggregator. Database migrations run automatically on startup.

# Start the server + workers + dashboard
mole serve

# Run database migrations
mole migrate

# Check connectivity to MySQL, Valkey, and GitHub
mole health

# Scan a repo and generate .mole/ context files
mole init /path/to/repo

# Review a PR from the CLI
mole review owner/repo#123
mole review owner/repo#123 --deep
mole review owner/repo#123 --install-id 12345

# Sync reactions, recalculate scores, and update metrics
mole sync

# Manage dashboard roles
mole admin set-role <user> <role>
mole admin list

# Update to latest version
mole update

# Version
mole version

Comment on any PR to trigger Mole:

PRs are also reviewed automatically when opened.

Developers can react to Mole's inline comments with 👍 (confirm issue) or 👎 (false positive). Mole syncs reactions automatically every hour, but you can force an immediate sync:

mole sync

This command:

1. Polls GitHub for reactions on recent review comments
2. Marks issues as confirmed or false_positive based on reactions
3. Recalculates PR scores excluding false positives
4. Updates developer and module metrics (false positives are no longer counted)

GitHub webhook ──> POST /webhook ──> Valkey queue ──> Worker pool
                   (signature check)   (dedup)        │
                                                      ├── Fetch PR diff (GitHub API)
                                                      ├── Load .mole/ context + config
                                                      ├── Run architecture validation (AST)
                                                      ├── Run security scanner (AST)
                                                      ├── Call Claude API (review + taxonomy)
                                                      ├── Calculate quality score
                                                      ├── Apply personality + severity filter
                                                      ├── Validate line numbers against diff
                                                      ├── Post review (summary + inline comments)
                                                      ├── Save review + issues to MySQL
                                                      └── Aggregator computes metrics (hourly)

Create a .mole/ directory in your repository root:

.mole/
  config.yaml        # personality, severity filter, architecture rules
  architecture.md    # system design, package structure
  conventions.md     # naming, error handling, patterns
  decisions.md       # ADRs, tech choices

Markdown files are loaded automatically and included in the review prompt. config.yaml controls Mole's behavior for this repo.

Generate context files automatically:

mole init /path/to/repo

Mole includes an optional HTMX-powered dashboard for developer growth tracking. Enable it by adding dashboard config to mole.yaml:

dashboard:
  github_client_id: "your-oauth-app-client-id"
  github_client_secret: "your-oauth-app-client-secret"
  session_secret: "a-random-32-char-secret"
  base_url: "http://localhost:8080"
  # Restrict access to members of a specific GitHub org (recommended)
  allowed_org: "your-github-org"

Create a GitHub OAuth App (separate from the GitHub App) at github.com/settings/developers with callback URL http://your-server/auth/callback.

By default, any authenticated GitHub user can log in. Set allowed_org to restrict access to members of a specific GitHub organization — only users who belong to that org will be allowed in.

# Only members of "acme-corp" can access the dashboard
dashboard:
  allowed_org: "acme-corp"

Can also be set via the MOLE_DASHBOARD_ALLOWED_ORG environment variable.

Manager sees less than Tech Lead by design — this tool is for growth, not HR evaluation.

github:
  app_id: 12345                          # GitHub App ID
  private_key_path: /etc/mole/app.pem    # Path to private key
  webhook_secret: "secret"               # Webhook secret

llm:
  api_key: "sk-ant-..."                  # Anthropic API key
  review_model: "claude-sonnet-4-6"      # Standard review model
  deep_review_model: "claude-opus-4-6"   # Deep review model
  # Pricing per 1M tokens [input, output] — for the Costs dashboard
  # Defaults to Anthropic's published pricing if omitted
  pricing:
    claude-sonnet-4-6: [3.00, 15.00]
    claude-opus-4-6: [15.00, 75.00]

mysql:
  host: localhost
  port: 3306
  database: mole
  user: mole
  password: "password"

valkey:
  host: localhost
  port: 6379

server:
  port: 8080

worker:
  count: 3

log:
  level: info                            # debug | info | warn | error

# Dashboard (optional)
dashboard:
  github_client_id: ""
  github_client_secret: ""
  session_secret: ""
  base_url: "http://localhost:8080"
  allowed_org: ""                        # Restrict to org members (leave empty to allow all)

Every field can be overridden with environment variables using the MOLE_ prefix:

A pre-built image is published to GHCR on every push to main:

docker pull ghcr.io/getkaze/mole:main

docker run -d --name mole \
  -p 8080:8080 \
  -v /path/to/mole.yaml:/etc/mole/mole.yaml \
  -v /path/to/github-app.pem:/etc/mole/github-app.pem \
  ghcr.io/getkaze/mole:main serve --config /etc/mole/mole.yaml

docker run -d --name mole \
  -p 8080:8080 \
  -v /path/to/github-app.pem:/etc/mole/github-app.pem \
  -e MOLE_GITHUB_APP_ID=12345 \
  -e MOLE_GITHUB_PRIVATE_KEY_PATH=/etc/mole/github-app.pem \
  -e MOLE_GITHUB_WEBHOOK_SECRET=secret \
  -e MOLE_LLM_API_KEY=sk-ant-... \
  -e MOLE_MYSQL_HOST=mysql \
  -e MOLE_VALKEY_HOST=valkey \
  ghcr.io/getkaze/mole:main

docker build -t mole .

make build              # current platform
make release            # cross-compile for linux/darwin amd64/arm64
make test               # run tests
make clean              # remove binaries

Binaries are output to dist/ with SHA256 checksums.

MIT — see LICENSE.