Skip to content

flanksource/gavel

BranchesTags

Repository files navigation

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

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"      |

Command blocks — use when commands are multi-line or need per-test setup:

### command: my test
```yaml
exitCode: 0
env:
  KEY: value
```

```bash
echo "hello"
```

* contains: hello

Standalone code blocks — auto-detected from headings:

## Smoke Tests

```bash
echo "auto-detected"
```

* cel: stdout.contains("auto-detected")

Front-matter configures build steps, default executables, file expansion, environment variables, working directory (cwd), and timeouts. The working directory resolves relative to the fixture file's location — set it at the file level for all tests or override per-test via table columns or command block frontmatter. See gavel fixtures --help for the full reference.

gavel test

Discover and run Go and Ginkgo tests with structured output.

gavel test --path ./...
gavel test --path ./pkg/... --name "TestFoo" -r
gavel test --format json
Flag Description
--path Test path pattern
--name Filter by test name
-r / --recursive Recursive test discovery
--format Output format (json, text)

gavel todos

Manage and execute TODO items with Claude Code integration.

gavel todos list
gavel todos list --status pending
gavel todos run .todos/fix-bug.md
gavel todos check .todos/fix-bug.md

gavel pr watch

Monitor GitHub Actions status for pull requests.

gavel pr watch
gavel pr watch --follow --interval 30s
gavel pr watch --sync-todos

gavel repomap

View the merged architecture configuration for a repository path.

gavel repomap view .
gavel repomap get src/main.go

Configuration

arch.yaml

Placed at the repository root (or any directory — gavel walks up to find it). Defines scope classification, technology detection, severity rules, and build/git settings.

scopes:
  rules:
    backend:
      - path: "cmd/**"
      - path: "pkg/**"
    frontend:
      - path: "web/**"

tech:
  rules:
    kubernetes:
      - path: "deploy/*.yaml"

severity:
  default: medium
  rules:
    'kubernetes.kind == "Secret"': critical
    'change.type == "deleted"': critical
    'commit.line_changes > 500': critical

git:
  version_field_patterns:
    - "**.image"
    - "**.tag"
    - "**.version"

Embedded defaults detect common scope types (ci, dependency, docs, test) and technologies (Go, Node.js, Python, Kubernetes, Terraform, Docker, etc.).

.gitanalyze.yaml

Controls which commits, files, authors, and resources are excluded from gavel git analyze. Placed at the repository root.

# Named filter sets toggled with --include / --exclude
filter_sets:
  bots:
    ignore_authors:
      - "dependabot*"
      - "renovate*"
      - "github-actions*"

  noise:
    ignore_files:
      - "*.lock"
      - "go.sum"
      - "package-lock.json"

  generated:
    ignore_resources:
      - kind: ConfigMap
        name: "*-generated"
      - kind: Secret

# Which filter sets are active by default
includes:
  - bots
  - noise

# Top-level filters (always applied)
ignore_commits:
  - "fixup!*"
  - "squash!*"

ignore_files:
  - ".idea/*"
  - "*.svg"

ignore_commit_types:
  - "chore"
  - "ci"

# CEL expressions — skip when true
ignore_commit_rules:
  - cel: "commit.is_merge"
  - cel: "commit.line_changes > 10000"

# Kubernetes resource filters
ignore_resources:
  - kind: Secret
  - kind: ConfigMap
    name: "*-generated"

CEL variables available in ignore_commit_rules:

Variable Type Description
commit.author string Author name
commit.author_email string Author email
commit.subject string Commit subject line
commit.body string Commit body
commit.type string Conventional commit type
commit.scope string Conventional commit scope
commit.is_merge bool True if subject starts with "Merge "
commit.files_changed int Number of files changed
commit.line_changes int Total lines added + deleted
commit.additions int Lines added
commit.deletions int Lines deleted
commit.files list File paths changed
commit.tags list Commit tags
commit.is_tagged bool True if commit has tags

Embedded defaults skip bot authors (dependabot*, renovate*, github-actions*), lock files (*.lock, go.sum, etc.), and merge commits.

Override at the CLI:

gavel git analyze --exclude bots      # include bot commits
gavel git analyze --include generated  # activate the "generated" filter set
gavel git analyze --verbose            # show skip reasons

Agent Skills

Gavel ships Agent Skills that give AI coding agents the ability to create and run fixture-based tests. Skills are auto-discovered from .agents/skills/ by any compatible agent (Claude Code, VS Code Copilot, Cursor, Gemini CLI, and others).

Skill Description
gavel-fixture-tester Create and run fixture-based tests using markdown files with command blocks, tables, and CEL assertions

Install

npx skills add flanksource/gavel

Use -g to install globally (all projects) or omit for project-only. Preview available skills first with npx skills add flanksource/gavel -l.

See .agents/skills/README.md for alternative installation methods.

Development

task build       # build binary
task test        # run all tests
task test:unit   # run unit tests only
task lint        # run linters
task fmt         # format code
task ci          # fmt + lint + test + build

License

See LICENSE for details.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.0.14 Latest
Mar 24, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages