flanksource-gavel

Gavel

A CLI toolkit for git analysis, AI-powered code review, and markdown-based test fixtures.

Install

# From source
go install github.com/flanksource/gavel/cmd/gavel@latest

# Or build locally
task build
task install  # installs to $GOPATH/bin

Pre-built binaries for Linux, macOS, and Windows are available on the Releases page.

Commands

gavel git history

Retrieve and filter commit history from a git repository.

gavel git history --path .
gavel git history --since 2024-01-01 --until 2024-06-01
gavel git history --author "alice" --message "feat*"
gavel git history abc1234                    # specific commit
gavel git history main..feature-branch       # commit range

Flag	Description
--path	Path to git repository (default: .)
--since	Start date for filtering
--until	End date for filtering
--author	Filter by author name/email (repeatable)
--message	Filter by commit message
--show-patch	Include diffs

gavel git analyze

Analyze commits with scope/technology detection, Kubernetes resource change tracking, severity scoring, and optional AI-powered analysis.

gavel git analyze
gavel git analyze --ai --model claude-sonnet-4-20250514
gavel git analyze --scope backend --tech kubernetes
gavel git analyze --summary --summary-window week
gavel git analyze --include bots --exclude merges --verbose
gavel git analyze --input previous-run.json   # re-analyze from JSON

Flag	Description
--ai	Enable AI-powered analysis
--model	AI model to use
--scope	Filter by scope types
--commit-types	Filter by conventional commit types
--tech	Filter by technologies
--summary	Generate a tree-based summary
--summary-window	Grouping window: day, week, month, year
--include	Include named filter sets from .gitanalyze.yaml
--exclude	Exclude named filter sets from .gitanalyze.yaml
--verbose	Show what was skipped and why
--input	Load from previous JSON output (repeatable)
--short	Show condensed file-change summary

gavel git init-config

Create a .gitanalyze.yaml with sensible defaults, then optionally spawn an AI CLI to analyze the repo and recommend additional rules.

gavel git init-config                          # create defaults + AI recommendations via claude
gavel git init-config --model gemini           # use gemini instead
gavel git init-config --model codex            # use codex instead
gavel git init-config --model none             # just create the defaults file, no AI

Flag	Description
--path	Path to git repository (default: .)
--model	AI CLI to use: claude, gemini, codex, or none (default: claude)
--debug	Enable debug logging

gavel git amend-commits

Interactively improve commit messages using AI. Rewrites commits below a quality score threshold.

gavel git amend-commits
gavel git amend-commits --threshold 5.0 --base main
gavel git amend-commits --dry-run

gavel verify

AI-powered code review with structured checks across completeness, code quality, testing, consistency, security, and performance.

gavel verify
gavel verify --range main..HEAD
gavel verify --model gemini --disable-checks SEC-1,PERF-2
gavel verify --auto-fix --max-turns 5
gavel verify --sync-todos

Flag	Description
--model	AI CLI: claude, gemini, codex, or a model name
--range	Commit range to review
--auto-fix	Enable iterative AI fix loop
--fix-model	Separate model for fixes
--max-turns	Max verify-fix cycles (default: 3)
--score-threshold	Exit 0 if score >= this (default: 80)
--disable-checks	Check IDs to disable
--sync-todos	Create TODO files from findings

gavel fixtures

Run declarative tests defined in markdown files using tables, command blocks, or standalone code blocks.

gavel fixtures tests.md
gavel fixtures fixtures/**/*.md
gavel fixtures -v tests.md                  # verbose (stderr on pass, stdout+stderr on fail)
gavel fixtures -vv tests.md                 # more verbose
gavel fixtures --no-progress tests.md       # disable progress display

Fixtures support three formats in a single markdown file:

Table format (preferred) — each row is a test. Custom columns become template variables in exec/args:

---
exec: bash
args: ["-c", "curl {{.flags}} {{.baseUrl}}{{.path}}"]
baseUrl: https://api.example.com
flags: "-s"
---

| Name       | path    | CEL                      |
|------------|---------|--------------------------|
| get users  | /users  | json.size() > 0          |
| get health | /health | json.status == "ok"      |