paniolo-scan

Scan a repository for AI harness performance — how well your repo is set up for coding agents across Copilot, Cursor, Codex, Antigravity, Claude Code, and Gemini.

New here? Read Intelligence layer and meta-harness — what a meta-harness is, why your repo needs one, how this scan connects to Paniolo, and where the open-source workflow fits.

100% diagnostic. Reports findings only — no scaffolding, autofix, or file writes.

npx @paniolo/scan

Goodwill service

@paniolo/scan and these remediation prompts are a free community starting point. Self-service AI fixes will not match a human-tuned intelligence layer — Paniolo's professional services are recommended for production-grade work. The free tier stays genuinely useful; this is honest guidance, not a gate.

Cursor

Install the paniolo-ai/scan skill to run the scan from Cursor Agent and optionally remediate findings:

1. npx skills add paniolo-ai/scan -a cursor
2. In Agent chat: "Use the paniolo-scan skill to scan this repo and summarize findings."

Filter Cursor-specific rule output: npx @paniolo/scan --harness cursor.

Quick start

# Scan the current directory
npx @paniolo/scan

# JSON for CI
npx @paniolo/scan --format json

# Filter by harness
npx @paniolo/scan --harness cursor,codex

# Scan another repo path
npx @paniolo/scan ../songshare-effect

# Gate CI: exit 1 when findings at or above a severity exist
npx @paniolo/scan --fail-on error

# Opt-in, local-only Session Analysis (deterministic, no LLM, no network)
npx @paniolo/scan --session-analysis

Session Analysis (your pain, in your own words)

--session-analysis mines this repo's local Claude Code session transcripts to show what you keep re-typing — recurring instructions, rules you correct the agent on despite them being in your CLAUDE.md, friction hotspots, and missing-rule suggestions ("you typed this across N sessions but it isn't in your committed guidance"). It is deterministic and LLM-free, reads only your local logs for this repo (never other projects, never repo contents), never runs in CI, and does not affect the scan score. Prompt snippets are redacted by default; add --include-raw-snippets to reveal them. See docs/architecture.md.

Fenced AI review (Semantic checks via an LLM subagent)

1. Emit the tasks:

   npx @paniolo/scan --emit-ai-tasks > paniolo-ai-tasks.json

2. Manual LLM execution: Drop paniolo-ai-tasks.json into an LLM session (ChatGPT, Claude, Cursor) with this prompt:

   "Please act as the AI reviewer: read the tasks in this JSON, perform the semantic analysis described in each prompt, and save your findings to a new paniolo-ai-results.json matching the exact schema required."

3. Ingest the results:

   npx @paniolo/scan --ingest-ai-results paniolo-ai-results.json

Documentation

• Intelligence layer and meta-harness — why meta-harness infrastructure matters, open-source scan/workflow, and Paniolo
• Overview — problem, scope, supported harnesses
• Meta-harness model — what “good” means, evaluation dimensions, calibration
• Harness analysis — sharing vs unique guidance, per-harness scores
• Full-spectrum roadmap — implementation path for intelligence-layer scanning
• Architecture — pipeline, rule model, roadmap
• Rules catalog — built-in rules by dimension and status
• Competitive analysis — landscape, AgentLint reuse, ideas
• Distribution and remediation — diagnostic core plus an optional agent-driven fix adapter
• CI integration — exit codes and the reusable paniolo-ai/scan GitHub Action
• npm publishing steps — release runbook for publishing npx @paniolo/scan
• npm packaging and privacy — publishing npx @paniolo/scan without publishing packages/scan/src/
• Diagrams — Mermaid conventions for docs

Development

npm install
npm run build
npm test
npm start

License

MIT