GitPreflight (v0)

Clean PRs by default. Fix issues at commit time.

GitPreflight is a staged-only, pre-commit code review gate designed for AI coding agents. It runs on git commit, reviews the staged diff only (git diff --cached), and prints stable Markdown your agent can apply before you push.

• Runs on git commit via a pre-commit hook.
• Reviews the staged diff only (git diff --cached).
• Prints a stable, LLM-friendly Markdown report with actionable suggestion blocks.
• Blocks commits when it finds minor or major issues.

Requirements

End users:

• Node.js (for the npm installer wrapper)
• Git

Contributors / source builds:

• Bun (repo package manager + CLI build/runtime for the interactive UI)
• Node.js (used by Next.js/Convex tooling)

Install (recommended)

Global install via npm (downloads a platform binary on install/first run):

npm i -g gitpreflight
gitpreflight --help

Curl install (OpenCode-style):

curl -fsSL https://gitpreflight.ai/install | bash
gitpreflight --help

Run (web + Convex)

bun dev

• Web app: http://localhost:3000
• Run individually:
  • bun run dev:web
  • bun run dev:convex

Configure (local-agent mode)

In a repo you want to protect:

gitpreflight setup
gitpreflight setup local-agent

The local-agent setup flow asks which local agent you use (Codex, Claude, or OpenCode), probes the command, then writes config to ~/.config/gitpreflight/config.json.

Check your installed version (and latest known release):

gitpreflight version
# shorthand:
gitpreflight -v

Hook setup

In a repo you want to protect:

gitpreflight setup
# or non-interactive:
# gitpreflight setup --scope local --hook pre-commit --yes
# gitpreflight setup --scope global --hook pre-commit --yes
# gitpreflight setup --scope repo --hook pre-commit --yes

gitpreflight setup is interactive in a TTY and explains scope options:

• global: enable across all repos on your machine
• local: enable for this repo only, without committed integration files
• repo: committed repo-owned setup for all contributors

Compatibility: gitpreflight init still works for repo-scoped Husky setup.

GitPreflight integrates via Husky:

• Adds/extends package.json#scripts.prepare to include husky install
• Creates/appends .husky/pre-commit to run gitpreflight review --staged
• Creates/appends .husky/post-commit for unchecked-commit capture

Optional push-gate mode:

• gitpreflight setup --scope repo --hook pre-push --yes creates/appends .husky/pre-push to run gitpreflight review --push
• gitpreflight setup --scope repo --hook both --yes installs both commit + push hooks

Inspect or remove setup:

gitpreflight status --verbose
gitpreflight uninstall --scope local
# or
gitpreflight uninstall --scope global

Policy overrides (optional):

# global default policy
git config --global gitpreflight.policy optional

# local repo override (for example, opt out in one repo)
git config --local gitpreflight.policy disabled

Repo owners can commit policy in package.json:

{
  "gitpreflight": {
    "policy": "required"
  }
}

Policy precedence is: repo policy > local git config > global git config > default (optional).

After repo-scoped setup (gitpreflight setup --scope repo ... or gitpreflight init), run your package manager install so Husky activates:

npm install
# or: pnpm install / yarn install / bun install

Run a review

gitpreflight review --staged

Hooks/CI output is always plain Markdown. In an interactive terminal, GitPreflight prefers a Bun-powered TUI (and falls back to a pager when needed).

Force plain Markdown output:

gitpreflight review --staged --plain
# or
GITPREFLIGHT_UI=plain gitpreflight review --staged

Metrics and telemetry

GitPreflight tracks two metric streams:

• Anonymous product telemetry (CLI + installer):
  • Endpoints:
    • POST /api/v1/usage/install
    • POST /api/v1/usage/review
  • Client payload: { "installId": "<random-id>" }
  • Not collected in payload: user identity, email, auth token, repository URL, file contents, patch/diff content.
  • Server behavior: Convex HTTP endpoints forward each event to PostHog.
• Hosted review metrics (server-side):
  • Daily usage quota counters are tracked per user and per org (usageDaily) when reviews run through the hosted /api/v1/review path.
  • Per-model aggregates (modelStats) track runs, findings, and average latency for dashboard reporting.

Local-agent mode note:

• Local reviews do not hit hosted usage quota or model-stat tracking.
• They still send the anonymous usage/review event (unless opted out below).

Opt out:

# disable anonymous analytics
export GITPREFLIGHT_ANON_TELEMETRY=0
# or
export GITPREFLIGHT_DISABLE_ANON_TELEMETRY=1

Override usage endpoint host (CLI/installer):

export GITPREFLIGHT_TELEMETRY_BASE_URL="https://your-gitpreflight-host"

Official release builds bake a default usage host at build/publish time (from GITPREFLIGHT_API_BASE_URL in release CI). Runtime env vars still take precedence.

Convex env required for forwarding events:

POSTHOG_API_KEY=phc_...
# optional override (default: https://us.i.posthog.com)
POSTHOG_HOST=https://us.i.posthog.com

Unchecked policy (offline/timeout)

If GitPreflight cannot complete a review (network/timeout/server issues):

• The commit is allowed.
• The commit is marked as UNCHECKED locally under .git/gitpreflight/.
• The next run on the same branch is blocked until the backlog is cleared or explicitly bypassed.

Bypass

• One-shot bypass (preferred):

gitpreflight skip-next --reason "<why>"

• Universal bypass:

git commit --no-verify
# or (if using pre-push mode):
git push --no-verify

Enforcement note

Repo-scoped hooks are a strong local default, but true "required" enforcement needs protected branch checks in your git host.

• Recommended: require a GitPreflight CI status check for merges to protected branches.
• Client hooks alone are bypassable via --no-verify.

Privacy stance

GitPreflight avoids storing customer repo source code at rest.

• The server stores:
  • instruction file contents (by hash) when configured (e.g. AGENTS.md)
  • review outputs and aggregated usage/statistics
  • anonymous usage events keyed by random install ID (forwarded to PostHog)
• The server does not store arbitrary repo files.

Source builds / local service

To build/run from source:

cd code
bun install

Run the CLI from source:

bun packages/cli/src/index.ts --help
bun packages/cli/src/index.ts review --staged

Local-agent mode

Local-agent mode shells out to a configured local agent command and expects GitPreflight Markdown output.

Configure it once:

gitpreflight setup local-agent

The setup flow lets you choose a provider (Codex, Claude, or OpenCode), probes the command with a live check, and saves config under ~/.config/gitpreflight/config.json.

Provider default commands:

• Codex -> codex
• Claude -> claude
• OpenCode -> opencode run

Probe success criteria before saving config:

• command spawn succeeds
• exit code is 0
• output is non-empty

Config files written:

• ~/.config/gitpreflight/config.json
• ~/.config/gitpreflight/config.schema.json

Then run reviews with local-agent mode:

gitpreflight review --staged --local-agent