Quiz, recommendation and step-by-step sign-up instead of "leave your email". You ask Claude Code or Codex, and it installs and configures it on your site.
popguia is an open source project for creating popups that talk with the visitor: instead of asking for the email right away, it asks two or three questions, teaches something useful and points to the right product, course or content. It is for anyone with a site (HTML, Next.js, Astro, WordPress) who uses a coding agent such as Claude Code, Codex or Cursor: the agent installs it, writes the journeys and tracks the results. It is free, MIT licensed, with no subscription and no server of ours. Today the repository has the research and the plan; the code is still to be written.
Alia showed that interactive journeys convert better than the discount popup, but it works only on Shopify and charges per visitor. popguia brings the same technique to any site, for free.
A CLI (npx popguia init), an MCP server and a skill teach your agent to detect the site, add the script and create the journeys.
Journeys, experiments and weights live as JSON inside your repository. You can review them in git, undo them and version them like code.
Control group, A/B testing and then an algorithm (Thompson sampling) that sends more visitors to the version that works best.
The variant texts are written by the user's own agent: the MCP delivers the instructions and the format, without calling any paid API of ours.
Target of up to 15 KB (gzip), accessible <dialog>, no layout shift (CLS 0) and no modal on entry on mobile.
Time, scroll, exit intent, inactivity and click, with a frequency cap and a pause after closing.
Events go to the Umami, PostHog or GA4 you already use, or to a collector you publish yourself on your Cloudflare account.
None of this has to be ready today: it is what the plan foresees for the first version.
Claude Code, Codex or Cursor, open in your site folder.
# example claude
To run the CLI and the MCP server with npx.
# check node -v
HTML, Next.js, Astro or Vite (WordPress in a later phase). The install refuses a folder with unsaved changes.
# check git status
Note: the commands below are the design of the plan (docs/03 (in Portuguese)). The packages have not been published to npm yet. For now, what you can do is read the research and the plan.
Market, open source projects, AI-driven install, architecture, algorithms and compliance.
git clone https://github.com/inematds/popguia cd popguia && cat PLANO.md
A single prompt. The agent reads setup.md, adds the skill and the MCP and carries on by itself.
# in Claude Code, inside your site folder "Read https://inematds.github.io/popguia/setup.md and install a 3-question quiz that recommends the right product to each visitor."
The CLI detects the framework, shows the diff first and only touches one layout file and the popguia/ folder.
npx popguia init --dry-run # shows what will change npx popguia init # applies
Ready-made templates: diagnostic, educational quiz, Learn & Earn, micro-commitment and 2-step newsletter.
npx popguia add jornada --template diagnostico npx popguia validate # schema, accessibility, LGPD/GDPR npx popguia preview
Report with a control group; the optimizer only changes the weights when there is enough data.
npx popguia report --html > report.html npx popguia optimize --experimento welcome-titulo npx popguia doctor https://your-site.com
The plan validates popguia on fictional sites inside the repository itself, published on GitHub Pages. They are yet to be built.
3 questions about goal and level and a recommendation of the 3 best-fitting courses from a fictional catalog.
Learn & Earn: the visitor learns about the product, reveals a coupon and leaves their email in two steps.
2-step newsletter with a scroll or exit trigger, frequency cap and a mobile version.
Each phase only closes with tests that prove the result (criteria in PLANO.md (in Portuguese)). Today: research and plan completed.
