Strict static analyzer for Go. Zero external dependencies — every rule is implemented from scratch on top of go/ast, go/types, and the go list command.

The bug above (transfer("o-42", "u-7") with parameters declared as userID, orderID string) compiles, passes every test, and ships to production. No major Go linter today catches this class. gox does, by demanding inline /* paramName */ comments at the call site whenever two adjacent arguments share a type.

The goal: catch the classes of bugs an LLM writing Go without supervision is most likely to introduce. Be loud, be opinionated, fail closed.

Status: experimental. Built as a tool for using Claude Code, Grok Build, and similar agents to write Go without leaving silent bugs behind. Used daily, but the rule set is still evolving — expect breaking changes to annotation syntax until v1.0.

Install

go install github.com/mentasystems/gox/cmd/gox@latest

Use

gox check ./...        # analyze; exit 1 on any issue
gox list               # list registered analyzers
gox explain <rule>     # print the rule's reference markdown
gox build [args]       # gox check && go build
gox test  [args]       # gox check && go test

Rules

Annotations

Every rule has a single opt-out marker. Annotations must include a reason after the colon — empty reasons are ignored.

Rule reference

The compiled gox binary ships every rule's reference page embedded as markdown. Print one to stdout:

The same content is available as a JSON envelope for agent consumption:

gox explain bodyclose --json
# { "rule": "bodyclose", "doc": "...", "explanation": "..." }

Each reference page covers what the rule catches, a bad / good example, the opt-out syntax, and the analyzer's known limitations. The reference is version-pinned to the binary you have installed — when a rule grows a new edge case, gox explain reflects it without depending on an external docs site.

Claude Code / Grok Build integration

gox install claude
gox install grok

gox install claude writes ~/.claude/gox-hook.sh and registers it as a Stop hook in ~/.claude/settings.json (timeout 30s). It is idempotent and migrates legacy PostToolUse registrations automatically. Preserves every other key in the file.

gox install grok writes ~/.grok/hooks/gox-hook.sh and registers the same Stop hook in ~/.grok/hooks/gox.json (native Grok hook file). Multiple *.json files under ~/.grok/hooks/ are merged; the command only touches the Stop array for our entry and leaves other events or user content intact.

When the agent finishes a turn, the hook scans the current git repo for changed .go files (unstaged, staged, and untracked) and runs gox check once per affected package. If issues are found, the hook returns a {"decision":"block","reason":"..."} payload. Claude surfaces it on the next turn; Grok records it as a hook annotation in the scrollback (and, for Stop hooks, the same shape is supported for feeding issues back).

The hook runs once per turn (on Stop) rather than on every edit. Earlier versions used PostToolUse on each Edit/Write, which was too slow on large packages.

• Claude Code re-reads settings.json when /hooks is opened or the app restarts.
• Grok re-reads ~/.grok/hooks/*.json at session start and on l (reload) inside the hooks modal (Ctrl+L or /hooks).

The hook resolves gox via $GOX_BIN if set, otherwise ~/go/bin/gox. Run go install github.com/mentasystems/gox/cmd/gox@latest to ensure it is present. Because Grok also reads ~/.claude/settings.json for compatibility, gox install claude works for Grok users too; the native grok target is recommended when you only use Grok Build.

Performance

A pure-Go implementation with no runtime overhead from external linters. On a 442-package monorepo (~1800 .go files):

The cache is per-package, keyed by file mtime+size and the analyzer set hash. It lives under $XDG_CACHE_HOME/gox/v2 (or ~/.cache/gox/v2). Pass --no-cache to disable.

Output cap

gox check prints at most 100 issues by default, then a one-line summary of how many were hidden. This keeps the output bounded for context-limited consumers — notably the Claude Code Stop hook, which pipes gox check straight back into the model. Raise or lift the cap with --max-issues=N (0 = unlimited) or the GOX_MAX_ISSUES env var. Issues are sorted by file:line, so the truncation is deterministic.

Generated code

Files marked with the standard Go marker // Code generated <generator> DO NOT EDIT. near the top are skipped automatically. This covers protoc-gen-go, yo, mockgen, and most common generators.

How is this different from staticcheck / golangci-lint / revive?

Short answer: every existing Go linter is a detector. gox is a gate.

The existing tools surface warnings and let humans decide. That works when the human is the one writing the code. When an LLM is writing the code at the speed of a few tokens per second and no one is reviewing line-by-line, "surface a warning" is the wrong default — the warning will be ignored unless something downstream refuses to proceed.

Concrete differences:

The bug that motivated gox is the swap-prone call site:

transfer(orderID, userID)   // vs transfer(userID, orderID)

Both compile. Both pass tests. The wrong one ships and corrupts the ledger. No major linter catches this today; gox's namedargs rule forces inline /* paramName */ comments on adjacent same-type arguments at the call site, which:

• catches the bug,
• documents the call site,
• and the LLM annotating its own code is essentially free.

That trade — "more typing at the call site, near-zero bugs of this class" — only makes sense when typing is cheap, which is now.

If you already love golangci-lint, keep it. gox is meant to live alongside it, not replace it: golangci-lint is the spell-checker, gox is the production gate.

Design notes

• Zero external dependencies. Everything uses Go stdlib + a shell-out to go list -json. No golang.org/x/tools, no third-party linter packages. Minimal maintenance: when a new Go release ships, there's nothing to update.
• Fail closed. Every rule defaults to error. Opt-outs require an explicit annotation with a written reason — the reason is the documentation.
• Targeted at LLM-written code. Heuristics are tuned so each rule catches a high-frequency LLM bug class without flooding human-readable idioms. For example, shadow exempts ok (the universal comma-ok name) but still catches err re-declaration, which is exactly the bug we want.
• namedargs is the killer rule. Two adjacent string/int/bool parameters in user-defined code force the call site to label them with inline comments. Stdlib calls are exempt because their conventions are memorized. The bug it prevents — transfer(orderID, userID) vs transfer(userID, orderID) — produces no compile error and no test failure, and is the single most common silent-bug class in unsupervised AI-written Go.

Contributing

Issues and pull requests welcome. Two ground rules:

1. No external dependencies. Every rule must be implementable with the Go standard library plus an out-of-process go list -json call. Adding golang.org/x/tools/go/packages, staticcheck, or any third-party linter is out of scope.
2. Each new rule must pass its own check. Run gox check ./... on a fresh clone before opening a PR — gox runs against its own source as part of the smoke test.

License

BSD 3-Clause. See LICENSE.