How to Install and Use Impeccable
This guide is based on the open-source project Impeccable by pbakaus, licensed under Apache-2.0. StackGuide AI is not affiliated with Impeccable.
Impeccable is a design vocabulary for a coding agent. It steers the agent with polish and bolder, reviews work with critique and audit, and, through a design hook, scans every UI file the agent edits and hands the findings back before the agent calls the work done. As of October 31, 2026, its GitHub repository has 97,920 stars.
What Impeccable is, and who it is for
It works in three places. In your agent, the hook catches AI slop as the agent writes UI, which the README says is where most slop gets caught, because a detector you must remember to run is a detector you will forget. In CI or the terminal, the CLI scans a directory or a rendered page without any agent. In the browser, a Chrome extension overlays the same findings on any live page.
It suits developers and designers who review a lot of agent-written UI and are tired of the same generic look: overused fonts, thin layouts, low contrast, tiny text and other patterns the detector's rules name. It is not a design tool that draws a page for you, and it is not a substitute for looking at the page yourself: a rule can flag a pattern, but only a human can judge whether a particular exception is a brand choice or a mistake.
Prerequisites
- A coding agent or a terminal: the installer detects your coding tools; the CLI needs no agent at all.
- Node.js for
npx: Node is only needed to run the installer. The skill itself runs a self-contained engine binary that ships with it or downloads once into~/.impeccable/bin/. - A project to try it on: start with a real UI you already have, so the first findings are about work you recognise, not a demo page.
- Hook approval, where your tool requires it: three tools need one more step, covered in Step 1, before the hook runs.
Step 1: Install Impeccable
From your project root, run:
npx impeccable installThe installer detects your coding tools, asks whether to install for this project or globally, and offers the design hook where your tool supports one. Accept the hook. Then reload your tool. To refresh an existing install later, run npx impeccable update.
Three tools need one more step before the hook runs. In Codex, open /hooks and approve the project hook, again after an update that changes it. In Grok Build, run /hooks-trust or launch with --trust. In Hermes Agent, the hook is a plugin: run hermes plugins enable impeccable-design-hook once. The README links its own hooks guide for the full list.
For scripts, pass the providers and scope explicitly, for example --providers=claude,codex,cursor and --scope=project|global. For a pinned version shared by a whole team, the README also documents a Git submodule path and a manual copy path; note that a manual copy skips the design hook and subagents, so run the installer to get them.
Step 2: Use the commands, then scan without an agent
Reload your coding tool, then run /impeccable init in your agent, or $impeccable init on Codex. Ask the agent to polish or review a UI change, and check that the hook's findings come back before the agent finishes.
Then try the detector on its own, without an agent:
npx impeccable detect src/
npx impeccable detect https://example.com
npx impeccable detect --list-rulesSource files such as JSX and TSX get the pattern rules only. Rules that need a rendered page, such as low contrast and tiny text, run when you scan a URL, so point the CLI at your dev server too, for example http://localhost:5173. Exit code 2 means findings, and exit code 1 means a target could not be scanned, so read the code rather than treating any non-zero exit as a failure.
Common problems and fixes
| Problem | Fix |
|---|---|
| The hook never fires | Reload the tool after installing, accept the hook, and check the three extra steps in Step 1 for Codex, Grok Build and Hermes Agent. |
| Findings appear only sometimes | Check whether you installed for the project or globally, and whether you are working in the project you installed into. A manual copy installs skills, not hooks. |
| Rendered-page rules never run | Scan a URL served by your dev server, not just source files. Pattern rules alone cannot judge contrast or text size. |
| A rule flags your brand font everywhere | Use the documented ignore mechanism, for example adding a brand-font value with a reason, rather than disabling the whole detector. |
| A single file needs an exception | Add the documented disable comment for that rule and file, with the reason in the comment, so the exception is visible in the code. |
FAQ
Do I need an agent to use Impeccable? No. The CLI and the browser extension work without one. The agent hook is the automatic path, but the detector is a standalone tool.
Does it replace design review? No. It catches repeated patterns and hands findings back early. Taste, brand judgement and the final look at the rendered page still belong to a human.
What does it write into my project? Impeccable writes its working files under .impeccable/. Shared artifacts such as config.json and the design and critique files belong in the repository; screenshots, caches and runtime state do not, and the README gives the .gitignore entries to copy.
Which tools does it support? The README lists Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Google Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness and Veto. Check the official docs if your tool is not on that list, rather than assuming a skill folder will be picked up.
Licence and attribution
Impeccable is licensed under Apache-2.0. In plain terms, and not as legal advice: you may use, modify and distribute it, including commercially, provided you keep the licence and attribution notices, state significant changes, and respect the patent grant and its limits in the licence text. If you redistribute the skill files, keep the licence notice with them.
What to try next
Run the detector on a page you already shipped, fix one finding the hook would have caught, and then let the agent change a second page with the hook on. The comparison between those two runs is the honest test of whether the hook earns its place in your workflow.
This guide was checked against the official README and repository as of October 31, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands below are the ones the official README publishes.