🪱 Gribble
Tiny bugs that find your bugs before you ship.

Gribble is an AI-driven website quality audit agent that runs during development: before a PR, in CI, and before a release. It walks every flow of your site like a picky code reviewer, checks broken links, UI best practices and your own guidelines, SEO, accessibility and performance, and points each finding at the source file that caused it.

A gribble is a tiny marine isopod that bores holes into ship hulls from places nobody looks. We named the pest hunter after the pest.

Install

Tell your coding agent (Claude Code, Cursor, pi, Codex, …):

Set up Gribble in this project by following https://gribble.dev/setup.md

It installs Gribble, runs init, records the first baseline, and asks you which model to use. Afterwards, ask it to fix findings, add flows or wire up CI: see Working with your agent.

Or by hand:

pnpm add -D gribble
pnpm exec gribble install   # downloads the Playwright browser
pnpm exec gribble init      # creates .gribble/ and (optionally) a skill for your coding agent
pnpm exec gribble audit     # let the gribbles chew on it

A fresh install for gate mode brings no model runtime (upgrading from 0.3 with pnpm? read this). review and all need pi, which ships as optional peer dependencies no package manager installs on its own:

pnpm add -D gribble @earendil-works/pi-ai @earendil-works/pi-coding-agent

How it works

• gate mode runs deterministic checks (links, network, SEO, axe, Lighthouse thresholds, UI hard rules, replay of fixed flows). Fast, reproducible, can block a merge.
• review mode lets an AI agent explore your site, walk the flows described in .gribble/flows/*.md, judge the UI against .gribble/guidelines.md, and propose fixes. It never blocks a merge; it comments.
• Everything is a diff against the baseline on main: new holes are reported, known ones are counted, patched ones are celebrated.

Gribble is a shell around pi: the agent loop, model catalog and auth come from pi's SDK, the audit tools and guardrails come from Gribble.

Packages

Package	Description
gribble	The CLI you install as a devDependency
@gribble/core	Harness, tool packs, config and flow parsing, report schema
@gribble/action	GitHub Action wrapper (gribble-dev/action)
@gribble/skills	Skill files that teach your coding agent to feed the gribbles
apps/website	gribble.dev (SvelteKit on Cloudflare Workers)

Documentation lives in docs/ and is published at https://gribble.dev/docs.

Development

pnpm install
pnpm build
pnpm test

See CONTRIBUTING.md for conventions.

License

MIT