Shadscan inspects a React shadcn app, scores its UI fundamentals from 0 to 100, and shows the evidence behind every finding.

It catches the product details that are easy to postpone: command menus, theme shortcuts, route states, accessible controls, form feedback, metadata, mobile behavior, and more.

The default scan is deterministic and read-only. It does not start the app, edit files, call an AI model, upload source, or require application secrets.

Quick Start

Run Shadscan from the root of a project:

pnpm dlx @shadscan/cli

The project path defaults to the current directory. Pass a path to scan another app:

pnpm dlx @shadscan/cli ../my-shadcn-app

Using npm or Bun:

npx --yes @shadscan/cli
bunx @shadscan/cli

Shadscan requires Node.js 18 or newer. Commands resolve to the latest stable release; prereleases are published under the next tag (@shadscan/cli@next).

Interactive human scans show progress immediately and keep each completed phase above the final report:

✓ Resolving project
✓ Discovering app structure
✓ Evaluating UI rules
✓ Preparing report

JSON, prompt, CI, non-TTY stderr, and --no-interactive output stay quiet. Redirecting stdout keeps the report clean while progress remains on an eligible stderr terminal.

What You Get

Your shadscan score: [###############-] 92/100 (Grade A)
shadscan has entered the chat.

Categories:
  Foundation:           20/20 (100%)
  Interaction:        12.2/20  (61%)
  States:               20/20 (100%)
  Accessibility:        20/20 (100%)
  Forms and Data Entry: 10/10 (100%)
  Production Polish:    10/10 (100%)

Missing: command menu has a Cmd/Ctrl+K shortcut
  Evidence: No complete mounted Cmd/Ctrl+K command-menu shortcut was found.
  Fix: Register a shortcut that prevents the browser default and toggles the menu.

Every report separates:

• Fixes: high-confidence defects with repository-relative evidence.
• Decisions: product choices that should be implemented or explicitly waived.
• Advisories: lower-confidence checks that need rendered or manual verification.
• Not applicable: rules excluded because the relevant UI surface is absent.

Common Commands

# Machine-readable, versioned report
pnpm dlx @shadscan/cli --json

# Paste-ready remediation plan for a coding agent
pnpm dlx @shadscan/cli --prompt

# Explicitly launch an installed agent with the generated plan
pnpm dlx @shadscan/cli --apply --agent codex

# Install the current candidate as an exact CI dependency, then enforce a floor
pnpm add --save-dev --save-exact @shadscan/cli
pnpm exec shadscan --fail-under 80 --no-interactive --no-roast

# Audit one category while investigating a focused area
pnpm dlx @shadscan/cli --category accessibility

Use --format human, --format json, or --format prompt when output selection needs to be explicit.

Pin an exact package version in CI; unqualified commands resolve to the latest stable release. Run pnpm dlx @shadscan/cli --help for every option.

Agent Handoff

--prompt turns the same deterministic report into a neutral, paste-ready plan for another coding agent. The handoff includes:

• prioritized work items grouped as fix, decide, or verify;
• rule IDs, evidence, suggested fixes, and acceptance criteria;
• detected framework, package manager, and source-coverage context;
• repository-owned verification commands that the agent must inspect first;
• the exact pinned Shadscan command to rescan after the work.

--apply is an explicit local action. It validates an installed Claude Code, Codex CLI, or Grok Build executable before launching it. Shadscan itself still does not make an AI request; the selected external agent follows its own provider and approval model.

MCP Server

shadscan mcp serves the same deterministic audit over the Model Context Protocol on stdio, so coding agents can query results as typed tool calls instead of parsing output:

claude mcp add shadscan -- npx -y @shadscan/cli mcp

Three read-only tools: scan (score plus filterable actionables — by category, severity, or workspace package), list_projects (workspace packages with their application-or-library classification), and explain_rule (what one rule checks and where it applies). Every call re-scans the current file state — results are never cached — and every response carries the engine, ruleset, and schema versions. The server scans inside the roots it was started with and nothing else, and it never writes files. Details and per-client setup live in docs/mcp.md.

Before Every Agent Commit

Install the optional AI-agent commit protocol:

npx skills add TheOrcDev/skills --skill shadscan-pre-commit --global

Then ask your agent:

Use $shadscan-pre-commit for this task. Establish the current score before
editing, run Shadscan immediately before every commit, and do not commit if the
audit is unassessed or below the task floor.

The skill governs agent behavior only. It does not install dependencies, configure Git, or add a Husky or native pre-commit hook.

What It Checks

The bundled ruleset contains 59 deterministic checks across six weighted categories.

| Category | Examples | | --- | --- | | Foundation | shadcn config, mounted theme provider, metadata, favicon, not-found and error boundaries | | Interaction | dark-mode and command-menu shortcuts, safe global hotkeys, mobile navigation, focus visibility | | States | loading and Suspense fallbacks, empty states, retryable errors, pending actions, mounted toasts | | Accessibility | names and labels, semantic controls, alt text, landmarks, live regions, keyboard and focus behavior | | Forms and Data Entry | validation, rendered field errors, error associations, legends, button types, autocomplete | | Production Polish | complete metadata, social previews, Button icon spacing, responsive shells, SEO files, mobile overflow |

See the CLI documentation for usage, automation, agent workflows, and every supported option.

Scoring

Raw rule points are normalized within each weighted category to produce the 100-point score.

High- and medium-confidence failures can reduce the score. Low-confidence checks stay visible as score-neutral advisories instead of pretending static analysis can prove rendered behavior.

Rules only run where they apply. Shadscan supports Next.js App Router, Pages Router, hybrid Next.js projects, React Router framework mode, TanStack Start, Laravel with Inertia and React, Astro with React islands, Vite React, and generic React applications.

Privacy And Exit Status

Local scanning is static and stays on your machine.

Findings return exit status 0 unless --fail-under is not satisfied. Discovery, audit, setup, and launched-agent failures return 1. Use --no-interactive for deterministic automation.

Web Scanner And Hosted API

The web scanner audits a public GitHub repository without installing the CLI or exposing an API key to the browser. GitHub access, extraction, rate limiting, and scanning stay on the server.

For agent and service integrations, Shadscan also exposes a versioned hosted API for public GitHub repositories and sanitized gzip tar snapshots.

• Pinned agent instructions
• OpenAPI 3.1 contract
• CLI documentation
• Web scanner

The hosted surfaces are opt-in and have separate source-handling contracts from the local CLI.

Contracts

• Audit JSON uses schema version 4 and is validated by the exported AuditReportSchema.
• Agent prompt output uses prompt version 5.
• Every report identifies the exact bundled ruleset version that produced it.
• RULE_CATALOG exposes immutable rule metadata for integrations.

License

Shadscan is available under the MIT License. The header and badges are rendered by shieldcn, a shadcn-styled badge and README graphics service.