convex-doctor

Diagnose your Convex backend for anti-patterns, security issues, and performance problems.

convex-doctor is a static analysis CLI for Convex projects. It parses your convex/ directory, runs 65 rules across 7 categories, and produces a weighted 0-100 health score. Think of it as ESLint, but purpose-built for Convex backends.

Benchmarks

Tested against 18 open-source Convex applications

Benchmarks run on Feb 24, 2026 against each project's main branch. Sorted by score.

Installation

Download prebuilt binary (recommended)

Grab the latest release for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/nooesc/convex-doctor/releases/latest/download/convex-doctor-aarch64-darwin -o convex-doctor
chmod +x convex-doctor && sudo mv convex-doctor /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/nooesc/convex-doctor/releases/latest/download/convex-doctor-x86_64-darwin -o convex-doctor
chmod +x convex-doctor && sudo mv convex-doctor /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/nooesc/convex-doctor/releases/latest/download/convex-doctor-x86_64-linux -o convex-doctor
chmod +x convex-doctor && sudo mv convex-doctor /usr/local/bin/

# Linux (aarch64)
curl -L https://github.com/nooesc/convex-doctor/releases/latest/download/convex-doctor-aarch64-linux -o convex-doctor
chmod +x convex-doctor && sudo mv convex-doctor /usr/local/bin/

Install from crates.io

cargo install convex-doctor

Build from source

git clone https://github.com/nooesc/convex-doctor.git
cd convex-doctor
cargo build --release
# Binary is at ./target/release/convex-doctor

Usage

Run from your project root (the directory containing convex/):

# Basic scan
convex-doctor

# Verbose output with file paths and line numbers
convex-doctor -v

# JSON output (for CI or tooling)
convex-doctor --format json

# Score only (prints just the number, e.g. "87")
convex-doctor --score

# Diff mode: only analyze files changed vs a base branch
convex-doctor --diff main
# Note: diff mode only runs file-level rules on changed files.

# Scan a specific project path
convex-doctor /path/to/my-project

Rules

convex-doctor runs 65 rules organized into 7 categories. Each category carries a different weight in the final score.

Rule reference

Scoring

The health score ranges from 0 to 100. Each finding deducts points based on its severity and category weight, with per-rule caps to prevent a single noisy rule from dominating the score.

Configuration

Create a convex-doctor.toml in your project root to customize behavior:

# Disable specific rules
[rules]
"security/missing-return-validators" = "off"
"arch/monolithic-file" = "off"

# Ignore files by glob pattern
[ignore]
files = [
  "convex/_generated/**",
  "convex/testHelpers.ts",
]

# CI: exit with code 1 if score is below threshold
[ci]
fail_below = 70

CI integration

GitHub Actions

Add convex-doctor to your CI pipeline using the prebuilt binary (runs in ~2 seconds, no Rust toolchain needed):

name: Convex Health Check
on: [pull_request]

jobs:
  convex-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install convex-doctor
        run: |
          curl -L https://github.com/nooesc/convex-doctor/releases/latest/download/convex-doctor-x86_64-linux -o convex-doctor
          chmod +x convex-doctor

      - name: Run convex-doctor
        run: ./convex-doctor

By default, convex-doctor exits with code 0. To fail the build when the score drops below a threshold, add a convex-doctor.toml to your project root:

[ci]
fail_below = 70

convex-doctor will exit with code 1 when the score is below fail_below.

Diff mode (PR-only scanning)

Only lint files changed in the pull request — useful for large codebases:

      - name: Run convex-doctor (changed files only)
        run: ./convex-doctor --diff origin/main

Alternative: install via cargo

If you prefer using the Rust toolchain:

      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install convex-doctor
      - run: convex-doctor

Note: cargo install takes ~30s to compile. The prebuilt binary approach is faster.

License

MIT