13 years of Microsoft hyperscale engineering, packaged as a harness for your AI coding agent.
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 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.
Acceptance test agent for coding agents: real-browser tests, with screenshots on the PR.
2026-11-14
ดาว
—
เครื่องมือ
—
อัปไทม์
—
real browser
Works in Claude Code, Cursor, Codex, Windsurf, and any MCP client. Powered by Muggle Test.
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.
100+ 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
6
Acceptance
Drives a real browser through the affected flows
Verdict + runId + per-step screenshots
7
Pull request
Opens the PR/MR with the evidence block in the body
PR URL
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 7 refuses to run until the Definition of Done holds. 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.
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.
Restart Codex and trust the plugin's hooks when it asks (or later, in /hooks). Skills are invoked as $muggle:<skill> — $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:
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.
Command
Alias
What it does
/muggle:muggle
/m
Command router and menu
/muggle:muggle-do
/mdo
The full cycle: request → pull request
/muggle:muggle-test
/mtest
Change-driven acceptance testing on your diff, PR, or branch
/muggle:muggle-test-feature-local
/mtestlocal
Test one named flow against localhost
/muggle:muggle-test-prepare
/mtestprep
Verify and start the dev servers a run needs
/muggle:muggle-test-import
/mimport
Import Playwright, Cypress, Gherkin, or PRDs
/muggle:muggle-test-regenerate-missing
/mregen
Bulk-regenerate scripts for cases that have none
/muggle:muggle-browser-task
/mbt
Perform a real action on a website from plain English
/muggle:muggle-pr-visual-walkthrough
/mpr
Post screenshots and a pass/fail summary to a PR
/muggle:muggle-pr-followup
/mprfollowup
Watch a PR's reviews, CI, and base drift
/muggle:muggle-feedback
/mfeedback
Flag a generated script or step as wrong
/muggle:muggle-preferences
/mprefs
View, set, or reset preferences
/muggle:muggle-status
/mstatus
Health check: runner, MCP server, auth
/muggle:muggle-repair
/mrepair
Diagnose and fix a broken install
/muggle:muggle-upgrade
/mupgrade
Update to the latest version
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.
Capability
GitHub
GitLab
Open and update the change
Pull request
Merge request
Read review feedback
Review threads + line comments
Discussions + notes
Reply per comment, resolve threads
Yes
Yes
Read CI status and re-enter on red
Actions
Pipelines
Rebase onto a drifted base
Yes
Yes
Signed commits
Yes
Yes
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 — by the walkthrough, or by a stated reason acceptance testing doesn't apply. A PR that changes only docs, tests, lint/format config, or CI config needs neither: its comment opens already settled as skipped.
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 replaces a copy an earlier release wrote with the current one, and leaves a copy you edited alone unless you pass --force; muggle init and /muggle-do do the same refresh on their own unless autoInstallCiWorkflow is never. To add it by hand instead:
The verdict is published as a check run against the pull request's head commit, not as this job's own status. An issue_comment run executes against the default branch, and only a head-commit check reaches the pull request from there — which is what lets settling the comment turn the check green without a new push.
GitHub reads the issue_comment trigger from the default branch's copy of the workflow, so comment-driven re-runs start working only once it is merged.
Runs for one pull request queue rather than cancel. Settling the comment starts a run while the one checking the push may still be going, and cancelling that run would leave a cancelled job on the pull request — red beside a green check. An installed copy that still says cancel-in-progress: true shows exactly that; muggle ci-install updates it.
On a pull request from a fork, GITHUB_TOKEN is read-only and the check run cannot be published. The command fails open and reports nothing rather than blocking the pull request.
Architecture
Test management lives in the cloud; execution is local and stateless. muggle-remote-* tools own projects, use cases, test cases, and scripts. muggle-local-* tools receive what they need and run the browser — so a local run never waits on cloud replay capacity.
Entity model
Project ("My App")
└── Use Case ("User Login Flow")
└── Test Case ("Login with valid credentials")
└── Test Script (recorded browser steps)
└── Run Result (pass/fail + screenshots)
Execution flow
Your agent describes what to test
│
▼
muggle-remote-* create or find the test cases
│
▼
muggle-local-execute-test-generation launches the browser runner
│
▼
An agent drives the browser step by step (click, type, navigate, assert)
│
▼
Per-step screenshots → action-script.json recorded
│
▼
Results at ~/.muggle-ai/sessions/{runId}/ — published during the run,
so the result carries a viewUrl straight to the dashboard
Data directory
~/.muggle-ai/
├── oauth-session.json # OAuth tokens (short-lived, auto-refresh)
├── api-key.json # Long-lived key for service calls
├── projects/ # Local project cache
├── sessions/ # Run sessions — read one with `muggle run-view [runId]`
│ └── {runId}/
│ ├── action-script.json # Recorded browser steps
│ ├── results.md # Step-by-step report
│ └── electron-runtime/screenshot/ # Per-step images
├── muggle-do/sessions/ # Cycle state, iterations, PR watchers
└── electron-app/{version}/
MCP tool reference
108 tools across authentication, projects, use cases, test cases, scripts, workflows, local execution, reporting, secrets, billing, and administration. Call them directly from any MCP client to build your own pipeline.
A lane's records in start order, and whether the rest wait on the primary
muggle-remote-test-case-bulk-preview-submit
Async batch preview (~50% cheaper)
muggle-remote-test-plan-graph-rebuild
Rebuild the prerequisite graph
Bulk-preview submissions return a jobId immediately. Poll muggle-remote-bulk-preview-job-get until terminal, then persist with the matching -create tool. -list and -cancel round out the set.
Administration — muggle-remote-prd-file-* (upload and process requirements docs), muggle-remote-secret-* (credentials for test environments), muggle-remote-wallet-* (credits, payment methods, auto-topup), muggle-remote-recommend-cicd-setup / -recommend-schedule, muggle-remote-user-feedback-*.
CLI reference
# Server
muggle serve # Start the MCP server with all tools
muggle serve --e2e # Cloud tools only (muggle-remote-*)
muggle serve --local # Local tools only (muggle-local-*)
# Setup and diagnostics
muggle init # Guided setup; saves preferences, offers the CI check
muggle llm-source [--show] # Who supplies the model for local runs: Muggle AI credit, your Anthropic key, a local model, or your Claude Code
muggle setup [--force] # Download or update the browser runner
muggle upgrade [--check] # Install the latest runner version
muggle versions # List installed runner versions
muggle cleanup [--dry-run] # Remove old versions and obsolete skills
muggle doctor # Diagnose installation problems
# Inspecting runs
muggle run-view [runId] # A run's steps beside the frames they produced (newest run by default)
muggle run-view --html # Render those frames as a self-contained page
muggle run-view --open # Render it and open it in the browser
muggle checkout-freshness # Fetch the base and check this checkout is built on its latest commit
# Authentication
muggle login [--key-expiry 90d]
muggle logout
muggle status
# Pull requests
muggle ci-install [--force] # Add or update the walkthrough check in GitHub Actions
muggle pr-walkthrough-check # Verify a PR's walkthrough comment is settled
muggle build-pr-section # Render a PR evidence block from a report on stdin
muggle --version
muggle --help
Configuration
Environment targeting. Set MUGGLE_MCP_PROMPT_SERVICE_TARGET (production or dev) in the MCP server's env block — in Codex, export it in your shell; the plugin forwards it. Mismatching it against the account you log in with is the usual cause of unauthorized_client.
Multi-repo cycles. Drop a muggle-repos.json in your working directory so a single request can span services:
Preferences./mprefs (or muggle init) controls the gates — whether to use a worktree, rebase onto the base branch, run acceptance tests every cycle, open the PR automatically, and arm the watcher. Each gate takes always, ask, or never.
When installed as a Claude Code plugin, MCP configuration ships with the plugin (plugin/.mcp.json; Codex reads plugin/.codex-mcp.json) — there is nothing to copy by hand.
Client support
Client
MCP tools
Skills
Guardrail hooks
Claude Code
Yes
Yes — slash commands
Yes
Codex
Yes
Yes — $muggle:<skill>
Yes, once trusted
Cursor
Yes, auto-configured
Synced to ~/.cursor/skills/
Advisory
Windsurf, others
Yes, via MCP config
No
No
Slash commands are plugin-managed; update them with /plugin update muggleai@muggle-works (Claude Code) or codex plugin marketplace upgrade muggle-works (Codex).
Codex
The Codex plugin ships the same skills, MCP server, and hooks as the Claude Code one, with what Codex needs written in rather than left to defaults:
Long local runs. Codex cancels an MCP call after 60 seconds unless told otherwise, and a local browser run takes minutes. The plugin's server allows 30 minutes per call and two minutes to start.
Your environment. Codex starts MCP servers with only HOME, PATH and the locale. The plugin forwards what the server reads — MUGGLE_MCP_PROMPT_SERVICE_TARGET, the AUTH0_* and service-URL overrides, HTTPS_PROXY/NO_PROXY, and on Linux the display variables the browser runner needs.
Claude Code tools in the skills. Codex has no AskUserQuestion, Skill tool, or background monitor. Each skill points at _shared/host-tool-equivalents.md, which maps them to Codex, and the session-start hook names it too.
PR watching. Codex cannot wake a session when a reviewer comments, so $muggle:muggle-pr-followup handles what is outstanding each time you run it rather than watching in the background.
Sandbox. Codex's default sandbox blocks the network and writes outside the workspace, so gh/glab and state under ~/.muggle-ai/ ask for approval. To stop the prompts, allow both in ~/.codex/config.toml:
Headless runs.codex exec cannot ask you anything. It refuses every muggle MCP call ("requires approval, but approval policy is never"), and it runs only hooks you have already trusted. Trust the hooks once in the TUI (/hooks), and approve the muggle tools in ~/.codex/config.toml:
muggle doctor checks whichever of the two you set up.
Troubleshooting
unauthorized_client during login — the MCP server is pointed at one environment and you're authenticating against another. Fix MUGGLE_MCP_PROMPT_SERVICE_TARGET and restart the client.
With both installed, muggle-ai-teams folds acceptance testing into each workflow step: test instructions written per slice at Plan, per-slice browser tests at Build, a full regression sweep at Verify, and results published and linked in the PR at Ship. Frontend slices get browser tests; backend-only slices are covered by unit tests, with the skip reasoned in writing.
Want it hosted, with nothing to configure? Muggle Test.
Contributing
pnpm install # This repo is pnpm-only
pnpm run build # tsup + plugin artifact
pnpm test # Tests impacted since origin/master, on 25% of cores (full suite in CI; MUGGLE_VITEST_FULL=1 forces it locally)
pnpm run lint # Lint (auto-fix)
pnpm run typecheck # Type check
pnpm run dev # Watch mode
Verification gates, all run in CI:
pnpm run verify:plugin # Plugin and marketplace metadata agree
pnpm run verify:contracts # CLI/MCP/plugin/skill surface contracts hold
pnpm run verify:skill-deps # Skill dependencies stay one-way
pnpm run verify:signatures # Shipped artifacts are signed
pnpm run verify:upgrade-experience # Existing-user upgrade still works
pnpm run verify:electron-release-checksums
Lint, test, build, contract verification across platforms
verify-end-user-upgrade.yml
Weekly + manual
Existing-user upgrade validation
publish-works-to-npm.yml
Tag v* or manual
Verify, audit, smoke-install, publish
Two independent tag tracks: vX.Y.Z publishes @muggleai/works to npm; electron-app-vX.Y.Z publishes browser-runner binaries consumed by muggle setup and muggle upgrade.
Maintainers cut releases with the repo-local /mrelease skill rather than tagging by hand — CI can otherwise publish a version that disagrees with the checked-in manifests.
Agents pick tools by reading descriptions, so that text is tuned deliberately rather than written once. internal/skills/optimize-descriptions/SKILL.md documents the five layers of agent-facing text, where each lives, and how to build and run trigger eval sets against them. It is maintainer-only and ships in neither the npm package nor the plugin.
