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.
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 warnThese 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.
Choose how to run it
| Channel | Start here | What you get | Best for |
|---|---|---|---|
| Native CLI | Install without Nodepaniolo 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.
Every flag, verified
This table matches paniolo scan --help. A flag that is not listed here is not a scan flag.
| 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. |
--target-for-current-dir | Scan 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-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. |
--internal-wiki | Team flag. Include internal wiki source links in finding evidence. By default only public https:// URLs are printed. |
--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. |
An older binary may lack a flag listed here. npx @paniolo/cli@latest scan --help is the check.
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
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
}
}
} Which mode, when
"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 |
Common flows, end to end
CLI only (no agent)
npx @paniolo/cli scan --format json > paniolo-report.jsonExpected: 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-scanSame 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 prominentlySecurity-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.
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 errorExit 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 1What 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.
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. |
Objections, answered
Does scan modify my repo?
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?
Who picked these thresholds?
How is this different from AgentLint / agnix / AgentLinter?
Skill vs. slash command vs. CLI?
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.