morluto / smokinggun

SmokingGun

Optimization evidence for agents: find complexity hotspots and test whether a proposed change is worth making.

It keeps static findings, estimates, imported measurements, and behavior evidence distinct so agents can decide what to investigate next.

Install the agent skill

The optional smokinggun skill teaches compatible agent hosts how to use the CLI. Install it with the shared Skills CLI:

npx skills add https://github.com/morluto/smokinggun --skill smokinggun

The Skills CLI owns skill placement, conflict handling, and updates. SmokingGun does not modify agent configuration or install skills itself.

Install the CLI

npm install -g smokinggun

Or bootstrap one scan without a global install:

npx --yes --package=smokinggun -- smokinggun scan .

This command may contact the npm registry. SmokingGun requires Node 22.18 or later.

Use the CLI

Scan a repository:

smokinggun scan .
smokinggun scan . --format markdown
smokinggun scan . --format sarif --output smokinggun.sarif

Reports include the hotspot, supporting evidence, coverage, assumptions, and the validation needed next.

Static scans are read-only, offline, and do not execute repository code or modify source files. Findings are candidates, not proof. SmokingGun imports measurement evidence from existing benchmark tools; it does not launch workloads or rewrite code.

Semantic scanners consume the captured source snapshot directly. External adapters run only with explicit authorization and an enforcing read-only sandbox; they receive captured source bytes rather than the live checkout. Benchmark, profile, and measurement artifacts cross an import boundary without granting workload-execution authority. See the authority architecture for the ownership rules behind these choices.

About

SmokingGun's authoritative path is immutable capture, snapshot-backed scanning, truthful coverage, content-addressed reports, and explicit evidence imports. SARIF, SCIP, benchmarks, profiles, and measurements remain external inputs. Missing or failed coverage stays visible instead of becoming a clean scan.

Development

Requires Node 22+ and pnpm 11.20.0.

pnpm install
pnpm typecheck && pnpm test && pnpm build

Quality gates: pnpm lint (oxlint), pnpm format:check (oxfmt), pnpm knip, pnpm check:boundaries, and pnpm test:coverage. Run pnpm changeset to record a release change intent. pnpm test:cli and pnpm test:package exercise the built package end-to-end.