muggle-ai-works

Muggle Works addresses a key gap in AI coding agent workflows: while agents can quickly produce code diffs, they often lack visibility into whether changes work end-to-end, break existing user flows, or meet the bar for human merge. The harness operates as a structured wrapper around these agents to enforce consistent delivery discipline, and currently supports web applications only. Triggered by a single natural language request, the tool runs a structured, gated delivery cycle: it first detects the connected repository, branch, local dev server, project configuration, and available credentials in a single pre-flight step, then freezes explicit requirements and acceptance criteria before any code is written. It delegates design and build work to subagents, creates signed conventional commits, maps the generated diff to potentially affected user flows, runs the project's unit test suite, and drives a real browser through affected user flows to capture pass/fail verdicts and per-step screenshots. A pull request or merge request is only opened once all defined Definition of Done gates are met, with attached evidence of test results and screenshots. If acceptance failures are detected, the harness runs up to 3 iterative repair cycles to resolve issues before opening the PR. Once the PR is live, a persistent watcher polls for reviewer comments, red CI status, and base branch drift, automatically re-entering the delivery cycle to address feedback without manual relay from the user. Unlike lightweight headless test stubs, the browser testing capability uses managed login profiles connected to live inboxes, enabling testing of magic links, emailed OTPs, email 2FA, verification emails, and password reset flows without requiring test-only backdoors, mail catchers, or skip-authentication flags. Test scripts generated from plain English flow descriptions persist across sessions to act as reusable regression tests that run after every subsequent change. The tool integrates natively with both GitHub (via the gh CLI) and GitLab (via the glab CLI, including self-hosted GitLab instances detected automatically from remote repository URLs). It supports opening and updating pull/merge requests, reading review threads and line comments, responding to comments, resolving review threads, checking CI pipeline status, rebasing onto drifted base branches, and creating signed commits across both platforms. An optional GitHub Actions check is available to validate PR acceptance walkthroughs even for pull requests opened outside the local harness session, ensuring the acceptance gate applies consistently. Muggle Works supports all MCP-compatible clients, with 108+ available MCP tools covering authentication, project and test case management, test script storage, local browser execution, result reporting, test environment secret storage, and workflow automation for users who wish to build custom delivery pipelines instead of using the packaged end-to-end cycle. It offers tailored setup paths: for Claude Code, it installs as a full plugin with built-in skills and slash commands; for Cursor, it auto-configures MCP settings and syncs skills to the user's skills directory; for other MCP clients like Codex and Windsurf, it supports manual server registration. Its architecture separates cloud-hosted test management from local, stateless browser execution, eliminating waits for cloud replay capacity. Local run data, including step-by-step results, recorded action scripts, and per-step screenshots, is stored in the user's home directory, with options to publish runs to the associated cloud dashboard for shared access. Users can adjust gate behavior (such as whether to use isolated worktrees, run acceptance tests on every cycle, auto-open PRs, or arm the PR watcher) via built-in preferences, and support multi-repo setups to handle cross-service requests spanning multiple connected codebases. The project is released under the MIT license, with an npm package available for installation.