paniolo scan Overview Docs Research Calibration Compare
Documentation

Using paniolo scan

Everything below works without Claude, without an API key, and without modifying your repo. The scan is a deterministic, offline CLI: no file writes, no model calls. Presenting the report is the paniolo-scan skill; fixing findings is paniolo-scan-remediate.

Quick Start

Run it now

# 1. Scan the repo you're in (terminal report) paniolo scan # 2. Machine-readable report for CI or tooling paniolo scan --format json # 3. Gate on severity (exit 1 when findings ≥ level) paniolo scan --fail-on warn

These commands use the native CLI. Install the unsigned Windows or Linux x64 pilot without Node or npm, then run them from your repo root. If you already use Node, run the same commands with npx @paniolo/cli in place of paniolo.

You get: detected harnesses, a guidance-file inventory, shared-vs-duplicated analysis, six dimension scores rolled into a totalScore (0–100), a per-harness gap matrix, and findings with concrete hints. A typical repo scans in seconds — it's filesystem and markdown parsing, no network, no model calls.

Deterministic by design: every check runs locally and gives the same result for an unchanged tree, so scores stay comparable across repos. The only network check, dead external links, runs when you pass --external-links.

Install Matrix

Choose how to run it

ChannelStart hereWhat you getBest for
Native CLI Install without Node
paniolo scan
The same read-only scanner, run without Node or npm. Unsigned pilot packages are available for Windows and Linux x64. Windows and Linux x64 hosts that do not use npm
npm CLI npx @paniolo/cli scan The diagnostic scanner without a permanent install. Requires Node; the scan makes no file changes. First scan, CI, scripts, headless use with Node
Portable skill npx skills add paniolo-ai/skills --all The read-only paniolo-scan skill in every skill-capable coding agent on your machine (Claude Code, Cursor, Copilot, Codex, Devin, Gemini CLI, and more). The agent runs the scan and presents scores. Fixes are a separate skill, paniolo-scan-remediate. Widest reach across agents
Claude Code plugin /plugin marketplace add https://github.com/paniolo-ai/skills
/plugin install paniolo-scan@paniolo-ai
The native /paniolo-scan slash command (bundles the skill). Claude Code users who want the slash command

The skill and slash command are separate installs. The skills.sh command installs the portable skill, which works in every agent (in Claude Code you invoke it by name, not as /paniolo-scan). The native slash command ships only through the Claude Code plugin. Installing one does not install the other.

CLI Reference

Every flag, verified

This table matches paniolo scan --help. A flag that is not listed here is not a scan flag.

FlagWhat it does
[PATH]Repository root to scan. Defaults to the current directory.
--harness <name>Restrict rule findings to one harness: copilot, cursor, codex, antigravity, claude, or gemini. Repeat the flag for several (--harness cursor --harness codex); a comma-separated list is rejected. Inventory, sharing, gap matrix, and optimization still evaluate all detected harnesses so JSON stays comparable.
--format <type>terminal (default) or json.
--fail-on <level>Exit 1 when findings at or above level exist: error (default), warn, or info. Overrides the config file.
--config <path>Use this paniolo.config.json. Defaults to one at the repo root if present.
--target <name>Scan a named repository from paniolo.config.json.
--target-for-current-dirScan the named target whose configured path matches the caller's original working directory. When a harness script is invoked with pnpm -C, npm's INIT_CWD points back at the repo that called it.
--profile <name>Built-in rule profile: default, strict, or minimal.
--rule <spec>Override one rule's severity and options, repeatable: rule-id=off|warn|error[:key=val,...].
--strict-configFail when the config names an unknown rule id.
--changedLint only changed files when safe; falls back to a full scan for global harness and config surfaces.
--files <files>...Scan only these files. Must come last on the command line.
--external-linksAlso check external links for dead URLs. The only network check; off by default.
--internal-wikiTeam flag. Include internal wiki source links in finding evidence. By default only public https:// URLs are printed.
--print-discoveryPrint detected harnesses and resolved skills directories as JSON, then exit without scanning.
--print-timingPrint per-phase and per-rule timing to stderr.
-h, --help / -V, --versionShow help or the version.

An older binary may lack a flag listed here. npx @paniolo/cli@latest scan --help is the check.

Report Reference

Reading the JSON

FieldMeaning
versionThe CLI version that produced the report.
totalScore0–100 rollup across the core meta-harness dimensions. Grades: excellent ≥ 85, good ≥ 70, fair ≥ 50.
scoreScopeWhich dimensions the score covers; "core" for the deterministic set. Compare scores across repos only within the same scope.
harnessesTools the repo appears to target, inferred from filesystem signals (e.g. CLAUDE.md, .cursor/, .codex/config.toml).
metaHarness.dimensionsPer-dimension status/score/grade. A dimension that did not run has "status": "not_run" and a null score — never zero.
sharingShared vs. harness-unique guidance in files, lines, and percent — the cross-harness duplication measure.
contextBudgetEstimated always-loaded lines and tokens per harness, with a recommended ceiling and status.
findings[]Rule violations: ruleId, severity (error warn info), message, file, line, a concrete hint, and evidence describing what the rule is based on.
summaryFinding counts by severity.
harnessGapMatrix / harnessOptimizationCapability table and 0–100 optimization score per detected harness, plus each harness's guidance footprint.

Annotated sample

Report shape from a harness scan. version is the CLI that wrote the file; the numbers will differ on your repo.

{ "version": "", "totalScore": 100.0, // core rollup — "excellent" band starts at 85 "scoreScope": "core", // deterministic dimensions only "summary": { "error": 0, "warn": 0, "info": 1 }, "metaHarness": { "dimensions": { "guardrails": { "status": "run", "score": 99, "grade": "excellent", "passedRules": 44, "applicableRules": 45 }, "sharing": { "status": "run", "score": 99, "grade": "excellent", "passedRules": 15, "applicableRules": 16 }, "session": { "status": "not_run", "score": null, "grade": null, "passedRules": 0, "applicableRules": 0 } // excluded, not zeroed } } }
Modes

Which mode, when

"Which flags should I use?"

You want…Run
A first look at one reponpx @paniolo/cli scan
A CI gate that blocks on serious issuesnpx @paniolo/cli scan --format json --fail-on error
A stricter gate including warningsnpx @paniolo/cli scan --fail-on warn
Only Cursor + Codex findingsnpx @paniolo/cli scan --harness cursor --harness codex
To scan a different directorynpx @paniolo/cli scan ../other-repo
Faster feedback on a branchnpx @paniolo/cli scan --changed
Workflows

Common flows, end to end

CLI only (no agent)

npx @paniolo/cli scan --format json > paniolo-report.json

Expected: JSON to stdout, exit 0 unless --fail-on matched. If you see "harnesses": [], no tool config was detected — baseline rules (like a missing AGENTS.md) still run, which is the point: the scan tells you what to add first.

Per-harness skill (any agent)

npx skills add paniolo-ai/skills --all # then, in your agent: "Use paniolo-scan to scan this repo and summarize findings."

The paniolo-scan skill runs npx --yes @paniolo/cli scan --format json and presents dimension scores. It does not edit the repo. Ask for paniolo-scan-remediate when you want fixes applied and the scan re-run. If the agent can't find the skill, confirm with npx skills add paniolo-ai/skills --list, and on Windows or Docker prefer --copy over symlinks.

Claude Code plugin (slash command)

/plugin marketplace add https://github.com/paniolo-ai/skills /plugin install paniolo-scan@paniolo-ai /paniolo-scan

Same read-only flow as the paniolo-scan skill. This channel does not go through skills.sh.

Security findings

npx @paniolo/cli scan --fail-on warn # surface guardrail findings prominently

Security-hygiene and posture findings appear in the guardrails dimension. A repo can score well overall and still carry a warning there, so gate on warn when security matters most.

The remediation loop

Scan, then present. The CLI and the paniolo-scan skill stop there. paniolo-scan-remediate applies the band of findings you choose and re-runs the scan so you can see the score move. The scanner itself never writes — if a fix appears without that skill or your own edit, file a bug.

CI Cookbook

Gate every PR

Any CI system that has Node.js can run the scan as one step:

npx --yes @paniolo/cli scan --format json --fail-on error

Exit codes are stable: 0 clean, 1 findings at/above threshold. The JSON report is a versioned interface — archive it as a build artifact and diff scores over time.

Pre-commit variant:

# .husky/pre-commit (or any hook runner) npx --yes @paniolo/cli scan --fail-on error || exit 1
Privacy & Data Boundaries

What it reads, what it never does

SurfaceReadsWritesNetwork
Default scanRepo files (guidance, configs, CI workflows, source for boundary rules)NothingNone — fully offline
--external-links (opt-in)The same filesNothingRequests to the external URLs found in your guidance, to check they resolve
  • The scan sends no telemetry and makes no model calls.
  • Remediation file writes happen only in your agent, in your working tree, on your instruction — never in the scanner.
Troubleshooting

When something looks wrong

SymptomLikely cause / fix
"harnesses": [] but I use CursorDetection is filesystem-based (.cursor/ dir or chat.agentSkillsLocations in .vscode/settings.json). Global/user-level config isn't repo evidence — commit the repo-level surface.
A flag from these docs errors as unknownYou're on an older published version. Run npx @paniolo/cli@latest scan --help and compare.
invalid value 'cursor,codex' for '--harness'Repeat the flag instead of listing names: --harness cursor --harness codex.
Score seems harsh / lenientRead the per-dimension passedRules/applicableRules — the score is a pass ratio, not a penalty pile. Then see how thresholds are derived.
Two runs differScans are deterministic for an unchanged tree — diff the tree first. With --external-links, a site that was briefly down can also change the result.
FAQ

Objections, answered

Does scan modify my repo?
No. scan is diagnostic only: no scaffolding, no autofix, no writes. That's a product boundary, not a missing feature — it's what makes the scan safe to run on any repo, including ones you don't own. Setting up a harness is a separate command, paniolo init, which does write files.
Does scan use an AI model?
No. Every finding comes from a deterministic rule that runs locally.
Who picked these thresholds?
Documented derivations with research anchors, locked by calibration fixtures in CI — the full methodology is published on the calibration page.
How is this different from AgentLint / agnix / AgentLinter?
Fair comparison, including what each does better than us, on the compare page.
Skill vs. slash command vs. CLI?
CLI for CI/headless; skill for every agent via skills.sh; plugin for the native Claude Code command. See the install matrix above.
What's next — goodwill, stated plainly

paniolo scan and the remediation prompts are free to use. Each finding says what to change and why, so you can fix it yourself or hand it to your coding agent.