Evidence-bearing local complexity scanner and investigation tool for software-engineering agents.
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.
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.
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.
Scan a repository:
smokinggun scan .
smokinggun scan . --format markdown
smokinggun scan . --format sarif --output smokinggun.sarif
smokinggun scan . --source-profile all
Reports include the hotspot, supporting evidence, coverage, assumptions, and the validation needed next.
The default runtime profile suppresses findings from tests, documentation, examples, and fixtures while retaining
those files in repository inventory. Use --source-profile all to scan every supported source file, or --only <path> to
focus explicitly on an auxiliary area.
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. 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.
Textual inputs—including configuration, reports, and JSON evidence artifacts—must be valid UTF-8. SmokingGun rejects malformed byte sequences instead of silently replacing them, because replacement text would no longer represent the captured evidence. Binary formats such as gzip-compressed pprof profiles remain binary until their format decoder handles them.
Numeric pprof fields must fit JavaScript's exact integer range (Number.MIN_SAFE_INTEGER through Number.MAX_SAFE_INTEGER). SmokingGun rejects values outside that range instead of rounding identifiers or measurements.
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.
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.
FAQs
Evidence-bearing local complexity scanner and investigation tool for software-engineering agents.
The npm package smokinggun receives a total of 36 weekly downloads. As such, smokinggun popularity was classified as not popular.
We found that smokinggun demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Ten malicious OpenAPI React Query Codegen versions were published to npm in the Mini Shai-Hulud attack, all with valid provenance.
Security News
Socket joins more than 100 technology, cybersecurity, and financial organizations calling for a global surge in cyber defense.
Product
Enterprise security teams can now detect malware, credential theft, suspicious network activity, and risky updates across Microsoft Edge extensions.