Muggle Works

Muggle Works

Acceptance test agent for coding agents: real-browser tests, with screenshots on the PR.

Coding agents are good at producing a diff. They are bad at knowing whether the diff works, whether it broke the login flow, and what still has to happen before a human can merge it. Muggle Works is the harness around the agent that answers those questions: it freezes requirements, delegates the design and build, runs the unit suite, drives a real browser through the affected user flows, opens the pull request with screenshots attached, and then keeps watching that PR — picking up review comments, red CI, and a stale base branch until the change is genuinely mergeable.

Works in Claude Code, Cursor, Codex, Windsurf, and any MCP client. Powered by Muggle AI.

AI agents: start with AGENTS.md (install, sign-in, flows, skills, errors) or llms.txt. muggle serve also serves both as MCP resources, muggle://docs/agents and muggle://docs/llms.

---

Highlights

• One request, one pull request. /mdo "add a logout button" runs requirements → design → build → impact analysis → unit tests → browser acceptance → PR. You answer one questionnaire up front, then walk away.
• A real browser under a real identity. Not a headless stub. Every managed login profile owns a live inbox, so magic links, emailed OTPs, email 2FA, verification mail, and password resets are all testable — no mail catcher, no test-only backdoor, no SKIP_AUTH flag.
• GitHub and GitLab as peers. Pull requests and merge requests, review threads and discussions, Actions and pipelines, signed commits on both. Self-hosted GitLab included — the provider is detected from the remote, not hardcoded.
• The loop keeps running after you close the laptop. A watcher polls the PR and re-enters the cycle when a reviewer comments, CI goes red, or the branch falls behind its base. Feedback becomes commits without you relaying it.
• A gate, not a vibe. No PR is opened until requirements are written, the build typechecks and lints, new logic carries unit tests, the suite passes, and a browser verdict is recorded — or a waiver reason is written down. Silence is not a waiver.
• Plain English in, replayable scripts out. Describe a flow in a sentence; get a script that persists across sessions and re-runs as a regression test after every change.
• 130 MCP tools if you'd rather assemble your own pipeline than use the packaged one.

Built for two kinds of people

If you write code for a living, this is the discipline you'd apply yourself if you had the patience to apply it every time: frozen requirements, a Definition of Done that blocks the PR, evidence attached to the review, and a follow-up loop that doesn't forget.

If you vibe-code, this is the part you can't easily judge by reading the diff. You don't have to know Playwright, or what a fixture is, or why the checkout page broke on mobile. Describe the feature; the harness builds it, clicks through it like a user, shows you the screenshots, and tells you what failed in English.

---

The cycle

| # | Stage | What it does | Evidence it leaves | | :- | :---- | :----------- | :----------------- | | 1 | Pre-flight | Detects repo, branch, dev server, project, credentials; asks everything it can't detect in one turn | state.md | | 2 | Requirements | Freezes goal and acceptance criteria before a line is written | requirements.md | | 3 | Build | Delegates real design surface to a design → plan → subagent build, then commits (signed) | Conventional commits | | 4 | Impact analysis | Maps the diff to the user flows it can break | Affected-flow list | | 5 | Unit tests | Runs the suite authored in stage 3 | Exit code | | 5.5 | Pull request | Opens the PR/MR before the browser run, its walkthrough check red until stage 7 | PR URL | | 6 | Acceptance | Drives a real browser through the affected flows, its progress showing on the PR | Verdict + runId + per-step screenshots | | 7 | Walkthrough | Settles the PR's walkthrough comment with the run's evidence | Walkthrough comment | | 7.5 | Repair | Investigates and fixes acceptance failures, up to 3 iterations | Repair log | | 8 | Watcher | Polls reviews, CI, and base-branch drift; re-enters the cycle on each | followup.log |

Stage 5.5 refuses to open the PR until build and unit tests meet the Definition of Done, and stage 7 refuses to settle its walkthrough without an E2E verdict. Stage 8 is dispatched only once stage 7.5 clears — a cycle with unrepaired failures never reaches a watcher.

---

Quick start

1. Install

Claude Code — full plugin: skills, MCP tools, and the browser runner.

/plugin marketplace add multiplex-ai/muggle-ai-works

/plugin install muggleai@muggle-works

The marketplace is muggle-works and its entry is muggleai; the installed plugin is named muggle, so its skills appear as /muggle: .

Cursor — npm install -g @muggleai/works. The postinstall writes ~/.cursor/mcp.json and syncs the muggle-* skills into ~/.cursor/skills/. Restart Cursor.

Codex — full plugin: skills, MCP tools, and the guardrail hooks.

codex plugin marketplace add multiplex-ai/muggle-ai-works

codex plugin add muggle@muggle-works

Restart Codex and trust the plugin's hooks when it asks (or later, in /hooks). Skills are invoked as $muggle: — $muggle:muggle-do, $muggle:muggle-test — or picked from /skills. See Codex for what differs.

Windsurf, any other MCP client — install the package as above, then register the server:

{

"mcpServers": { "muggle": { "command": "muggle", "args": ["serve"], "env": { "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production" } } } }

2. Set up

muggle init

Explains how the harness works, saves your preferences, and offers to install the pull-request walkthrough check. Then confirm the install is healthy:

/mstatus                  # Claude Code

$muggle:muggle-status # Codex muggle doctor # anywhere — also checks the Codex plugin or MCP entry

Broken? /mrepair, or muggle setup --force.

3. Build something

/mdo "Add a logout button to the header"

PRE-FLIGHT    → repo: frontend · branch: users/me/logout-button · target: localhost:3000

REQUIREMENTS → Goal: logout button in header. AC: visible, ends session, redirects to /login. BUILD → src/components/Header.tsx, src/hooks/useLogout.ts (+ unit tests) IMPACT → affects "User Login" and "Session" flows UNIT TESTS → 12/12 pass ACCEPTANCE → 3/3 test cases pass · runId a1b2c3 · 14 screenshots PULL REQUEST → #42 opened, walkthrough posted WATCHER → armed on #42

Authentication starts on the first protected call: a browser opens with a verification code, you sign in, and the call continues. Credentials persist in ~/.muggle-ai/.

---

Commands

Every skill has a short alias. Both spellings work in Claude Code. In Codex, mention the skill with $: $muggle:muggle-do, or the alias $muggle:mdo.

---

GitHub and GitLab

The harness resolves one provider token — github or gitlab — from the URL you passed or the origin remote, then picks the matching recipe set. GitHub goes through gh, GitLab through glab. Self-hosted GitLab resolves by matching the remote host against glab's configured host, so git.acme.com works without configuration.

Nested GitLab namespaces of any depth are handled — the project path is everything before the /-/ segment, never assumed to be two levels.

The pull-request walkthrough check

When a PR is opened from a session running this plugin, Muggle reserves a comment for the acceptance walkthrough and holds the turn open until it's settled. The comment moves through three stages, edited in place: waiting for the E2E feasibility check; then E2E running — waiting for the report or E2E not feasible with the reason; then the E2E report. A PR that changes only docs, tests, lint/format config, or CI config opens straight at its reason. A session that ends without a run or a reason leaves the comment at the stage it reached, and the check stays unsettled.

A PR opened any other way — the web UI, a teammate without the plugin — never passes through that session, so the same check also runs in GitHub Actions. It fails while the comment is still empty, and whenever the walkthrough reports a failed or inconclusive test case; the check's summary names each one with its failing step and a link to the run. While a new E2E run is underway on the PR, the check stays in progress until that run's walkthrough replaces the previous one. When the Muggle PR watcher sees it red, it repairs the cases, re-runs the whole suite, and re-settles the comment.

The autoInstallCiWorkflow preference, chosen during muggle init, decides whether Muggle adds the workflow itself: always installs it in the repository muggle init runs in and in any repository /muggle-do opens a PR from, ask (the default) asks first, never leaves CI alone. To add it to a repository by hand:

muggle ci-install

That writes .github/workflows/muggle-walkthrough.yml. Run again later, it repla