ProjScan · Mission Control

Overview

Version: 5.0.3
Downloads: 20k total
Updated: 19 Jul 2026
Category: Developer Tools / MCP server
Platform: Node.js 18+ (20+ for watch)
Languages: 11 AST adapters / 12 named
MCP tools: 51
MCP registry: io.github.abhiyoheswaran1/projscan
Price: Free (MIT)

ProjScan tells reviewers when to bootstrap, prove, or stop, the local proof layer for code review, whether a person or an AI agent made the change. 5.0.2 keeps a Proof Contract's own scope executable: a prove --intent that describes a dependency or tooling version change (for example "upgrade projscan to 5.0.1") now places package.json and package-lock.json in allowedFiles instead of forbiddenFiles, so an upgrade contract no longer blocks its own intent, and unrelated intents keep the manifests forbidden by default. The same release hardens Baseframe suite interop: ProjScan strips leading ./ prefixes and normalizes separators before it classifies harness evidence, so it recognizes externally supplied changed-file paths (MCP, imported proof) as sanctioned .agentloop/ and .agentflight/ writes; it de-duplicates changed files at intake, so one harness write never counts twice in scope drift; and Team Proof Recipe forbiddenFiles entries carry the same harness guard as contract forbiddenFiles. The 5.0.0 review loops are unchanged: projscan review-gate and projscan proof-broker give reviewers explicit restart loops from the same local review surfaces they already use, and with --bootstrap-contract each command mints the next scoped Proof Contract only when explicitly requested, then returns aligned JSON, console, and PR-comment evidence with bootstrap status, proof debt, reviewer guidance, and next commands. Review Gate reads the proof evidence already on disk, the Proof Contract, the Agent Change Passport, the Proof Broker, the Proof Receipt, the Proof Replay, Proof Sufficiency, and Team Proof Recipes, then returns one reviewer decision: ready, needs-proof, drifted, or blocked, written to .projscan/review-gate.json. Review stays local, bootstrap never runs proof commands implicitly, and MCP continues to return evidence without executing proof. Under it, projscan passport folds a Proof Contract and a Proof Receipt into one Agent Change Passport, and projscan guard runs alongside the session as Live Guard, flagging the moment a change drifts past the approved boundary. The proof loop runs in the CLI: projscan prove --intent writes the contract, projscan prove --run -- <command...> runs a local proof command with shell execution disabled, and projscan prove --changed replays the diff into a Proof Receipt that shows scope, proof freshness, sufficiency gaps, required reviewers, changed-after-proof files, the replay command, and a receipt fingerprint. For a Baseframe Suite task, projscan passport --intent "<text>" --task-id <id> --emit-baseframe exports a stable local .baseframe/evidence/<task-id>/projscan-assessment.json that AgentLoopKit reads to write its task contract and AgentFlight later reads for review readiness; ProjScan depends on neither package and writes none of their artifacts.

Mission Control sits on code intelligence. ProjScan answers from a stable v3 semantic graph of file, function, package, and symbol nodes, plus a dataflow engine that tracks direct, propagated, and bridge source-to-sink risk, all served over MCP. 51 MCP tools span Review Gate, the Proof Broker, the Agent Change Passport, Live Guard, the verified change workflow, executed proof runs, proof-first assessment, change simulation, repo understanding, graph queries, proof workflows, dependency intelligence, PR evidence, trust gates, release readiness, and cross-worktree coordination, across 11 AST adapters covering 12 named languages. Review Gate, the Proof Broker, and the passport tool return evidence and never run local proof commands. It stays local-first: no hosted scanning, no code upload, no ProjScan account, no API key, and telemetry off until you opt in.

Part of Baseframe Labs

Four tools, four questions.

Baseframe Labs is four developer tools, each answering a different question about your work, in the order the work happens. Each one stands on its own.

Three of them, ProjScan, AgentLoopKit, and AgentFlight, also hand off through versioned JSON under .baseframe/. VerisKit verifies a change on its own and needs none of the others.

Features

What it does well.

Proof & Verification

09

Review Gate: projscan review-gate reads the Proof Contract, Agent Change Passport, Proof Broker, Proof Receipt, Proof Replay, Proof Sufficiency, and Team Proof Recipes, then returns one reviewer decision (ready, needs-proof, drifted, or blocked) to .projscan/review-gate.json. With --bootstrap-contract it mints the next scoped Proof Contract only when explicitly asked. It reads evidence and never runs proof commands.
Agent Change Passport: projscan passport writes a Proof Contract and evaluates the working tree in one command, then saves a local passport: approved and forbidden files, changed files, proof replay, Proof Sufficiency, reviewer action, warnings, and next commands.
Live Guard: projscan guard --contract .projscan/proof-contract.json --watch checks the working tree against the saved contract during a session and flags drift the moment the change leaves the approved boundary. --fail-on-drift exits non-zero for CI.
Verified change workflow: The start -> prove -> run -> changed loop: prove --intent writes a Proof Contract, prove --run records the proof, and prove --changed emits a reviewer-ready receipt.
Proof Cards V2: projscan assess --goal names the safest next change and returns Proof Cards: the evidence, the safe change shape, the proving commands, and the risk delta.
Change simulation: projscan simulate --plan predicts the files, tests, contracts, and rollout of a change before you edit, read-only and never inheriting false confidence.
Agent trust gate: One MCP tool returns proceed, caution, or block before edits, commits, and merges, with dataflow risk and collision evidence behind the call.
Proof Broker and PR Passport: projscan proof-broker --contract .projscan/proof-contract.json --pr-comment brokers the proof a change still owes into one reviewer-ready PR comment: the reviewer decision, Proof Receipt evidence, recipe gaps, required reviewers, and a receipt fingerprint. With --bootstrap-contract it mints the next scoped Proof Contract only when asked. Reads evidence; runs no commands.
Readiness evidence: Evidence packs, regression matrices, coverage, and transitive impact compose into one auditable readiness view; mission-proof rolls saved results into pass or fail.

Mission Control

03

Intent routing: projscan start --intent routes a plain-language goal into concrete commands, proof, and handoffs, backed by workplans, agent briefs, and quality scorecards.
Runnable handoffs: start --save-mission <dir> writes a runnable bundle (mission.sh, status.sh, review.sh) so a sleeping or fresh agent resumes without rereading the report.
Adoption layer: projscan start and first-run share one onboarding path: privacy check, orientation, preflight, MCP doctor, then ready-to-paste client configs and the next command.

Code Intelligence

03

Deep graph platform: A stable v3 semantic graph of files, functions, packages, and symbols, plus a dataflow engine tracking direct, propagated, and bridge source-to-sink risk.
Autonomous bug hunt: Risk-ranked bug-hunt queues, hotspot analysis over high-churn and high-complexity files, and semantic search give an agent a prioritized starting point before editing.
Deeper review intelligence: Structural diffs, one-call verdicts with contract-change detection, and auto-blocking taint flows; PR comments carry a Reviewer Decision and the first command to run.

Agent Coordination

02

Multi-agent coordination: Monorepo package intelligence, cross-repo sibling awareness, durable session and feedback memory, and per-call cost budgeting, with coordination hints for the next agent.
Swarm coordination: collisions, claim, and merge-risk coordinate parallel agents across git worktrees with overlap detection, advisory leases, and a safe integration order, no daemon.

Platform & Release

02

Plugin platform: A stable analyzer and reporter plugin contract with plugin init and plugin test; a local plugin runs only after you approve its exact bytes.
Release trust: Release plans, version-tag validation, declared-versus-installed drift, npm audit to SARIF, and a blast-radius preview before any package bump lands.

See it in action

A closer look.

projscan Agent Change Passport showing a drifted billing-retry handoff with approved and forbidden files, changed files, proof replay, Proof Sufficiency, warnings, and next commands. — One local handoff artifact
`npx projscan passport --intent "is my agent allowed to change billing retry logic?" --save-contract .projscan/proof-contract.json --output .projscan/passport.json` packages the approved boundary, changed files, proof replay, Proof Sufficiency, reviewer action, warnings, and next commands into one local handoff artifact.

projscan Live Guard watch output showing a billing-retry change move from clear to drift with reviewer action and next commands. — Catch drift before review
`npx projscan guard --contract .projscan/proof-contract.json --watch` watches the current diff against a saved Proof Contract and catches a change moving from clear to drift before review.

ProjScan Mission Control routing a plain-language goal into a runnable mission with the next command, the proof to run, and a review gate — One goal in, a runnable mission out.
`projscan start --intent "<goal>"` turns a goal into a mission with the next command, the proof to run, and a review gate. `projscan assess` sits beside it, naming the safest next change and the commands that prove it before you edit.

ProjScan Proof Cards from projscan assess: each card names what is risky, why it matters, the safe change shape, the commands that prove it, a confidence read, and the risk delta a fix removes — The evidence behind the safest change
`projscan assess --goal "<goal>"` returns Proof Cards: what is risky, why it matters, the safest change shape, the commands that prove it, a confidence read, a feedback or suppression path, and the risk delta a fix removes. `projscan simulate --plan "<change plan>"` predicts the files, tests, contracts, and rollout steps before you edit.

ProjScan saving a mission bundle, reporting local pass and fail mission proof as Markdown, and resuming start from the saved proof state — Proof you can paste
`projscan mission-proof --mission <dir> --format markdown` prints a paste-ready report of which proof commands passed, which failed, and what the agent still owes. It reads saved bundles locally and never uploads source. Add `--require-passed` to fail a CI step until every selected bundle passes.

ProjScan Proof Router: a next-tool-call MCP payload alongside copyable proof commands, checklist, MCP call, and review-gate shortcuts — Copy the next move
List the shortcut menu, pull the next shell command, fetch the MCP call, or copy the checklist and Markdown runbook without rereading the full report. `--next-tool-call` returns the cursor tool and args as compact JSON; `--review-gate` returns the stop checklist before another slice, release, publish, or deploy.

ProjScan running on a repository: banner, scan progress, and project report — The classic orient flow
`projscan start` still checks your runtime and repo on day one. Lead with `--intent "<goal>"` and the same start command routes a plain-language goal into commands, proof, and handoff surfaces.

Coding agent calling ProjScan tools over MCP in a macOS-style terminal — Built for agents first
Plug ProjScan into any MCP-aware client and the agent reads the repo through a typed, context-budget-aware surface. 51 MCP tools cover Review Gate, the Proof Broker, the Agent Change Passport, executable proof contracts, proof-first assessment, change simulation, intent routing, graph queries, dataflow, proof workflows, PR evidence, trust gates, and swarm coordination, all running locally. Review Gate, the Proof Broker, and the passport tool return evidence and never run local proof commands.

Hotspot analysis ranking high-risk files — Hotspots, ranked by risk
High-churn, high-complexity files rise to the top, each with a risk score and the signals behind it. An agent knows where to look before it touches a line.

Semantic search returning ranked symbols — Semantic search, not grep
Ask for the code that handles auth or talks to the database and get ranked symbols straight from the graph. The local ONNX model runs on your machine, so nothing about the repo leaves it. If the model cannot load, offline or rate-limited, search falls back to BM25 ranking instead of failing.

Custom markdown report produced by a reporter plugin — Shape the output with plugins
The reporter plugin contract turns a scan into whatever your team needs. projscan plugin init scaffolded this custom markdown report; projscan plugin test verified it.

What's new

5.0.2: Dependency-intent contracts keep their manifests in scope.

Ask prove --intent for a dependency or tooling version change, say "upgrade projscan to 5.0.1", and 5.0.2 puts package.json and package-lock.json in allowedFiles instead of forbiddenFiles. The upgrade contract no longer blocks its own intent. Unrelated intents keep the manifests forbidden by default, so a billing-retry contract still catches a stray dependency bump. 5.0.2 also hardens the Baseframe suite interop from 5.0.1, so ProjScan reads sanctioned harness writes as harness evidence rather than scope drift. The 5.0.0 review loops are unchanged: 51 MCP tools, 11 AST adapters covering 12 named languages, explicit bootstrap on proof-broker and review-gate, review stays local, and MCP returns evidence without executing proof.

Upgrade contracts allow their manifests: When the intent describes a dependency or tooling version change, ProjScan now writes package.json and package-lock.json into allowedFiles instead of forbiddenFiles, so an upgrade contract no longer blocks its own intent. Unrelated intents keep the manifests forbidden by default.
Normalized harness paths: ProjScan strips leading ./ prefixes and normalizes separators before it classifies harness evidence, so it recognizes externally supplied changed-file paths (MCP, imported proof) as sanctioned .agentloop/ and .agentflight/ writes. It also de-duplicates changed files at intake, so one harness write never counts twice in scope drift.
The recipe harness guard: Team Proof Recipe forbiddenFiles entries now carry the same harness-path guard as Proof Contract forbiddenFiles. A recipe that forbids .agentloop/** or .agentflight/** no longer flags sanctioned harness evidence as forbidden scope drift.
Sibling harness writes: Proof Receipts still classify sibling Baseframe harness writes (.agentloop/, .agentflight/) as informational harness evidence, and Proof Ledger matching still normalizes package-runner prefixes: npx, npm exec, pnpm exec and dlx, yarn exec and dlx, bunx, and node_modules/.bin.
Explicit bootstrap, unchanged: projscan proof-broker --intent "<text>" --bootstrap-contract and projscan review-gate --intent "<text>" --bootstrap-contract write the next scoped Proof Contract only when you ask for it, then return bootstrap-aware PR Passport output and reviewer guidance. Leave the flag off and ProjScan mints nothing.
Review Gate evidence, unchanged: review-gate --contract .projscan/proof-contract.json --pr-comment prints Review Gate Markdown carrying status, the allow-review decision, reviewer action, proof debt, recontract guidance, bootstrap status when present, required reviewers, next commands, and artifact paths; --ci --fail-on-needs-proof prints a compact CI summary and exits non-zero until the gate is ready. The JSON includes kind: "review-gate", decision, proofDebt, recontract, bootstrap, requiredReviewers, nextCommands, prComment, artifacts, and the embedded Proof Broker report. Artifacts land in .projscan/review-gate.json or .projscan/review-gates/<name>.json, and ProjScan rejects traversal, symlink targets, non-JSON files, and existing files that are not Review Gate artifacts.
MCP and exports: MCP exposes projscan_review_gate, keeping the tool count at 51; it returns gate evidence and does not run local proof commands. MCP still exposes projscan_prove and can create, replay, and record imported proof, while CLI prove --run executes local commands. The package exports computeReviewGate() plus Review Gate report, decision, proof-debt, recontract, artifact, and PR-comment types, and every existing proof workflow (Proof Broker, passport, Live Guard, Proof Ledger, Proof Replay, Proof Sufficiency, Team Proof Recipes, stale, failed, and changed-after-proof handling, and evidence-pack receipt sections) stays independent.

Proof workflows

The proof replay trust loop.

Under the suite export, the proof loop runs end to end: save a Proof Contract, run or record the required proof, replay the final diff, and hand reviewers a receipt that shows scope, proof freshness, sufficiency gaps, required reviewers, and changed-after-proof files. Core scans run locally, source is not uploaded, and telemetry stays off until you opt in.

Richer Proof Replay: projscan prove --changed reports replay status, timeline events, changed-after-proof files, the replay command, and a receipt fingerprint, so a reviewer can see what the proof covered and what shifted after it ran.
Proof Sufficiency: The receipt tells reviewers whether proof is strong, adequate, weak, missing, stale, or failed across the changed risk surfaces, so weak or missing proof is visible instead of assumed.
Team Proof Recipes: .projscanrc.json proofRecipes let teams require path-matched proof commands, reviewers, and forbidden files for sensitive areas, so a change under src/billing/** carries its own proof bar.
PR comments carry the receipt: projscan evidence-pack --pr-comment includes Proof Receipt evidence when available: proof replay, proof sufficiency, recipe gaps, required reviewers, changed-after-proof files, and receipt fingerprints.
Hardened proof reads: Proof Contract and Proof Ledger reads reject symlink escapes, proof logs redact more standalone token and private-key shapes, and saved Mission Control scripts reject shell control syntax before running proof commands.
MCP creates, replays, records: MCP exposes projscan_prove and projscan_passport, with the server now at 51 tools after Review Gate and the Proof Broker. Over MCP an agent can create a Proof Contract, replay the diff, record imported proof, and read passport, broker, and review-gate evidence. Only the CLI prove --run executes local commands.

The loop

Goal, mission, proof, review.

One workflow runs from a plain-language goal to gated evidence. Each step is a command you hand to the next agent.

Route a goal: projscan start --intent "<goal>" infers the workflow and returns an execution plan with a current cursor, route confidence, ready actions, done criteria, proof commands, and a review gate. State the goal; ProjScan picks the tools.
Save the mission: --save-mission <dir> writes a bundle: README, prompts, runbook, task card, review gate, JSON handoff files, proof logs, and executable mission.sh, status.sh, and review.sh. A fresh or sleeping agent resumes from the bundle without rereading the report.
Run and resume proof: mission.sh runs the next steps, status.sh reports where the work stands, and review.sh gates approval. Proof status lands in proof-logs/summary.json, and projscan start --mission <dir> resumes from that saved pass or fail state.
Review the evidence: projscan mission-proof summarizes local proof across one or many bundles: Markdown for humans, JSON for agents. --latest, --all, --needs-attention, --summary, --require-passed, and --write turn saved bundles into release-review artifacts, none of which upload source.

How it works in practice

Practical workflows.

From first clone to a gated production merge.

PR evidence comment: projscan evidence-pack --pr-comment posts a Reviewer Decision (ship, review, or fix-first) with top risks, CODEOWNERS routing for who owns each file, the next commands, and what changed since your local baseline.
Team bootstrap: projscan init team writes a starter policy, a GitHub Action, CODEOWNERS hints, and first-run setup, wiring a new repo in one command.
MCP setup that works: projscan mcp doctor --client claude|cursor|codex checks your config and prints a paste-ready snippet; npx projscan init mcp --client all wires it in one shot. Registry id: io.github.abhiyoheswaran1/projscan.
Trust calibration: Blocks are rare and mean real semantic risk: new bridge-helper dataflow paths, audit findings above threshold, or failing preflight gates. Scale-only concerns return caution with a manual-review note. A local baseline means later runs report deltas, not every old finding.

Stable surface

What 5.x means.

A versioned contract your agents and CI can depend on.

Semver covers: MCP tool names and schemas, CLI commands and documented flags, exit codes, the CLI JSON envelope (schemaVersion 2), the analyzer and reporter plugin contract (schemaVersion 1), and the public API exports.
Consolidated in 4.0: 4.0 removed projscan_explain and projscan_graph after a full deprecation release; projscan_file and projscan_semantic_graph (query mode) replace them. Everything since has been additive, and the 5.0 line continues the same proof-first surface: explicit bootstrap loops on Review Gate and the Proof Broker in 5.0.0, sharper contract scoping and harness-path handling in 5.0.1 and 5.0.2, no tool removals, and every other 2.x, 3.x, and 4.x surface stays.Migration guide: docs/MIGRATION-4.0.md
Languages and runtime: Eleven AST adapters cover twelve named languages: JavaScript and TypeScript share one Babel adapter; Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++ each use a Tree-sitter adapter. Node.js 18+ (20+ for recursive Linux watch), on macOS, Linux, and Windows. Every release ships npm provenance and a CycloneDX SBOM, checked against the installed tarball by the repo maintainer with npm run release:check.
Privacy: Offline by default: no source upload, no API key, telemetry off until you opt in. projscan privacy-check prints what ProjScan can read, write, or contact, and --offline blocks every network surface. Your repo never leaves the machine.

Tell reviewers when to bootstrap, prove, or stop.

Run Review Gate to turn the proof on disk into one reviewer decision (ready, needs-proof, drifted, or blocked), bootstrap the next scoped Proof Contract only when you ask, gate it in CI, broker the remaining proof into a PR comment, write the Agent Change Passport, and guard the session for drift. Bootstrap never runs proof commands implicitly, and Review Gate reads evidence without executing proof. Local-first: no hosted scanning, no code upload, no API key.

Open the Review Gate and bootstrap the next contract

Gate the review in CI

Broker proof into a PR comment

Write the Agent Change Passport

Guard the session for drift

Install from npm

AgentLoopKit

The local control plane for low-token, verifiable agent loops. It owns scope, gates, and completion decisions, with a token receipt on every step.

View

Developer ToolsFree

AgentFlight

agentflight guard watches local trust while your coding agent works; agentflight finish writes the Review Passport that proves the result.

View

Developer ToolsFree

VerisKit

veris runs the test and quality tools you already have, then returns one honest verdict, verified, failed, or partial, plus a PR-ready report.

View

ProjScan

Four tools, four questions.

What it does well.

Proof & Verification

Mission Control

Code Intelligence

Agent Coordination

Platform & Release

A closer look.

One local handoff artifact

Catch drift before review

One goal in, a runnable mission out.

The evidence behind the safest change

Proof you can paste

Copy the next move

The classic orient flow

Built for agents first

Hotspots, ranked by risk

Semantic search, not grep

Shape the output with plugins

5.0.2: Dependency-intent contracts keep their manifests in scope.

The proof replay trust loop.

Goal, mission, proof, review.

Practical workflows.

What 5.x means.

Tell reviewers when to bootstrap, prove, or stop.

AgentLoopKit

AgentFlight

VerisKit