Get started fast.

ProjScan runs entirely on Node.js, with no install scripts and no API key. Call it through npx for a single session, or pin it as a dev dependency in any project.

Requires Node.js 18 or newer (20 or newer for recursive Linux file watching). Works on macOS, Linux, and Windows.

ProjScan ships a small vocabulary that the rest of the page reuses. None of it is jargon for its own sake.

• Semantic graph. An AST-backed map of files, functions, packages, and symbols, with edges for imports, calls, and inheritance. Every other surface reads from it.
• Dataflow. Tracks how values move through the graph: direct, propagated, and bridge source-to-sink risks. Bridge-helper findings auto-block a review.
• Bug-hunt queue. Files ranked by churn and complexity, with the signals behind each score. The first place an agent should look before editing anything.
• Evidence pack. A composed verdict that carries top risks, CODEOWNERS routing, dataflow findings, baseline trend, and the exact next command. What projscan review returns.
• Trust gate. One MCP call that returns proceed, caution, or block before edits, commits, or merges. The agent reads it, the human reads it, both stay in sync.
• Baseline. A local snapshot written after each scan. Later runs report deltas from main, so you see new risk instead of every old finding.

projscan start is the entry path a new agent or human follows on day one. It checks your Node.js version, Git state, package metadata, config, Tree-sitter runtime, plugins, and MCP startup, then returns ready-to-paste recipes for the workflow you are about to run.

ProjScan is an MCP server that exposes forty tools across graph traversal, bug-hunt queues, PR evidence, trust gates, and release readiness. One command wires it into Claude Code, Cursor, Codex, or all of them at once.

If the server does not appear in your client, run projscan mcp doctor --client claude (or cursor, or codex). The doctor compares the installed ProjScan against your client config and prints a corrected, paste-ready snippet.

On any change, projscan review --format markdown writes a PR comment with a single verdict, the top risks, CODEOWNERS-derived routing, the exact next commands, and what shifted from your local baseline. The verdict has three states and is the spine of the comment.

• Proceed. No semantic risks above threshold, no dataflow taints, no failing preflight gates. Cosmetic and stylistic findings still appear as suggestions, not blockers.
• Caution. Scale-only or context-dependent concerns: new hotspots, broad blast radius, dependency advisories below the configured severity, lint or coverage drift. The reviewer is asked to read; nothing is blocked.
• Block. Real semantic risk. Bridge-helper dataflow findings, audit findings above threshold, or any explicit preflight gate that failed with evidence. The comment names the gate, the file, and the next command to run.

CODEOWNERS routing is computed per changed file: which team owns it, who to flag for security review, and which packages cross ownership boundaries in a monorepo. The block list is intentionally small. Borderline cases return caution with a manual-review note rather than fake defects.

Once a single repo runs cleanly, three commands take ProjScan from "useful for me" to "measurable for the team".

projscan init team writes a starter policy file, a GitHub Actions config, CODEOWNERS hints, and a first-run onboarding guide into your repo. The generated policy is yours to edit; CI reads from it on every PR.

projscan trial produces a local adoption-readiness report covering first-run activation, dogfood coverage, feedback summary, market validation, and trust signals. Useful before a wider rollout, and useful again after, so you can measure whether the loop saved time.

projscan dogfood and projscan feedback capture structured reviewer feedback against the PR comment, so claims about value are tied to evidence. A scan only counts as "proven" after repo coverage, three or more useful responses, measured value, false-positive balance, and repeat PR feedback are all present.

Extend the analysis surface with local analyzer and reporter plugins. projscan plugin init scaffolds the project, projscan plugin test runs the validation harness against gallery examples, and the contract is semver-stable.

The full plugin authoring guide lives in the repo.

ProjScan is fully offline by design. Nothing about your repo, your scan, or the graph it builds leaves your machine.

• No source upload. No telemetry. No API key.
• The published npm package has zero install scripts. npm install projscan runs no ProjScan code.
• Every release ships an npm provenance attestation and a CycloneDX SBOM published as a GitHub asset.
• projscan verify-release checks provenance and SBOM against the installed tarball locally. The same validators run as npm run release:check.
• Semantic search uses a local ONNX model that downloads once on first use, then runs entirely on-device.

The trust model is the differentiator, not a footnote.

Most first-run issues land in a handful of buckets.

• MCP server not appearing in your client. Run projscan mcp doctor --client <claude|cursor|codex> for a corrected, paste-ready config snippet. The doctor checks the installed version against your client config and outputs the exact JSON to drop in.
• doctor reports missing Tree-sitter parsers. The bundled parsers cover eleven languages out of the box. A flagged language usually means an installer step was skipped or a network proxy blocked the optional dependency. Re-run install with network access and the language probe will retry.
• Long scan, repeated findings. After the first run, ProjScan writes a local baseline. Later scans report only deltas. If you are seeing every old finding again, delete the baseline and rebuild it with a clean scan.
• Windows path errors. Use forward slashes in projscan start flags, or quote paths with spaces. The CLI normalizes paths internally; the typical cause is shell escaping, not ProjScan.
• Agent ignored the trust gate. The gate is advisory unless the client enforces it. Wire it into your team policy via projscan init team so CI can fail the build when the gate returns block.

For anything else, start with projscan doctor. It prints a focused health check that names the failing subsystem and the next command.