gruff-go is an opinionated, parser-only code-quality scanner for Go, built to govern AI-generated code. It reads Go packages without executing them, scores findings across 11 quality pillars, and emits reports for terminals, CI annotations, SARIF consumers, static HTML, and a local dashboard.
gruff exists to make AI-generated code something a human can trust. Its primary use is a coding-agent hook: when an agent writes code, gruff is the gate that forces output a reviewer who didn't write it can actually sign off on. It optimises for three things:
- Legible enough to verify — a reviewer can confirm the code does what was asked.
- Secure where the eye fails — it catches the security classes human review reliably misses.
- Tested for real, not padded — it forces high-signal tests and rejects low-signal test ceremony.
The framing it encodes: you are a coding agent, and a human who didn't write this code has to read, review, and trust it. That is also why doc comments are required even on a private one-liner — not as ceremony, but because coding agents routinely produce code that superficially works while misunderstanding the requirement. Forcing the agent to state intent, usage, contract, and failure behaviour in prose gives the reviewer something to check the implementation against; a mismatch between the doc comment and the code is a signal the change needs a deeper look.
gruff is heuristic static analysis, not a proof: it can create the artifact a reviewer checks (a doc comment, an assertion) but cannot verify that artifact is truthful. Run it beside go vet, staticcheck, govulncheck, tests, and human review — as the forcing function that makes that review tractable, not a replacement for it.
| Field | Value |
|---|---|
| Release line | Published 0.4.0 package line |
| Runtime | Go 1.25+ |
| Module | github.com/blundergoat/gruff-go |
| Binary | gruff-go |
| Rule catalogue | 83 rules across 11 pillars; 70 enabled by default |
| Primary config | .gruff-go.yaml |
| Analysis schema | gruff.analysis.v2 |
| Baseline schema | gruff-go.baseline.v0.1 |
| Severity gate | --min-severity with advisory, warning, error |
| Dashboard | 127.0.0.1:8765 by default |
- Go
1.25or newer, matchinggo.mod. - Git only for changed-region scans (
--since,--diff, or the legacy--diff-base). - No runtime dependencies outside the Go standard library.
The project-pinned install flow uses Go's tool directive, which needs Go 1.24 or newer. The binary itself requires Go 1.25+, so that is the effective floor.
Install as a project-pinned dev tool:
go get -tool github.com/blundergoat/gruff-go/cmd/gruff-go@v0.4.0
go tool gruff-go init
go tool gruff-go summary .From a source checkout:
git clone https://github.com/blundergoat/gruff-go.git
cd gruff-go
go build -o ./bin/gruff-go ./cmd/gruff-go
./bin/gruff-go --helpLinux, macOS, and Windows archives are attached to each GitHub Release. Releases include checksums.txt.
# Create the project config.
go tool gruff-go init
# Review the current finding mix.
go tool gruff-go summary .
# Inspect the current module.
go tool gruff-go analyse .
# Raise the failure floor while exploring an existing codebase.
go tool gruff-go analyse --min-severity error .
# Emit SARIF for code scanning.
go tool gruff-go analyse --format sarif --min-severity error . > gruff.sarif
# Generate a fresh-start baseline.
go tool gruff-go analyse --generate-baseline gruff-baseline.json .
# Start the local dashboard.
go tool gruff-go dashboard --project .Go's standard flag package stops parsing flags at the first non-flag argument. Put every --flag before path arguments.
| Command | Purpose |
|---|---|
analyse |
Run rules over the supplied paths and emit a report. |
hook |
Emit the gruff.hook.v1 JSON contract for coding-agent changes. |
summary |
Print a compact score, per-pillar counts, top rules, and top files. |
report |
Render static HTML or JSON to stdout or --output <file>. |
baseline |
Run a scan and write the current findings to a baseline file. |
init |
Generate a default .gruff-go.yaml. |
check-ignore |
Report whether paths.ignore / gitignore would exclude given paths, and why. |
list-rules |
Print rule metadata as text or JSON. |
dashboard |
Serve the local browser dashboard. |
list, help |
Show command lists and command-specific help. |
completion |
Print a shell completion script. |
analyze is accepted as an alias for analyse.
Run go tool gruff-go help <command> for command-specific flags.
go tool gruff-go analyse --format <fmt> accepts:
| Format | Use it for |
|---|---|
text |
Human terminal output. |
json |
Full gruff.analysis.v2 report. |
summary-json |
Compact CI digest without the full finding list. |
sarif |
SARIF 2.1.0 for code scanning. |
github |
GitHub Actions workflow annotations. |
html |
Self-contained inspection report. |
markdown |
CI-ready Markdown summary for PR comments or job summaries. |
go tool gruff-go report --format <fmt> accepts html and json. See docs/output-formats.md for schema details and HTML flags.
| Code | Meaning |
|---|---|
0 |
No finding met --min-severity, and no fatal diagnostic occurred. |
1 |
At least one finding met --min-severity. |
2 |
Invalid input or a fatal diagnostic such as config, parse, baseline, path, or diff failure. |
--min-severity defaults per command: advisory (every finding fails) for analyse and summary, none (never fails) for the report and dashboard artifact generators - see configuration. Pass warning for moderate gating or error for the strict gate. Go uses --min-severity where the other gruff implementations use --fail-on; both names work on the CLI as of v0.1.1.
Generic CI command:
go tool gruff-go analyse --format github --min-severity warning .SARIF upload jobs can use:
go tool gruff-go analyse --format sarif --min-severity error . > gruff-go.sarifFor incremental rollout, generate a baseline first, commit it after review, then run with --baseline gruff-baseline.json. See docs/ci-integration.md for GitHub Actions and GitLab examples.
gruff-go auto-loads .gruff-go.yaml from the project root unless --config <path> or --no-config is supplied. Config validation fails closed on unknown keys, unknown rule IDs, unknown pillars, and invalid thresholds.
paths:
ignore:
- "vendor/"
- "internal/generated/"
allowlists:
acceptedAbbreviations: ["ID", "HTTP", "JSON", "AST"]
secretPreviews: [] # authorize fixed category/scheme markers; payload stays hidden
selection:
excludeRules: []
excludePillars: []
rules:
complexity.cyclomatic:
threshold: 15
severity: error
naming.package-underscore:
enabled: trueSee docs/configuration.md for the full schema and validation rules.
The current checkout contains 83 rules across 11 pillars. 70 rules are enabled by default; the 13 opt-in rules are convention-only naming/modernisation checks, parser-only dead-code candidates, the entropy/PII/PHI sensitive-data detectors, and the static-analysis-redundant test candidate.
| Pillar | Rules |
|---|---|
complexity |
3 |
dead-code |
6 |
design |
1 |
documentation |
5 |
maintainability |
6 |
modernisation |
2 |
naming |
8 |
security |
24 |
sensitive-data |
16 |
size |
3 |
test-quality |
9 |
See docs/rules.md for rule IDs, severities, thresholds, and remediation guidance.
list-rules reports the effective rule state after applying project config. Use go tool gruff-go list-rules --no-config to inspect built-in defaults.
Baselines suppress reviewed findings without disabling rules:
go tool gruff-go analyse --generate-baseline gruff-baseline.json .
go tool gruff-go analyse --baseline gruff-baseline.json .Matching is one-to-one. Gruff consumes exact rule/file/fingerprint pairs first,
then pairs remaining modern entries by their line-insensitive contract identity.
This keeps reviewed findings unchanged after line or measured-value shifts without
letting one baseline row hide multiple duplicate findings. Older entries without
stableIdentity remain compatible and use exact fingerprint matching only. The
agent hook uses the same matcher for baseline and git-base new-only filtering.
Changed-region scans use Git only when requested:
go tool gruff-go analyse --format json --changed-ranges "3-3,8-10" src/foo.go
go tool gruff-go analyse --format json --since HEAD src/foo.go
git diff | go tool gruff-go analyse --format json --diff ---diff also accepts working-tree, staged, unstaged, or a base ref. JSON output keeps the normal findings array and adds suppressedCount when changed-region filtering is active. The older --diff-base flag remains supported as a base-ref alias.
Display filters such as --include-pillars, --exclude-rules, and --include-rules reduce report noise without changing which rules execute.
go tool gruff-go dashboard --project .
# Open http://127.0.0.1:8765/ in a browser.The dashboard binds to loopback by default and refuses public hosts unless --allow-public is supplied. It has no authentication; treat the bind address as the safety boundary. See docs/dashboard.md for the security model, postMessage protocol, and scan timeout behavior.
In polyglot repositories, gruff-go, gruff-php, and gruff-py all default to port 8765; use --port when running multiple dashboards at the same time.
Default scans are local source inspections. gruff-go parses Go source and selected text/config files; it does not execute target code, run tests, call package build scripts, query vulnerability feeds, or replace type-aware tools. Git is invoked only for explicit diff scans. Sensitive-data previews are deny-by-default: empty or nonmatching preview allowlists emit [redacted], while matching paths may emit only fixed category or connection-scheme markers—never reusable payload bytes.
While gruff is pre-1.0, the CLI surface, rule IDs, finding fingerprints, baseline identity, and schemas named in this README are compatibility-sensitive within a patch series. Breaking changes to those surfaces land in a minor release and are called out in CHANGELOG.md. Rule precision is calibrated by dogfooding this repository and by scanning a separate Go service corpus before release.
| Tool | Relationship |
|---|---|
go vet |
Type-aware checks for suspicious Go constructs. Run it before or beside gruff-go. |
staticcheck |
Deeper semantic linting. gruff-go focuses on scoring, baselines, reports, and project-level quality signals. |
govulncheck |
Vulnerability-feed-backed dependency and call-path checks. gruff-go does not query vulnerability feeds. |
gofmt / go fmt |
Formatting only. gruff-go does not format code. |
| Code review and tests | Still required; gruff findings are deterministic review prompts, not runtime proof. |
go test ./...
go vet ./...
make checkmake check is the release gate together with a dogfood scan that must return grade A with zero findings on this repository. Read CONTRIBUTING.md for workflow and test conventions.
docs/ indexes the full set. The most-used entries:
- Agent guardrail - running gruff as a coding-agent hook: the loop, pre-commit, and CI gate.
- Configuration
- Output formats
- Rules
- Dashboard
- CI integration
- Releasing
- Changelog
- Contributing
- Security
Built by Matthew Hansen.