gaze report

April 9, 2026 · View on GitHub

Orchestrate Gaze's four analysis operations (CRAP, quality, classification, docscan) and pipe the combined JSON payload to an external AI CLI for formatting into a human-readable markdown report.

The formatted report is written to stdout and optionally appended to $GITHUB_STEP_SUMMARY for GitHub Actions Step Summary integration.

Synopsis

gaze report [packages] [flags]

Arguments

Argument	Required	Description
`packages`	No	Go package patterns (e.g., `./...`, `./internal/...`). Defaults to `./...` when omitted.

When no package arguments are provided, ./... is used automatically (the entire module).

Flags

Flag	Type	Default	Description
`--format`	`string`	`text`	Output format: `text` (AI-formatted markdown) or `json` (raw analysis payload)
`--ai`	`string`	`""`	AI adapter: `claude`, `gemini`, `ollama`, or `opencode`. Required in text mode.
`--model`	`string`	`""`	Model name for the AI adapter. Required for `ollama`; optional for other adapters.
`--ai-timeout`	`duration`	`10m`	Maximum time to wait for the AI adapter to respond. Uses Go duration format (e.g., `5m`, `30s`, `2m30s`).
`--coverprofile`	`string`	`""`	Path to a pre-generated Go coverage profile. Skips the internal `go test -coverprofile` run.
`--max-crapload`	`int`	not set	CI gate: fail if CRAPload exceeds N. Absent by default (no enforcement).
`--max-gaze-crapload`	`int`	not set	CI gate: fail if GazeCRAPload exceeds N. Absent by default (no enforcement).
`--min-contract-coverage`	`int`	not set	CI gate: fail if average contract coverage is below N%. Absent by default (no enforcement).

The threshold flags (--max-crapload, --max-gaze-crapload, --min-contract-coverage) use pointer semantics internally: when a flag is not provided, no threshold is enforced. When explicitly set — even to 0 — the threshold is active. This means --max-crapload=0 will fail if any function is in the CRAPload (i.e., zero tolerance).

Configuration Interaction

The gaze report command does not directly read .gaze.yaml. The underlying analysis pipeline uses default classification thresholds. To customize thresholds, use gaze crap and gaze quality individually.

The --coverprofile flag is the key CI optimization — pass a coverage profile generated during your test step to avoid running tests twice.

AI Adapter Details

Adapter	Binary	System Prompt Delivery	Payload Delivery
`claude`	`claude`	Temp file via `-p` flag	stdin
`gemini`	`gemini`	`GEMINI.md` in temp dir	stdin
`ollama`	HTTP API	`system` field in JSON body	`prompt` field in JSON body
`opencode`	`opencode`	`.opencode/agents/gaze-reporter.md` in temp dir via `--dir`	stdin

Before the analysis pipeline starts, Gaze validates that the adapter binary exists on PATH (or that the Ollama HTTP API is reachable). An invalid binary produces a hard exit before any analysis runs.

Environment Variables

Variable	Description
`GITHUB_STEP_SUMMARY`	When set, the formatted report is appended to this file path for GitHub Actions Step Summary display. Symlink protection (`O_NOFOLLOW`) is applied.

Examples

AI-formatted report with Claude

gaze report ./... --ai=claude

JSON-only output (no AI required)

gaze report ./... --format=json > report.json

In JSON mode, the --ai flag is not required. The raw analysis payload is written directly to stdout.

CI integration with thresholds

# Generate coverage during test step
go test -race -count=1 -coverprofile=coverage.out ./...

# Run report with pre-generated coverage and quality gates
gaze report ./... \
  --ai=opencode \
  --coverprofile=coverage.out \
  --max-crapload=35 \
  --max-gaze-crapload=5 \
  --min-contract-coverage=8

Using Ollama (local model)

gaze report ./... --ai=ollama --model=llama3.2

The --model flag is required for Ollama and specifies which model to use for formatting.