Scan Docs — paniolo scan

60-Second Quick Start

Run it now

# 1. Scan the repo you're in (terminal report)
npx @paniolo/cli scan

# 2. Machine-readable report for CI or tooling
npx @paniolo/cli scan --format json

# 3. Gate on severity (exit 1 when findings ≥ level)
npx @paniolo/cli scan --fail-on warn

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

Three ways in

Channel	Install	What you get	Best for
npm CLI	`npx @paniolo/cli scan`	The diagnostic scanner itself. Zero install, zero writes.	First scan, CI, scripts, headless use
Portable skill	`npx skills add paniolo-ai/scan --all`	A `paniolo-scan` skill in every skill-capable coding agent on your machine (Claude Code, Cursor, Copilot, Codex, Devin, Gemini CLI, and more). Your agent runs the scan, presents scores, and remediates findings you pick.	Widest reach across agents
Claude Code plugin	`/plugin marketplace add https://github.com/paniolo-ai/scan` `/plugin install paniolo-scan@paniolo-ai`	The native `/paniolo-scan` slash command (bundles the skill).	Claude Code users who want the slash command

Skill vs. slash command — two 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 is generated against the CLI's own --help output — if a flag isn't here, it doesn't exist.

Flag	What 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`.
`--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-config`	Fail when the config names an unknown rule id.
`--changed`	Lint 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-links`	Also check external links for dead URLs. The only network check; off by default.
`--print-discovery`	Print detected harnesses and resolved skills directories as JSON, then exit without scanning.
`--print-timing`	Print per-phase and per-rule timing to stderr.
`-h, --help` / `-V, --version`	Show help or the version.

Version note: this reference matches @paniolo/cli 0.5.54. If a flag above is missing from your installed version, run the latest release with npx @paniolo/cli@latest scan . and compare its --help.

Report Reference

Reading the JSON

Field	Meaning
`version`	The CLI version that produced the report.
`totalScore`	0–100 rollup across the core meta-harness dimensions. Grades: excellent ≥ 85, good ≥ 70, fair ≥ 50.
`scoreScope`	Which dimensions the score covers; `"core"` for the deterministic set. Compare scores across repos only within the same scope.
`harnesses`	Tools the repo appears to target, inferred from filesystem signals (e.g. `CLAUDE.md`, `.cursor/`, `.codex/config.toml`).
`metaHarness.dimensions`	Per-dimension `status`/`score`/`grade`. A dimension that did not run has `"status": "not_run"` and a `null` score — never zero.
`sharing`	Shared vs. harness-unique guidance in files, lines, and percent — the cross-harness duplication measure.
`contextBudget`	Estimated 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.
`summary`	Finding counts by severity.
`harnessGapMatrix` / `harnessOptimization`	Capability table and 0–100 optimization score per detected harness, plus each harness's guidance footprint.

Annotated sample (real output)

From an actual @paniolo/[email protected] run against Paniolo's own harness repository:

{
  "version": "0.5.54",
  "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

Do you need a comparable score or a CI gate? └─ yes → FULL SCAN: npx @paniolo/cli scan [--format json --fail-on error] deterministic · offline · byte-for-byte reproducible Do you only need feedback on what changed? └─ yes → CHANGED FILES: npx @paniolo/cli scan --changed falls back to a full scan for global harness and config surfaces Do you want dead external links reported too? └─ yes → NETWORK CHECK (opt-in): npx @paniolo/cli scan --external-links

"Which flags should I use?"

You want…	Run
A first look at one repo	`npx @paniolo/cli scan`
A CI gate that blocks on serious issues	`npx @paniolo/cli scan --format json --fail-on error`
A stricter gate including warnings	`npx @paniolo/cli scan --fail-on warn`
Only Cursor + Codex findings	`npx @paniolo/cli scan --harness cursor --harness codex`
To scan a different directory	`npx @paniolo/cli scan ../other-repo`
Faster feedback on a branch	`npx @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/scan --all
# then, in your agent:
"Use paniolo-scan to scan this repo and summarize findings."

The skill runs npx --yes @paniolo/cli scan --format json, presents dimension scores, surfaces the goodwill framing, then remediates the findings you pick and re-scans. Troubleshooting: if the agent can't find the skill, confirm with npx skills add paniolo-ai/scan --list, and on Windows/Docker prefer --copy over symlinks.

Claude Code plugin (slash command)

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

Same flow as the 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 → present → remediate → re-scan. The CLI diagnoses; your agent (via the skill or slash command) applies fixes in your working tree, then re-runs the scan to verify the score moved. The scanner itself never writes — if a "fix" appears without your agent doing it, 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

Surface	Reads	Writes	Network
Default scan	Repo files (guidance, configs, CI workflows, source for boundary rules)	Nothing	None — fully offline
`--external-links` (opt-in)	The same files	Nothing	Requests 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

Symptom	Likely cause / fix
"harnesses": [] but I use Cursor	Detection 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 unknown	You'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 / lenient	Read the per-dimension `passedRules`/`applicableRules` — the score is a pass ratio, not a penalty pile. Then see how thresholds are derived.
Two runs differ	Scans 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.

Using paniolo scan