# KyaniteLabs/checkyourself [Health: Active] **Category:** ๐Ÿ”’ Security **Repository:** https://github.com/KyaniteLabs/checkyourself **GitHub Stars:** 5 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/kyanitelabs-checkyourself ## Description Local-first production-readiness audit for AI-built apps: read-only checks, an evidence-based 0-100 score, and guided fixes before launch. ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "checkyourself": { "command": "npx", "args": ["-y","kyanitelabs-checkyourself"] } } ``` ## Documentation & README # CheckYourself 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. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Model-agnostic](https://img.shields.io/badge/AI-model--agnostic-blue.svg)](#works-with-every-ai-coding-tool) [![Production-hardening engine](https://img.shields.io/badge/engine-19%20capabilities-blueviolet.svg)](90_ADVANCED/) [![Read-only by default](https://img.shields.io/badge/safety-read--only%20first-brightgreen.svg)](#is-it-safe-to-run-on-my-codebase) **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 2026-09-05 retrofit checkpoint is backed by **150 tests and 88 subtests**, and `python3 tools/validate_public.py .` passes. These are repository checks, not a production-safety certification. --- ## Table of contents - [What is CheckYourself?](#what-is-checkyourself) - [Why it exists](#why-it-exists) - [Get started](#get-started) - [What it produces](#what-it-produces) - [Verifier-owned challenge runner](#verifier-owned-challenge-runner) - [What it checks](#what-it-checks) - [Works with every AI coding tool](#works-with-every-ai-coding-tool) - [Who it is for](#who-it-is-for) - [How it works](#how-it-works) - [Optional local CLI](#optional-local-cli) - [Optional visual dashboard](#optional-visual-dashboard) - [Token efficiency by design](#token-efficiency-by-design) - [Safety model](#safety-model) - [FAQ](#faq) - [License](#license) --- ## What is CheckYourself? 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`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/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. --- ## Why it exists 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. --- ## Get started 1. Download or clone this repository. 2. Put the `checkyourself` folder in or next to your project. 3. Point your AI coding assistant at the folder as its **operating context**. Start at [`CONTEXT.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/CONTEXT.md) โ€” it routes the agent through each stage without loading the whole repo. New to the system? Read [`START_HERE.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/START_HERE.md) first. 4. Run a read-only diagnostic and review the **Production Reality Report**. 5. Approve fixes one at a time or in safe, reversible batches. 6. Recheck and rescore after each batch. 7. 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. 8. Get a custom learning plan based on the actual gaps. > **No model lock-in. No required cloud account. No required command line.** ### Direct your assistant Once the folder is in place, tell your AI assistant how to operate within it: ```text 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. ``` --- ## Visual workflow ![CheckYourself user workflow: add the folder, run the audit, review the backlog, approve fixes, verify, repeat, and learn](https://raw.githubusercontent.com/KyaniteLabs/checkyourself/HEAD/assets/checkyourself-user-workflow.png) ```text Add the folder โ†’ run the audit โ†’ review the full backlog โ†’ approve fixes โ†’ verify โ†’ repeat โ†’ learn what you missed ``` CheckYourself 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. --- ## What it produces Default outputs (see a real example in [`samples/sample-production-reality-report.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/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](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/docs/checkyourself-score-explained.md)). - **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. ## Verifier-owned challenge runner 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 ASTRA adversarial review found eight findings and the retrofit closed them; the evidence trail is [`ASTRA-REVIEW.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/_retrofit-2026-09-04/ASTRA-REVIEW.md) and [`ASTRA-FIX-REPORT.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/_retrofit-2026-09-04/ASTRA-FIX-REPORT.md). --- ## What it checks 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/`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/90_ADVANCED/), but users do not need to read it first. --- ## Works with every AI coding tool 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/`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/06_ADAPTERS/README.md). --- ## Who it is for 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. --- ## How it works 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: 1. **Project context** โ€” the agent maps what your app does and detects the stack. 2. **Run diagnostic** โ€” a read-only sweep produces the Production Reality Report and score. 3. **Guided fix mode** โ€” you approve fixes in safe batches; the agent applies and verifies them. 4. **Learning plan** โ€” the agent writes a plan from the real gaps it found. 5. **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/`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/90_ADVANCED/) deepens any stage when a domain warrants it. --- ## Optional local CLI For a zero-token head start, CheckYourself ships a small **optional** scan & scaffold CLI โ€” standard library only, no network, no secret values printed: ```bash python3 tools/checkyourself.py /path/to/your/project ``` It 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`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/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`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/docs/cli.md), [`docs/mcp.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/docs/mcp.md), and [`docs/agent-access-cli-plan.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/docs/agent-access-cli-plan.md). --- ## Optional visual dashboard 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: ![CheckYourself dogfood dashboard showing the self-audit score, launch status, risk counts, and coverage sweep](https://raw.githubusercontent.com/KyaniteLabs/checkyourself/HEAD/10_DASHBOARD/output/checkyourself-dogfood-dashboard-live-20260612.png) After the report exists, say either: ```text dashboard yes ``` The 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: ```text dashboard inline ``` or: ```text dashboard inline ``` The first creates one self-contained HTML/CSS file. The second returns the compact Markdown dashboard shape instead of creating a file. Dashboard files: - [`10_DASHBOARD/README.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/10_DASHBOARD/README.md) - [`10_DASHBOARD/dashboard-data-contract.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/10_DASHBOARD/dashboard-data-contract.md) - [`10_DASHBOARD/inline-dashboard.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/10_DASHBOARD/inline-dashboard.md) - [`10_DASHBOARD/dashboard-prompt.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/10_DASHBOARD/dashboard-prompt.md) - [`10_DASHBOARD/dashboard-template.html`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/10_DASHBOARD/dashboard-template.html) --- ## Token efficiency by design 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. See [`docs/token-efficiency.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/docs/token-efficiency.md). --- ## Safety model **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. --- ## FAQ ### What is CheckYourself in one sentence? 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. ### Do I need to install a toolchain or use the command line? 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. ### Which AI tools does it work with? Any model-agnostic assistant that reads text or files, including Cursor, Windsurf, GitHub Copilot, Codex, ChatGPT, Claude, Gemini, Replit, Lovable, Bolt, and local agents. ### Is it safe to run on my codebase? 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. ### How is it different from a linter or a "top issues" tool? 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. ### What does the Production Reality Score mean? It is a bounded 0โ€“100 evidence score with severity caps and explicit reasoning, explained in [`docs/checkyourself-score-explained.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/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. ### How does the challenge runner establish evidence? 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. ### Does the local integrity HMAC prove independent issuance? 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. ### Is CheckYourself free and open source? Yes โ€” it is released under the [Apache License, Version 2.0](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/LICENSE) and is free to use, copy, and adapt under those terms. ### Who is it for? 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. --- ## Contributing Issues and pull requests are welcome. See [`CONTRIBUTING.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/CONTRIBUTING.md) and the [`CHANGELOG.md`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/CHANGELOG.md) for project history. --- ## License Apache License, Version 2.0 โ€” free and open source. See [`LICENSE`](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/LICENSE). ## What is CheckYourself? **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** | [GitHub](https://github.com/KyaniteLabs/checkyourself) ยท [Forgejo](https://git.kyanitelabs.tech/KyaniteLabs/checkyourself) | | **Keywords** | AI app completion evidence, verifier-owned challenge, pre-launch review | ## Who it's for - 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 ## FAQ ### What is CheckYourself? 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. ### Who should use CheckYourself? founders and engineers shipping AI-generated apps. ### How is CheckYourself different? 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. ### Is CheckYourself production software? Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use. ## Status - Maintained as of 2026 on the default branch - Prefer release tags when pinning dependencies - Report issues on the canonical remote listed above ## Agent surface - 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 ## Contributing Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths. ## License See [LICENSE](https://github.com/KyaniteLabs/checkyourself/blob/HEAD/LICENSE) in this repository (or package metadata if license is package-only).