This MCP server exposes a read-only, local-only CheckYourself audit toolkit for inspecting AI-built projects, scoring evidence, and validating review artifacts.
Describe capabilities: return the machine-readable CheckYourself capability manifest without scanning a project.
Scan a project: inspect a local project for stack, scripts, CI, tests, env/secrets risks, findings, and scan limits; optional deep checks.
Emit coverage skeleton: return the 20-surface coverage template for manual evidence entry.
Check coverage: validate coverage objects for required surfaces, statuses, evidence, missing-evidence notes, and N/A reasons.
Issue verifier receipts: hash an in-root registered verification artifact and return a verifier receipt inline.
Score findings: compute a deterministic Production Reality Score from findings and optional coverage, including caps, penalties, confidence, and manual evidence gaps.
Rank backlog: normalize findings into a complete severity/category/ID-ordered remediation backlog.
Get next approval batch: return up to three highest-severity unresolved findings for the next fix batch.
Diff findings: compare old/new findings artifacts and flag regressions, transitions, evidence changes, and count deltas.
Validate artifacts: validate inline JSON against bundled CheckYourself schema kinds.
Get schemas: return bundled JSON schemas so agents can inspect expected fields before producing artifacts.
All tools are read-only by default, operate on local inputs only, require no authentication, make no network calls, do not modify files, and have no external rate limits; MCP results are returned as JSON without writing generated files or applying fixes.
Integrates with GitHub Copilot to provide pre-launch production-readiness audits for AI-built applications, leveraging file-reading capabilities for diagnostics.
Allows Replit users to run CheckYourself audits directly in the Replit environment, using its file-aware agents to perform read-only production checks.
For AI app builders, CheckYourself runs local challenges to test claimed work, record evidence, and expose risks. Score is not a guarantee.
Check yourself before you wreck yourself — for the apps you ship. Before you launch it, CheckYourself.
CheckYourself is a free, open-source, model-agnostic completion-evidence workflow for apps built with AI coding assistants. It turns any AI assistant — Cursor, Claude, ChatGPT, Gemini, Copilot, Windsurf, Replit, Lovable, Bolt, Codex, or a local agent — into a pre-launch reviewer that inspects your app, records observed and untested behavior, runs verifier-owned challenges, surfaces production gaps, proposes fixes for your approval, verifies local receipts, and writes a learning plan built from the exact gaps your own project had.
Under the hood it is a staged engineering system, not a single canned prompt: an ICM-style context workspace that routes the agent through each stage, an evidence-based 0–100 scoring method with severity caps, verifier-owned challenges across 20 canonical surfaces and 10 scored categories, a 19-capability production-hardening engine spanning auth, data, secrets, CI/CD, observability, privacy, and AI governance, JSON output schemas, report and risk templates, and a public validation suite. You install it as your AI assistant's operating context — no SaaS, no account, no lock-in to any one model.
The repository is backed by 152 tests and 88 subtests — re-verified 2026-10-27: python3 -m unittest discover -s tests is all green (python3 -m pytest tests/ -q reports 152 passed) — and python3 tools/validate_public.py . passes. These are repository checks, not a production-safety certification.
Related MCP server: Architect-to-Product (A2P)
CheckYourself is an open-source reviewable completion-evidence system — a structured, staged engineering framework of context files, scoring logic, output schemas, templates, and production-hardening guidance. It records what was observed, what was inferred, what remains untested, and which risks still block launch; its verifier executes committed local challenges, rechecks stored executed receipts at score time, and validates report verdict consistency. It does not certify production safety or provide independent external custody of the evidence.
It answers one question that matters to every "vibe coder," indie hacker, and AI-assisted builder: "Is this app actually ready to ship, and if not, what exactly is wrong and how do I fix it?"
Unlike a "top three issues" linter, CheckYourself builds a complete findings register and a complete remediation backlog, produces a bounded 0–100 evidence score, and walks you through fixes one safe, reversible batch at a time. When the audit is done, it generates a bespoke learning plan so you actually learn from what your project was missing. The score remains scoped evidence, not a production-safety guarantee.
It is also organized as an ICM-style context workspace: CONTEXT.md routes the agent to staged folders, each major stage has its own CONTEXT.md, and durable handoff artifacts belong in stage output/ folders. CheckYourself is not affiliated with the RinDig ICM project; it uses the same file-first idea so agents know what to read, do, and produce at each step.
Apps built fast with AI tools tend to look finished long before they are safe to launch. The gaps are usually invisible from the happy path: missing auth checks, unvalidated inputs, leaked secrets, no backups, no rollback, no tests, no rate limits, no error tracking.
CheckYourself gives you reality before production does the grading — a calm, complete, plain-English second pass that any AI assistant can run on your behalf.
Download or clone this repository.
Put the checkyourself folder in or next to your project.
Point your AI coding assistant at the folder as its operating context. Start at CONTEXT.md — it routes the agent through each stage without loading the whole repo. New to the system? Read START_HERE.md first.
Run a read-only diagnostic and review the Production Reality Report.
Approve fixes one at a time or in safe, reversible batches.
Recheck and rescore after each batch.
Continue until every finding is fixed or proven not applicable; keep deferred, accepted-risk, and suppressed items visible as residual risk with owner and trigger context.
Get a custom learning plan based on the actual gaps.
No model lock-in. No required cloud account. No required command line.
The deterministic interface — the local CLI and the stdio MCP server — is also published as an npm package that wraps the same stdlib-only Python tool (Python 3 required; Node is only used to launch it):
npm install @puenteworks/checkyourself
npx @puenteworks/checkyourself --help # same CLI as python3 tools/checkyourself.py
npx @puenteworks/checkyourself mcp # stdio MCP server (11 tools)The full audit workspace (this repository) remains the operating context your AI assistant loads; the npm package delivers the machine interface.
Once the folder is in place, tell your AI assistant how to operate within it:
Use the checkyourself folder as your operating context.
Start with a read-only diagnostic.
Do not make code changes until I approve a specific fix.
Generate the dashboard only if I say `dashboard yes` or `dashboard inline`.
After the diagnostic, create a learning plan based on the gaps you found.
Add the folder → run the audit → review the full backlog → approve fixes → verify → repeat → learn what you missedCheckYourself is not a "top three issues" tool. It creates a complete findings register and a complete remediation backlog. The first approval batch is intentionally small so fixes stay safe, understandable, and reversible.
Default outputs (see a real example in samples/sample-production-reality-report.md):
Project Map — what your app appears to do.
Detected Stack — framework, database, auth, hosting, tests, deployment signals, and confidence.
Production Reality Score — a 0–100 score with caps and reasoning (how the score works).
Coverage Sweep — every relevant production surface marked Pass, Finding, Unknown, or Not applicable.
Complete Findings Register — every discovered risk, not just the obvious ones.
Complete Remediation Backlog — every finding and blocking unknown in a deterministic severity, category, and finding-ID order.
Highest-Severity Approval Batch — a small unresolved slice for review, not the whole scope. The local CLI does not infer safety, dependencies, coupling, or blast radius; the diagnostic and human approval gate still do.
Guided Fix Loop — approve, fix, verify, rescore, repeat.
Bespoke Learning Plan — what to learn next based on what your own app was missing.
Optional output:
Human Audit Dashboard — one self-contained HTML/CSS dashboard that visualizes the score, risks, backlog, coverage, status, and learning plan. It is optional because dashboards use extra tokens. Ask for it with dashboard yes, or use dashboard inline for the compact Markdown fallback.
The challenge verb executes the committed .checkyourself/challenges.json definitions against the project under review. The runner accepts argv-only commands, applies bounded timeouts, and treats a failed or timed-out challenge as a fail-closed finding. The verifier owns the execution receipt: a successful EXECUTED receipt is the only class eligible for full credit; caller-issued receipts remain explicitly UNVERIFIED and are capped.
At score time, stored executed receipts survive only a fresh verifier run that agrees on the exit state, success assertions, source and challenge bindings, and a semantic output digest. The digest normalizes volatile durations, timestamps, and paths while the raw capture hash still detects edits. Verifier-owned per-surface minimum contracts reject or cap semantic vacuity such as true, false, echo-only or print-only commands, hollow test-runner output, and trivial regexes.
The local integrity HMAC is project-local tamper evidence. It is not proof of independent issuance, operator identity, or external custody; externally controlled custody is future work. --claim records the accepted completion claim and labels evidence rows as claim-bound or unbound. Report validation labels schema validity separately from semantic verdict consistency and recomputes the verdict rather than trusting the supplied score.
The adversarial review found eight findings and the retrofit closed them; the review and fix reports are not included in this repository.
The diagnostic sweeps the whole relevant production surface:
product purpose, users, and harm model;
frontend UX, accessibility, and client safety;
API/backend behavior, validation, uploads, and webhooks;
auth, permissions, sessions, roles, and admin paths;
data storage, migrations, backups, and tenant/user isolation;
secrets, environment variables, and runtime configuration;
tests, quality gates, and regression coverage;
CI/CD, supply chain, dependencies, and release safety;
deployment, rollback, hosting, and environments;
observability, logs, errors, alerts, and incident response;
performance, scaling, caching, and rate limits;
privacy, compliance, data retention, and consent;
AI/RAG/agent governance when applicable.
The full technical engine lives in 90_ADVANCED/, but users do not need to read it first.
CheckYourself is model-agnostic and ships as plain Markdown, so it runs in any AI assistant that can read text or files:
Category | Tools |
AI IDEs & editors | Cursor, Windsurf, GitHub Copilot, Codex |
Chat assistants | ChatGPT, Claude, Gemini |
App builders | Replit, Lovable, Bolt |
Local & custom agents | any local model or agent that reads files |
Tool-specific setup guides live in 06_ADAPTERS/.
CheckYourself is for people who build with AI and want reality before production does the grading:
beginners learning by doing;
intermediate builders who can ship but want a safer second pass;
experienced developers who want a reusable audit context;
AI-built app learners and community builders;
Cursor, Windsurf, Replit, Lovable, Bolt, ChatGPT, Claude, Gemini, Codex, and local-agent users;
founders, freelancers, agencies, and teams preparing real launches.
CheckYourself runs as a staged workflow, each stage with its own context file so your AI tool always knows what to read, do, and produce:
Project context — the agent maps what your app does and detects the stack.
Run diagnostic — a read-only sweep produces the Production Reality Report and score.
Guided fix mode — you approve fixes in safe batches; the agent applies and verifies them.
Learning plan — the agent writes a plan from the real gaps it found.
Dashboard (optional) — a self-contained HTML or inline Markdown view of everything.
Each stage is defined by its own context files, scoring rules, schemas, and templates — so the agent always knows what to read, what to do, and what to produce. The advanced engine in 90_ADVANCED/ deepens any stage when a domain warrants it.
For a zero-token head start, CheckYourself ships a small optional scan & scaffold CLI — standard library only, no network, no secret values printed:
python3 tools/checkyourself.py /path/to/your/projectIt detects your stack, flags obvious deterministic risks (possible hardcoded secrets, a committed .env, missing .env.example, absent tests or CI) ranked P0–P3, and writes a pre-filled context file your AI can build on. Add --json for a machine-readable summary, --format json --no-write for JSON stdout, or --ci to use it as a lightweight pipeline gate (non-zero exit on a P0). The challenge verb executes committed challenge definitions; score re-executes stored executed receipts; validate --kind report separates schema validity from semantic verdict consistency. The CLI is a scaffold for discovery, not a production-safety certification. See docs/cli.md.
The CLI is the canonical local engine, and CheckYourself also ships a thin local stdio MCP wrapper for native-agent clients. There is no hosted API for the current open-source product. See docs/cli.md, docs/mcp.md, and docs/agent-access-cli-plan.md.
The Markdown report is the default output because it is cheaper, faster, and easier for most AI tools to produce.
This repository includes a real dogfood dashboard screenshot from CheckYourself auditing itself:
After the report exists, say either:
dashboard yesThe AI creates one self-contained HTML/CSS dashboard from the report — it should not re-run the audit just to make the dashboard. If you do not want HTML, ask for:
dashboard inlineor:
dashboard inlineThe first creates one self-contained HTML/CSS file. The second returns the compact Markdown dashboard shape instead of creating a file.
Dashboard files:
CheckYourself uses progressive context loading so audits stay affordable even on large projects:
Start with the stage context and coverage matrix.
Load advanced files only when a domain is relevant.
Keep the complete findings register compact.
Expand details for P0/P1 items and the next approval batch.
Do not paste long source files, logs, or reference docs back to the user.
Generate the HTML dashboard only when the user asks for it.
Start read-only. CheckYourself inspects, explains, and recommends before any code or config changes happen. Fixes require explicit user approval, are applied in small reversible batches, and are re-verified and re-scored after each batch. This is the single most important rule in the system.
CheckYourself is a free, open-source, model-agnostic review workflow that turns any AI coding assistant into a reviewer of completion evidence for AI-built apps — a staged diagnostic workspace, verifier-owned challenges, a bounded evidence-based score, a complete findings register and remediation backlog, approval-based guided fixes, and a 19-capability hardening engine that surfaces gaps, explains the risks, and teaches you what remains unproven.
No build step, no dependencies, and no required command line. You load CheckYourself as your AI assistant's operating context and it works through the stages with you. It also ships a small optional Python CLI and validator for maintainers and agent workflows, but you never need them to run an audit.
Any model-agnostic assistant that reads text or files, including Cursor, Windsurf, GitHub Copilot, Codex, ChatGPT, Claude, Gemini, Replit, Lovable, Bolt, and local agents.
Yes. CheckYourself starts read-only by default. It will not change code or configuration until you approve a specific, reversible fix, and it re-verifies after every batch.
A linter flags style and a few obvious problems. CheckYourself builds a complete findings register and remediation backlog across the entire production surface — auth, data, secrets, CI/CD, deployment, observability, privacy, and more — then guides fixes and produces a learning plan.
It is a bounded 0–100 evidence score with severity caps and explicit reasoning, explained in docs/checkyourself-score-explained.md. A low score with clear unknowns is more useful than a falsely high one; the score is not a production-safety guarantee.
The challenge verb executes committed argv-only definitions from .checkyourself/challenges.json with timeouts and fail-closed results. Only verifier-executed EXECUTED receipts can receive full credit. The scorer re-executes stored receipts and compares exit state, assertions, and a normalized semantic output digest; caller-issued receipts are UNVERIFIED and capped.
No. It detects tampering with project-local challenge receipts. It does not prove independent issuance, operator identity, or external custody; externally controlled custody is future work.
Yes — it is released under the Apache License, Version 2.0 and is free to use, copy, and adapt under those terms.
Vibe coders, indie hackers, beginners learning by doing, intermediate builders, experienced developers wanting a reusable audit, and founders, freelancers, agencies, and teams preparing real launches.
Issues and pull requests are welcome. See CONTRIBUTING.md and the CHANGELOG.md for project history.
Apache License, Version 2.0 — free and open source. See LICENSE.
Relicensing note (dated): GitHub release v1.4.2 (published 2026-05-29) shipped an MIT LICENSE and a release body that said “MIT licensed”. From v1.7.0 (published 2026-06-13) onward, including current HEAD, the project is Apache-2.0. Copies obtained under MIT remain under MIT; Apache-2.0 §4 notice and attribution obligations apply to copies obtained under Apache-2.0. This note does not change any grant.
CheckYourself is a local-first completion-evidence review system for apps built with AI that helps founders and engineers shipping AI-generated apps test claimed work with verifier-owned challenges, record evidence, and surface unresolved risk.
Product | CheckYourself |
Category | Local-first completion-evidence review for apps built with AI |
Best for | founders and engineers shipping AI-generated apps |
Not | a generic linter or code formatter |
Source | |
Keywords | AI app completion evidence, verifier-owned challenge, pre-launch review |
Primary: founders and engineers shipping AI-generated apps
Use when you need to test claimed work with evidence-backed findings and a fix path
Skip if you need a generic linter or code formatter
CheckYourself is a reviewable completion-evidence workflow for AI-built apps. It helps founders and engineers record observed behavior, unresolved assumptions, evidence-backed findings, and a bounded score with a fix path.
founders and engineers shipping AI-generated apps.
Unlike style linters, CheckYourself records reviewable evidence and unresolved risk, not only style. It does not replace production tests, expert review, or independent external custody of the original completion claim.
Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.
Maintained as of 2026 on the default branch
Prefer release tags when pinning dependencies
Report issues on GitHub
Coding agents: read this README first, then repo docs/AGENTS.md if present
Prefer machine-readable briefs (llms.txt) when the repo ships one
MCP or skill entrypoints are documented in-repo when applicable
Issues and PRs welcome on GitHub. Keep public docs free of secrets and machine-local paths.
See LICENSE in this repository (or package metadata if license is package-only).
Normalize inline findings and return the complete remediation backlog sorted by severity, category, and finding ID. The highest_severity_batch is a deterministic severity slice; safety and dependency analysis are not performed. Each item includes fix summary, order rationale, verification, rollback idea, learning value, and status. This recommends work only; it does not modify files or mark findings resolved. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: findings (required). Returns: Backlog result using schema checkyourself-backlog/1.
Validate an inline CheckYourself coverage object for required surfaces, valid statuses, reviewed evidence, missing-evidence notes, and not-applicable reasons. Returns errors and warnings; it does not calculate a score. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: coverage (required). Returns: Coverage completeness result using schema checkyourself-coverage-check/1.
Return the 20-surface CheckYourself coverage skeleton that an agent fills with manual evidence, missing-evidence notes, and not-applicable reasons before coverage-backed scoring. In MCP mode this only returns the skeleton object; it does not create a file. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: project. Returns: Coverage skeleton using schema checkyourself-coverage/1.
Return CheckYourself's machine-readable capability manifest: CLI commands, MCP transport, schema names, scoring weights, score caps, coverage surfaces, exit codes, and public-repository scope guardrails. This is a read-only discovery tool and does not scan a project. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: no named parameters. Returns: Capability manifest using schema checkyourself-capabilities/1.
Compare two inline findings artifacts (scan results, reports, or finding lists) and return added, resolved, unchanged, status and severity transitions, evidence-level changes, severity count deltas, and a regression flag that is true for newly open, reopened, or escalated P0/P1 findings or increased counts. Use this to gate changes against a baseline. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: new (required), old (required). Returns: Diff result using schema checkyourself-diff/1.
Return the next highest-severity unresolved approval batch from inline findings by reusing the backlog ranking rules. The batch contains at most the first three unresolved findings at the highest current severity; safety and dependency analysis are not performed. This is a planning tool only and does not perform fixes. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: findings (required). Returns: Next-batch result using schema checkyourself-next-batch/1.
Issue one verifier-hashed receipt only for an existing, registered surface-specific verification artifact under the configured MCP scan root. The result is returned inline and is not written to disk. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: claim (required), result (required), command (required), reference (required), +4 more. Returns: Verifier receipt using schema checkyourself-receipt/1.
Inspect a local project directory for deterministic production-readiness signals: stack, scripts, CI, tests, environment files, obvious secret/config risks, generated findings, counts, and public-repo claim guardrails. MCP mode returns JSON only; it does not write generated files or apply fixes. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: deep, project, max_files. Returns: Scan result using schema checkyourself-scan/1.
Return a bundled CheckYourself JSON schema by name so an agent can inspect expected fields before producing or validating artifacts. This reads the repository's schema file and returns it; it does not validate an artifact. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: name (required). Returns: The requested bundled JSON schema.
Compute a deterministic Production Reality Score from inline findings and optional coverage evidence. Returns score, raw score, confidence, score mode, severity counts, caps applied, per-category penalties, and manual evidence still needed. MCP mode does not write score history. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: findings (required), claim, coverage. Returns: Score result using schema checkyourself-score/1.
Validate an inline JSON artifact against one bundled CheckYourself schema subset and return validation errors. Supported kinds include scan, coverage, score, backlog, next, diff, report, dashboard, dashboard-data, learning-plan, and capabilities. Requires no authentication. It reads local inputs only, does not make network calls, does not modify local files, and has no external rate limits.
Inputs: kind (required), artifact (required). Returns: Validation result using schema checkyourself-validation/1.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Most tools have clearly distinct roles: scanning, coverage emission/checking, scoring, backlog/next selection, diffing, validation, and schema retrieval. Minor potential overlap exists between 'coverage_check' and 'validate' or 'backlog' and 'next', but descriptions clarify their contexts.
Naming conventions are mixed: several tools use snake_case verb_noun forms ('coverage_emit', 'coverage_check', 'receipt_issue') while others are single words ('describe', 'scan', 'score', 'backlog', 'next', 'diff', 'validate', 'schema'). This inconsistency makes the API feel less cohesive.
Eleven tools is slightly on the higher side for the apparent scope, but each serves a distinct purpose in the analysis workflow. A few could potentially be merged (e.g., 'next' is a filtered view of 'backlog'), but the count is still reasonable and not bloated.
The tool set covers the core workflow: scanning, coverage generation/validation, scoring, backlog management, diffing, artifact validation, and schema access. It lacks an explicit reporting or aggregation tool, but the existing functions seem sufficient for the stated read-only analysis domain.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
