dumbdown

Less jargon. More understanding. Explain code or technical documentation with a big idea, analogy, walkthrough, terms, example and caveats at your chosen reading level.

Open dumbdown · Download v1 source · Verification

Start in the browser

1. Open the site and try the included debounce example, or paste a nonprivate snippet. The initial explanation is a labeled, hand-written sample.

2. Choose Code or Documentation and your reading level.

3. The initial OpenAI · your API key mode requires your API key and consent. For a free local experiment, choose On this device · experimental instead. Then select Dumb it down and compare the explanation with your original source.

4. Copy explanation or Download saves Markdown. Keep your original source separately before closing or reloading.

Input is limited to 12,000 characters; longer input is rejected rather than cut down. Remove secrets first. Code is never executed and pasted links are not fetched. A working button and valid JSON do not establish that an explanation is correct.

Related MCP server: mini-mcp-demo

Choose a model mode

OpenAI · your API key is the initial choice. Enter your own key and confirm the source/billing notice. The site sends the complete validated source, content type and reading level to OpenAI using GPT-5.4. Your API account pays; a ChatGPT subscription does not include API credit. Manage your API keys. The initial sample is available without a key, and opening the page makes no explanation request.

On this device · experimental downloads a model and runs it in a browser worker through WebLLM. No account, API key or paid model service is required; prompts stay on the device. Qwen 3 1.7B is the initial device choice, with Qwen 3 4B also available. These small models have missed important return values, sorting behavior and documentation conditions in our checks. Treat this mode as an experiment and review every claim.

Device mode needs HTTPS or localhost, WebGPU, compatible graphics hardware and enough memory/storage. Downloads range from roughly 1 GB to over 2 GB for the checked models. Model files can be cached when browser storage permits. Stop download and Cancel stop waiting. After cancelling generation, a fresh attempt reloads the cached model. A 12,000-character snippet can still exceed a model's token context; shorten it if the app reports that limit. There is no automatic paid fallback.

Nothing is sent until you request an explanation using the button or native tool. The key remains in the open page and active request. Clear key, Cancel, device mode, reload and page exit clear it and the consent. Cancellation cannot undo an already processed or charged provider request. Hosted explanations also require source review.

The browser app does not save source, keys or explanations in browser storage or an application database. Reload restores the sample. Model caches are separate. Exports contain the explanation and its generated example, which can repeat input details; they do not include a separate copy of the original source. Hosting/model/provider systems can process normal request metadata under their own policies. See privacy and security.

Install the source

Use Node.js 24 and npm. Download dumbdown_1.0.0_source.zip and SHA256SUMS from Releases, verify the ZIP's SHA256, and extract it into a new folder. On Windows:

Get-FileHash .\dumbdown_1.0.0_source.zip -Algorithm SHA256

From the extracted root:

npm ci
npm run dev

Open the printed localhost URL, normally port 5173. The first dependency/model download requires internet access. The website needs no operator .env.local; the visitor enters their own key in the page for optional hosted mode.

To run the compiled Worker locally:

npm run build
npm start

Stop either local server with Ctrl+C. The managed Linux execution profile used by Sites is separate from the automatically selected local profile.

CLI

The CLI uses your OpenAI API key and credits, with GPT-5.4 by default. It never executes the input. Set OPENAI_API_KEY in the process environment, or copy .env.example to ignored .env.local in the installation root and enter your key there. Keep that file private. OPENAI_MODEL can override the model; other models are outside the v1 verification scope.

npm run explain -- --help
npm run explain -- ./snippet.js code beginner
node scripts/explain.mjs ./api-notes.txt documentation intermediate > explanation.md

Use the direct node command when redirecting Markdown, so npm's command banner does not enter the file. Content types are code and documentation; levels are beginner, intermediate and advanced. Successful Markdown goes to stdout. Errors go to stderr with exit code 1. node scripts/explain.mjs --version identifies the installed version.

MCP and native WebMCP

For a stdio MCP client, use an absolute path to the installed script:

{
  "mcpServers": {
    "dumbdown": {
      "command": "node",
      "args": ["/absolute/path/to/dumbdown/scripts/mcp.mjs"]
    }
  }
}

Configure the local key as above. The one tool, dumbdown_explain, accepts source, kind and level. It shares the CLI's bounds, instructions and default model and returns structured content plus Markdown. Save the result through your client. .env.local is resolved relative to the installation even when the client starts elsewhere; restart the server after changing it. Local Node credentials are separate from the visitor's browser key.

In browsers implementing native document.modelContext, dumbdown_explain uses the selected mode and displays the same result as the button. Hosted use requires a key and consent set in the page; credentials are not a tool argument. Native support is experimental and may require browser feature flags. Other browsers use the normal controls.

Develop, recover and upgrade

The app uses React, TypeScript and Vite with an explicit Cloudflare Worker. lib/explanation-instructions.mjs shares instructions across modes; lib/explainer.mjs validates input/output, exports Markdown and calls the Node provider. lib/visitor-explanation.mjs bounds the browser hosted request. lib/browser-model.mjs manages device inference and cancellation. The compiled Worker embeds public assets and serves three explicit API routes; unknown paths return 404 and retired /api/explain returns 410.

npm test
npm run typecheck
npm run lint
npm run build
npm run audit:ci
npx playwright install chromium chrome
npm run test:e2e
npm run test:webmcp

Browser regression checks intercept synthetic hosted responses and make no paid calls. The native check requires the real browser API and fails if absent. DUMBDOWN_BROWSER_EXECUTABLE can select an installed compatible Chromium executable. See VERIFIED.md for actual model checks and their limits.

Save original source and exports before upgrading. Extract each release separately, install its locked dependencies, then copy only your retained private .env.local if needed. A browser reload restores the sample rather than recovering unsaved work. A failed retry labels the previous result. Stability and recovery explains cancellation, device requirements and configuration.

From a clean committed source tree, npm run package:source creates the ZIP and checksum files. Main's passing workflow publishes those checked bytes and preserves older releases.

License

MIT for the original code. Retain THIRD_PARTY_NOTICES.md; dependencies, separately downloaded models and services have their own terms.