breakhound

Find where your layout breaks across every viewport width, then hand the fix to your coding agent.

Instead of dragging the browser or clicking through device presets, run one command in your project. breakhound finds your framework and dev server (and starts it if needed), discovers every route, sweeps each page from 320px to 1920px in a real browser, finds the exact pixel where things go wrong, and tells you why:

✔ Next.js running at http://localhost:3000
✔ 14 routes from src/app (2 dynamic, filled in from links on your pages)
breakhound 1.0.0 · 14 pages · 320–1920px

  ✖ /pricing        2 issues · layout changes at 768, 1024   4.1s
  ✔ /about          clean · layout changes at 640, 1024      3.2s
  ✖ /blog/[slug]    1 issue · layout changes at 768          3.8s  as /blog/hello-world
  ...

  ✖ error    320–599px      Page scrolls horizontally (280px wider than the viewport)
              div.pricing-table · /pricing
              → It stays 600px wide no matter the screen size. Replace the fixed width
                with max-width: 100% (or a fluid width) so it can shrink.
  ⚠ warning  768–919px      Row of 6 items wraps onto 2 lines
              header nav ul · /pricing, /blog/[slug]
              → Collapse this row into a menu below this width, tighten its spacing, or
                let it scroll sideways.

  Report  .breakhound/report.html  (npx @seybel/breakhound report to open it)
  Fix it  npx @seybel/breakhound mcp install  so your agent can scan, verify and undo by itself

Quick start

In your project folder:

npx @seybel/breakhound

No config needed. It works with Next.js, Nuxt, SvelteKit, Astro, Remix, React Router, TanStack Router, Vue, Angular and plain Vite apps, at the root of a monorepo too, and follows links on anything else. Chromium downloads the first time (about 150 MB).

To type breakhound on its own, install it globally with npm i -g @seybel/breakhound, or add it to your project with npm i -D @seybel/breakhound.

What it finds

Pages that scroll sideways, content spilling out of its box, media that doesn't shrink, overlapping content, nav rows and labels that wrap, clipped and squished text, text too small or too big for phones, small tap targets, distorted images, text against the screen edge, and a missing viewport tag.

Every issue comes with the exact widths where it happens, the element to blame, the numbers behind it, a screenshot, and a likely fix. It also opens menus, dialogs, tabs and accordions and checks them open, can check Safari's and Firefox's engines too, and is built to stay quiet on carousels, off-canvas menus and other patterns that only look wrong. All the checks →

Three ways to use it

In the terminal, as above. Pages behind a login, dynamic routes, staging servers and big apps are all covered in recipes.

In Chrome, with the breakhound extension: right-click any page, from localhost to production, and choose Scan with breakhound. A timeline fills in live as the page grows from 320px to 1920px. More →

With your coding agent. breakhound doesn't edit your code: your agent does, and breakhound checks its work at every width.

npx @seybel/breakhound mcp install

That sets it up for Claude Code, Cursor, VS Code, Antigravity, Windsurf and Codex. Then ask your agent to fix the responsive issues: it can scan, verify that each fix didn't break another width or page, commit each fix on its own, and undo it. No MCP? npx @seybel/breakhound prompt --copy gives you instructions to paste into any agent. More →

In CI

- uses: Seybel/breakhound@v1
  with:
    fail-on: error

It starts your dev server (or scans a preview deployment), turns each issue into an annotation, and uploads the report as an artifact. More →

Docs

• Getting started and your first scan
• Recipes for common jobs
• Configuration and the CLI

Contributing

Found a false positive, or a bug breakhound missed? That's the most useful thing to report. See CONTRIBUTING.md for that and for working on the code.

License

MIT