io.github.genclass-devPublished by GitHub account genclass-devv0.2.2Updated Nov 6, 2026
Find race conditions in your web app by reordering its responses, replay one, prove the fix.
GenClass records what happens inside your local web app's pages and lets a coding agent find, replay and prove fixes for timing-dependent bugs.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
An MCP server for Claude Code and other coding agents. It connects to the pages of your app running on your machine
(through @genclass/runtime's agent link) and gives the agent:
genclass_explore runs your steps again with the network answering in
different orders (and slower, if you like) and reports what ends differently from the run where responses came back
in order.genclass_replay delivers the exact order that produced a bug again, before your fix (reproduced) and
after it (not reproduced), and genclass_explain writes a Playwright test that fails while the bug is there.By default everything stays on your machine (see Privacy). No dependencies. The server is free. For developers who want the loop run for them, GenClass runs it as a service under Enterprise: the MCP server, collector and dashboard hosted by GenClass or inside your network (genclass.dev/enterprise).
Pick your client. Every block pins this release, so the client starts exactly this version;
npx -y @genclass/[email protected] config <client> prints the same lines, and genclass_setup prints the block for the
client it runs in.
As a plugin (the server, a prompt hook that brings new findings to each prompt, and the genclass skill with the procedure):
Or the server alone (--scope project writes .mcp.json for everyone on the project; --scope user for all your projects). init also writes the skill to .claude/skills/genclass/SKILL.md (--no-skill leaves it out):
Or just the skill (no server): npx skills add genclass-dev/genclass-plugin. (genclass-dev/genclass-plugin is this plugin at a repository root, assembled from this package; the marketplace in genclass-dev/GenClass lists the same plugin.)
Settings, Developer, Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
[Add genclass MCP server to Cursor] or cursor://anysphere.cursor-deeplink/mcp/install?name=genclass&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnZW5jbGFzcy9tY3BAMC4yLjIiXX0%3D
Or .cursor/mcp.json in the project (~/.cursor/mcp.json for all projects):
[Install in VS Code] or from a terminal:
Or .mcp.json at the workspace root (the portable format; .vscode/mcp.json takes the same entry under servers):
As a plugin (the server and the genclass skill):
Or the server alone:
Or ~/.codex/config.toml (.codex/config.toml in a trusted project). The first start downloads the package, so allow more than the default 10 seconds:
As an extension (the server and the genclass skill):
Or the server alone:
Or .gemini/settings.json in the project (~/.gemini/settings.json for all projects):
~/.codeium/windsurf/mcp_config.json (Windsurf), ~/.config/devin/mcp_config.json (Devin Desktop's Cascade agent; %APPDATA%\devin\mcp_config.json on Windows):
Devin CLI and Devin Desktop's Devin Local agent:
Or MCP Servers, Configure, Configure MCP Servers (~/.cline/data/settings/cline_mcp_settings.json):
goose://extension?cmd=npx&arg=-y&arg=%40genclass%2Fmcp%400.2.2&id=genclass&name=genclass&description=Find%20race%20conditions%20by%20reordering%20responses%2C%20replay%20one%2C%20prove%20the%20fix (open it to install), or goose configure (Add Extension, Command-line Extension, command npx -y @genclass/[email protected]), or ~/.config/goose/config.yaml:
~/.config/zed/settings.json (.zed/settings.json in the project), or Settings, AI, MCP Servers, Add Server:
AI Assistant: Settings, Tools, AI Assistant, Model Context Protocol (MCP), Add, then this JSON. Junie: .junie/mcp/mcp.json in the project (~/.junie/mcp/mcp.json for all projects), same JSON:
opencode.json in the project (~/.config/opencode/opencode.json for all projects), or opencode mcp add:
Any other MCP client: a stdio server, command npx, arguments -y @genclass/[email protected], no environment variables
required.
genclass skillThe server's instructions (sent when it connects) tell the agent when to reach for GenClass: the symptom words
("sometimes", "randomly", "only in production", "on slow connections", a value that "flips back", stale or old
results, lost edits, double submits, sideways scrolling), the code changes that call for an explore, the scan before a
UI change is done, and the first call for each. The procedure (the explore arguments, the Playwright pairing, how to
read a report, what to say when done, what to do when the tools are missing) is the genclass skill,
plugin/skills/genclass/SKILL.md. Three ways to get it:
npx -y @genclass/[email protected] init writes it to .claude/skills/genclass/SKILL.md in the project (--no-skill
leaves it out). The written file carries a genclass:init marker line: a rerun replaces a file with the marker and
leaves one without it (yours, or edited), and says which;npx skills add genclass-dev/genclass-plugin (the skills CLI: Codex, Cursor, Copilot, Gemini CLI, Claude Code and
others) or gh skill install genclass-dev/genclass-plugin genclass (GitHub CLI 2.90 or later, for Copilot) installs
the skill alone, with no server (the skill then says how to add one). npx skills add genclass-dev/GenClass
installs the same file from this repository's root copy, skills/genclass/SKILL.md.To remove it: delete .claude/skills/genclass/ (or the directory the skill tool wrote to); with the plugin,
/plugin uninstall genclass@genclass.
Then connect the app's development build (once). The agent link needs the newest runtime line, @genclass/runtime
0.3.0-beta.1 or later: npm install @genclass/[email protected], the version this release was tested with (npm's
latest is the older 0.2.x, which has no agent entry):
A production build drops all of this (measured with Vite, esbuild and Next.js 15; the package's sideEffects list names
neither entry). Load a page of the dev server and ask the agent for genclass_status. The agent can also ask genclass_setup,
which reads your package.json and shows the lines for your framework.
The skill and the server's instructions tell the agent to show you each of these and wait for your yes: running that
install or adding those lines; npx playwright install chromium and npm i -D playwright; genclass_scan with hosted: true; writing a fix or a
test when you only asked what broke.
On a real page in headless Chromium (the package's end-to-end check), explore found that race in 5 of 6 reordered runs of a page that never showed it on the developer's fast backend, the generated test failed on the buggy page and passed on the fixed one, and explore on the fixed page reported nothing. Details: docs/runtime/AGENT.md.
What it calls a race is what the page shows or writes, not the noise of a running page: an age that moved by the time
the session took ("13 minutes ago", "14 minutes ago"), a field name made for each load and a different count of a POST
that only reads are not differences by themselves; "3:30 PM" against "4:00 PM" and a save that never went out are. With
slow_ms one load runs with no added delay (runs + 3 loads: 2 slow baselines, that one, and the reordered runs): what
both slow baselines show and it does not is named as what a slow response alone does, and what only one of them does is
"worth a look". A report that compared nothing says NO VERDICT, not "no race".
claude --dangerously-load-development-channels server:genclass and new findings arrive in the session as they
happen (notifications/claude/channel).npx -y @genclass/[email protected] init --hook adds a UserPromptSubmit
hook to .claude/settings.json; each prompt then carries the findings that changed since the last one.The bridge listens on 127.0.0.1 only and checks the Host header. Pages may talk to it only from your machine
(localhost, 127.0.0.1, *.localhost) or an origin you list in GENCLASS_AGENT_ORIGINS (a *.test or LAN dev host): a public
website, a router page or a captive portal you visit cannot plant findings, and a page can only add to its own run.
The agent API refuses browsers and needs a token only your user can read. Everything a page sends is validated,
capped, stripped of invisible characters and shown to the agent as quoted data, never as instructions. Nothing leaves
your machine (the exceptions are under Privacy). See section 6 of
AGENT.md.
By default the server collects nothing and sends nothing to GenClass or anyone else. Findings stay on your machine, in
.genclass/agent/ in the server's working directory (the project, for clients that start servers there; set
GENCLASS_STATE_DIR for clients that do not, such as Claude Desktop), which the server gitignores, and in the bridge's memory; the bridge's token is in
~/.genclass. genclass_analytics {source: "production"} reads
your own GenClass dashboard when you set GENCLASS_DASHBOARD to its private link. genclass_scan loads the page the
agent names (that is the page's own traffic) in a local browser; only with hosted: true is the URL sent to the
genclass.dev page check, and when the project has no @genclass/runtime with scan, npx downloads the version this release pins, @genclass/[email protected], from npm. With GENCLASS_REPORT set (off by
default) the server also mirrors its log of the loop to that dashboard, in small batches: the id, kind and page path of
each finding, when its evidence was read, each replay armed and its verdict, when a regression test was written, each
explore report (page loads compared, races found) and each clear, so the dashboard's Closed-loop development view
draws every issue's path (found, reproduced, fix proven, closed, or round again) and lists what the agent did; never a
title, an evidence line, a snapshot or any page text, and nothing it sends feeds a decision.
The lines above start the runtime in development builds only. On a local or private address it sends no diagnostics (it
does fetch its on-device model from jsDelivr). Running it in production is a separate choice this server does not need:
outside the check GenClass.init() runs for every visitor and sends its disclosed anonymous diagnostics from public
hosts by default (PRIVACY.md), which
GenClass.init({ telemetry: false }) turns off; the agent link is not part of them.
Apache-2.0
Source: packages/mcp/README.md at commit cc78bfc
GenClass status
Which pages on this machine are connected to GenClass (route, schedule, model state), counts of findings by kind, the explore session and armed replays. Call it first in a web project, and before you test a page.
Takes no parameters.
GenClass findings
What GenClass recorded in pages on this machine, ranked and deduplicated with counts: races found by explore (final state depends on response order), responses that overwrote newer data, uncaught errors (with the click and request before them), the same request sent twice by two clicks, the on-device model's detections, visual checks. Use when the user reports an intermittent bug, after changing data-fetching or submit code, or before saying a UI change is done.
kindlimitroutesince_minutesExplain a GenClass finding
Everything about one finding: what happened in causal order (click → request → response → state write), the recorded steps and delivery order, what differed from the request-order baseline, the model's facts, how to replay it exactly, and a Playwright regression test that fails while the bug is there.
idrequiredExplore response orders
Find races before users do. action "start" arms the next page loads: 2 baselines with responses in request order (with `slow_ms`, a third with no added delay), then `runs` loads where overlapping responses arrive in a seeded different order (optionally slower, or with `focus` endpoints last). Run the same scenario once per armed load, then action "report": each load's final state is compared with the baseline; a difference in what the page shows, its form values, the requests it sent or its errors depends on network timing (a race), and comes with a seed that replays it. Store values that differ while the page is the same are listed apart as internal state. Without `route`, the page of the first armed load is the page under test; set `route` when the scenario loads several pages. Armed loads expire after 30 minutes. "stop" disarms.
idrunsseedfocusrouteactionrequiredslow_msReplay a finding
Reproduce one finding exactly. action "arm": the next page load of the finding's route gets the delivery order that produced it; do the same steps (genclass_explain lists them). action "result": whether that replay reproduced it. Use before a fix to confirm the bug and after it to prove the fix.
idrequiredtimesactionrequiredGenClass analytics
What GenClass measured about the app. local: per-endpoint request counts, median and p95 latency, error rates and failure streaks; per-page runs, errors and overwritten fields; learned relations between fields and learned flows, from pages on this machine. production: the GenClass dashboard's sessions, detections by diagnosis and page, and latest decisions (needs GENCLASS_DASHBOARD, the dashboard's private link; "sample" reads the public sample).
rangeroutesourceSet up GenClass
The lines to add so this project's dev build connects to GenClass (detects Vite, Next.js and others from package.json), how to check it works, and this MCP client's config lines for keeping the server configured. It changes no file; show the user the lines and wait for a yes before you run or add them.
Takes no parameters.
Scan a page for visual bugs
Audit one page in one step with GenClass's 23 measured visual checks: text you cannot read against its background, images, fonts, stylesheets and media that failed to load, a page that scrolls sideways on a phone, controls stuck under fixed bars, layers that swallow clicks, covered dialogs, template leaks like {{name}} or [object Object]. It loads the URL headless at desktop and phone sizes in Playwright's Chromium on this machine (when that is missing it says how to install it); hosted: true runs it on the genclass.dev page check instead, which adds accessibility, speed and security audits, takes public pages only and is the one case where the URL leaves this machine and returns a score and each problem with its element, selector and a suggested CSS fix, worst first, plus the JSON report. Use it before you call a page or UI change done, after CSS or layout changes, and on a site you do not own. Works on any URL, including the dev server (http://localhost:5173/); no page needs GenClass installed.
urlrequiredphonehostedClear GenClass records
Forget recorded runs and findings on this machine (all, findings or runs), e.g. after a fix to start clean.
what90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
/plugin marketplace add genclass-dev/genclass-plugin/plugin install genclass@genclassclaude mcp add --scope project genclass -- npx -y @genclass/[email protected]# or: npx -y @genclass/[email protected] init --hook (.mcp.json and the skill, plus the prompt hook in .claude/settings.json){ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}code --add-mcp '{"name":"genclass","command":"npx","args":["-y","@genclass/[email protected]"]}'{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}codex plugin marketplace add genclass-dev/genclass-plugincodex plugin add genclass@genclasscodex mcp add genclass -- npx -y @genclass/[email protected][mcp_servers.genclass]command = "npx"args = ["-y", "@genclass/[email protected]"]startup_timeout_sec = 30gemini extensions install https://github.com/genclass-dev/genclass-plugingemini mcp add genclass npx -- -y @genclass/[email protected] # -s user: for all projects{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}devin mcp add -s user genclass -- npx -y @genclass/[email protected]cline mcp add genclass --yes -- npx -y @genclass/[email protected]{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}extensions: genclass: type: stdio name: genclass enabled: true cmd: npx args: ["-y", "@genclass/[email protected]"] env_keys: [] envs: {} timeout: 300{ "context_servers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}{ "mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/[email protected]" ] } }}{ "$schema": "https://opencode.ai/config.json", "mcp": { "genclass": { "type": "local", "command": [ "npx", "-y", "@genclass/[email protected]" ], "enabled": true } }}import { GenClass } from "@genclass/runtime";import { connectAgent } from "@genclass/runtime/agent";
// Next.js: process.env.NODE_ENV === "development"if (import.meta.env.DEV) { const rt = GenClass.init(); connectAgent(rt);}you: the search results are sometimes for an older query; find out why and fix itagent: genclass_findings → f1 [stale-write] /search: the response to GET /api/search "?q=reac" overwrote "search.results" after a newer GET /api/search had already written it genclass_explain f1 → steps, delivery order, a replay, a regression test genclass_replay arm f1 → (loads the page, types) → result: REPRODUCED (fixes the handler to keep only the latest answer, adds the test) genclass_replay arm f1 → result: not reproduced genclass_explore start {slow_ms: 600} → 9 runs → report: no race