Descuff

Turn your existing website into an interface AI agents can understand and use.

Descuff checks a local supported app, tells your coding agent what to add, then proves the before/after improvement.

Your coding agent does the flexible discovery and implementation work. Descuff keeps the process evidence-backed, safety-gated, and validated.

It focuses on practical agent-facing standards: llms.txt, Schema.org JSON-LD, OpenAPI, API Catalog metadata, and safe browser/runtime WebMCP validation.

Preview hosted recon can also inspect a deployed public URL and report what browser agents can observe without source access.

Current release: descuff@0.17.4 on npm. Descuff is an early public preview for local Next.js App Router, Next.js Pages Router, and React/Vite codebases, including common monorepo layouts where the app lives under folders such as apps/web.

Works today: local Next.js App Router and Pages Router projects, plus React/Vite preview support for source-backed frontend routes, forms, fetch references, and existing standards.

Quick Start

Run Descuff inside a local supported project:

npx descuff doctor .
npx descuff start .

doctor checks that you are in a supported project root. start creates the baseline, validation report, implementation plan, and coding-agent prompt.

Descuff writes:

.descuff/baseline.json
.descuff/model.json
.descuff/assessments.json
.descuff/generated-changes.json
.descuff/graphify-enrichment.json
.descuff/skill-evidence-packet.json
.descuff/llm-discovery-prompt.md
.descuff/llm-discovery-template.json
.descuff/semantic-enrichment-prompt.md
.descuff/semantic-enrichment-template.json
.descuff/plan.md
.descuff/codex-prompt.md

When .descuff/runtime.json includes browser-agent scenarios, scans can also write:

.descuff/browser-agent-scenarios.json
.descuff/browser-agent-results.json
.descuff/browser-agent-results.md
.descuff/readiness-explanations.json
.descuff/readiness-explanations.md

Give .descuff/codex-prompt.md, .descuff/plan.md, and the LLM discovery artifacts to Codex, Cursor, Claude Code, or another coding agent. The agent writes .descuff/llm-discovery.json, runs npx descuff enrich ., reviews .descuff/llm-discovery-diff.md, then implements the accepted standards while preserving the existing UI and behavior. Older semantic-enrichment.json workflows still work as a compatibility fallback.

start prints the detected domain profile, route/API/capability/form counts, implemented/recommended standards, validation status, readiness notes, generated artifact paths, and next steps.

After implementation:

npx descuff finish .

Descuff rescans, validates, and writes:

.descuff/final-validation.json
.descuff/before-after.md

What Descuff Does

• Detects Next.js routes, API operations, forms, middleware/proxy/route-handler auth boundaries, Server Actions, route visibility, and existing standards.
• Detects React/Vite preview apps with source-backed frontend routes, React Router route evidence, navigation links, forms, literal same-origin fetch references, and existing public standards.
• Builds an evidence-backed semantic model of domain profile, compatibility application type, capabilities, risks, routes, APIs, standards, and readiness.
• Records optional Graphify/native structural correlation when graphify-out/graph.json is present, and continues with native analysis when it is absent or invalid.
• Recommends agent-facing standards: llms.txt, Schema.org JSON-LD, OpenAPI, RFC 9727 API Catalog, and experimental WebMCP implementation plans for browser-registered public read tools.
• Generates a conservative implementation plan for a developer-owned coding agent.
• Validates standards, security boundaries, runtime evidence, readiness score, and structured readiness explanations.
• Can use optional .descuff/runtime.json to inspect a running local app in the browser, compare browser-agent task effort before/after standards, and execute only explicitly approved read-only WebMCP scenarios.
• Links readiness explanations to configured browser-agent scenarios so teams can see which missing evidence affects real agent tasks.
• Reports before/after improvement so teams can see what changed.
• Tracks a local drift baseline so CI can fast-pass irrelevant changes and revalidate agent-facing changes before they ship.

Why It Exists

Most websites were designed for humans and browsers. AI agents need clearer entry points: public summaries, structured entities, documented APIs, discoverable catalogs, and strict safety boundaries around anything sensitive or mutating.

Descuff gives developers a repeatable workflow:

baseline -> LLM discovery review -> plan -> implement with your coding agent -> validate -> compare

Commands

npx descuff start [project-root]
npx descuff finish [project-root]
npx descuff scan [project-root]
npx descuff report [project-root]
npx descuff plan [project-root]
npx descuff diff [project-root]
npx descuff check [project-root]
npx descuff scenarios [project-root]
npx descuff recon <url> [--max-pages N] [--scenario id] [--compare path] [--browser]
npx descuff doctor [project-root]
npx descuff install [codex|claude-code|cursor|all] [project-root]
npx descuff install --platform codex
npx descuff install --platform claude-code [project-root]
npx descuff install --platform cursor [project-root]
npx descuff install codex --global
npx descuff enrich [project-root]
npx descuff validate [project-root]
npx descuff fix
npx descuff apply-safe [project-root]

Recommended first-time flow:

start -> enrich -> coding agent implements accepted plan -> finish

Lower-level commands:

• scan writes .descuff/analysis.json, .descuff/model.json, .descuff/assessments.json, .descuff/generated-changes.json, .descuff/graphify-enrichment.*, .descuff/skill-evidence-packet.*, LLM-discovery prompt/template artifacts, and legacy semantic-enrichment prompt/template artifacts.
• report prints domain profile, compatibility application type, capability count, route/API counts, and standard status.
• plan writes .descuff/plan.json and .descuff/plan.md.
• diff compares changed files against .descuff/drift-baseline.json and writes .descuff/drift-diff.json plus .descuff/drift-report.md.
• check performs the same deterministic, non-LLM drift analysis, fast-passes unrelated changes, writes a validation plan, and runs validation for changes that can affect routes, APIs, capabilities, auth boundaries, or published standards. Passing checks say no Descuff repair is needed; failing checks point the coding agent back to the start -> finish -> check repair workflow.
• scenarios writes .descuff/scenario-suggestions.json and .descuff/scenario-suggestions.md with evidence-backed read-only browser-agent task suggestions. Hosted recon can use these suggestions when no explicit .descuff/runtime.json scenarios exist.
• recon inspects a hosted public URL without source access, writes .descuff/hosted-recon.*, and reports visible standards, public pages, forms, metadata, confidence labels, blockers, and optional read-only browser-agent reachability scenarios. Add --browser when you want best-effort rendered-page evidence, browser network counts, and browser-discovered WebMCP tools.
• doctor diagnoses the current root before first use, writes .descuff/doctor.json and .descuff/doctor.md, and suggests a likely nested app root when Descuff was run from the wrong folder.
• Drift baselines are generated local artifacts by default. Keep .descuff/ ignored for public repos, and let CI preserve .descuff/drift-baseline.json as a protected cache/artifact or regenerate it from the base branch before checking a pull request.
• install --platform codex installs the tested Codex skill under $CODEX_HOME/skills/descuff or ~/.codex/skills/descuff; invoke it with $descuff ..
• install --platform claude-code writes a project slash command to .claude/commands/descuff.md; invoke it with /descuff ..
• install --platform cursor writes a project rule to .cursor/rules/descuff.mdc; ask Cursor Agent to Descuff the app from that project.
• install all writes local preview skill instructions for Codex, Claude Code, and Cursor under .descuff/skills/. Install output reminds users to run finish only after explicit Descuff plan implementation and check for ordinary later edits. Installed agent instructions begin with a short intake: what Descuff does, the current local Next.js and React/Vite preview boundary, whether to use LLM discovery, whether to generate browser-agent scenarios, whether to run optional hosted recon, and whether to use existing Graphify output when present. The agent should wait for confirmation before running Descuff commands unless the prompt explicitly says to proceed without confirmation. If Graphify is used, installed agents keep Graphify stats as compact supporting evidence and end with Descuff-specific next steps such as deployment, hosted recon, readiness repair, or scenario review. When local validation and hosted recon both run, installed agents should report them separately so local source success is not confused with deployed-site visibility.
• enrich validates .descuff/llm-discovery.json against the skill evidence packet, source fingerprints, and input artifact hashes, then writes .descuff/llm-discovery-diff.md. If no LLM discovery file exists, it still validates legacy .descuff/semantic-enrichment.json and writes .descuff/semantic-enrichment-diff.md.
• validate rescans before scoring, writes .descuff/validation.json, and exits non-zero on validation failure. The validation report includes readinessExplanations so tools can distinguish blockers, recommendations, acceptable gaps, and complete categories.
• Optional .descuff/runtime.json lets scan and validate use a running local app for browser/runtime evidence. It can include read-only browserAgentScenarios for standard-neutral task checks and explicit webMcpToolScenarios for safe tool execution. Without it, Descuff keeps using conservative synthetic runtime evidence.
• fix prints agent workflow instructions. It does not invoke an LLM and does not edit source directly.
• apply-safe is intentionally disabled for automatic source writes in this release.

Example Result

A simple Next.js landing page with one waitlist endpoint can move from:

Readiness: 60/100
Standards: none

to:

Readiness: 85/100
Standards: api-catalog, llms-txt, openapi, schema-org
Failures: 0
Warnings: 0

The remaining points depend on the app. A simple landing page may not have structured product, article, booking, or workspace entities for Descuff to model.

Safety Model

Descuff treats runtime analysis as read-only by default. It does not invoke mutating HTTP methods, submit forms, execute server actions, or expose sensitive/high-consequence capabilities unless a validation scenario explicitly defines setup, expected side effects, verification, and cleanup.

Descuff does not directly call an LLM. It writes a plan and prompt for the coding agent you already use.

Supported Today

• Next.js App Router
• Next.js Pages Router
• nested Next.js apps in common monorepo layouts, such as apps/web/app
• React/Vite preview apps with source-backed frontend route, form, fetch-reference, and public standards evidence
• API routes
• basic form evidence
• conservative Server Action capability modelling
• middleware and proxy.ts auth-boundary detection
• route-handler auth evidence for common session, API-key, permission, and wrapper patterns
• authenticated route filtering for public metadata
• existing llms.txt, OpenAPI, Schema.org JSON-LD, API Catalog, and WebMCP detection

External Hardening

Descuff has been tested against unrelated public Next.js repositories covering static sites, content sites, commerce, SaaS dashboards, booking flows, Pages Router auth, analytics apps, and forms-heavy monorepos. Those audits turned into regression tests for route discovery, Server Actions, auth boundaries, monorepo route roots, and safety classification.

Not yet supported as a general-purpose website crawler:

npx descuff scan https://example.com

Use hosted recon for the public deployed surface:

npx descuff recon https://example.com

Use local source-backed validation for implementation:

cd my-supported-app
npx descuff start .

Documentation

• How To Use Descuff
• CLI Package README
• Example Next.js App

Development

pnpm install
pnpm run ci

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md before opening a change.