pbakaus/impeccable
The design language that makes your AI harness better at design.
How impeccable is put together
Impeccable is a design-guidance toolkit for AI coding agents, distributed as an npm CLI (`npx impeccable`), provider-native skill folders for ~16 AI harnesses (Claude Code, Cursor, Codex, Gemini CLI, Grok Build, etc.), a Claude Code plugin/marketplace package, and a browser extension with DevTools panel. The core is a deterministic anti-pattern detection engine (59 rules) written in plain Node ESM JavaScript that parses HTML/CSS via htmlparser2/css-tree/css-select and runs with no LLM or API key; LLM-driven behavior lives in markdown skill/command definitions (SKILL.md plus 30+ reference docs) that instruct the agent. A build pipeline (Bun + custom scripts) compiles the canonical skill source into per-provider dist folders, and a live-mode feature lets agents iterate on designs in a real browser via Puppeteer/Playwright.
Languages
Frameworks
Infrastructure
Major components
CLI installer/updater
`cli/bin/cli.js` implements `impeccable install/update/link`, detecting harness folders (~/.claude, ~/.codex, .cursor, ...) and writing skill files and hook manifests into them.
Anti-pattern detection engine
`cli/engine/detect-antipatterns.mjs` and `detect-antipatterns-browser.js` run 59 deterministic HTML/CSS detector rules with no LLM, exported as the package main and browser build.
Detector rule registry & checks
`cli/engine/registry/antipatterns.mjs` and `cli/engine/rules/checks.mjs` define the rule catalog and individual checks, supported by shared helpers (color, fonts, page, inline-ignores).
Skill content (commands & references)
`skill/SKILL.src.md` plus `skill/reference/*.md` define the `/impeccable` command vocabulary (23 commands like init, audit, polish, live) as prompt instructions for AI agents.
Provider dist & subagents
Compiled per-provider skill folders (.claude/, .cursor/, .agents/, .gemini/, .grok/, .trae/, plugin/, etc.) each carry SKILL.md, reference docs, and four agent definitions (asset-producer, documenter, finish-reviewer, manual-edit-applier).
Hook manifests
Provider-native hook configs (.codex/hooks.json, .cursor/hooks.json, .grok/hooks/impeccable.json, plugin/hooks/hooks.json) wire Impeccable into harness lifecycle events.
Browser extension
`extension/` contains a Manifest V3 extension (background service worker, content script, popup, DevTools panel/sidebar) that surfaces detector findings in-page.
Build, test & release tooling
`scripts/build.js`, `build-browser-detector.js`, `build-extension.js`, `run-tests.mjs`, and `release.mjs` compile skills to dist targets, run layered test suites (core/detector/e2e/live), and publish skill/CLI/extension releases.
A focused week of reliability fixes around AI-provider hooks, making sure background processes shut down cleanly and provider-specific quirks are handled.
5 weeksWeek of 2026-08-24
Week of 2026-08-24latest
A focused week of reliability fixes around AI-provider hooks, making sure background processes shut down cleanly and provider-specific quirks are handled.
Week of 2026-08-17
The busiest recent stretch of scanner accuracy work: fixing false positives in color parsing, comment handling, and grid detection, plus tightening security around the live preview server.
Week of 2026-08-10
A large week capped by new releases (skill v4.1.x, CLI v3.6.0, extension v1.3.2), with major fixes to the guided build flow and how the tool judges visual fidelity against reference designs.
Week of 2026-08-03
Heavy investment in cross-platform reliability (especially Windows) and in the copy-edit/verify pipeline, alongside richer visuals for the concept-picking pages.
Week of 2026-07-27
The biggest week by volume: two new AI providers joined the lineup (Google Antigravity and Hermes Agent) while the team cut startup overhead and hardened security for non-local development hosts.
Over the past month this repo (a design-quality toolkit for AI coding agents) has been in a heavy bug-fixing and polish phase, with a steady stream of fixes to how it scans code, parses colors and CSS, and talks to different AI providers like Grok, Codex, Claude, Gemini, and Antigravity. The team also shipped new releases of the skill, CLI, and browser extension, added support for new agent platforms, and steadily cleaned up internal plumbing so the same logic isn't duplicated across surfaces. The overall arc is one of hardening: fewer false alarms from the scanners, more reliable installs and hooks across operating systems, and clearer guidance baked into the tool's own documentation.
Week by week
2026-08-24A focused week of reliability fixes around AI-provider hooks, making sure background processes shut down cleanly and provider-specific quirks are handled.latest5 changes
Fix
Cleaner shutdowns
Fixed two issues where the context helper process could hang or exit messily by draining its output and closing network connections before quitting.
Fix
Grok hook compatibility
Taught the tool to read Grok's differently-formatted hook messages and to rewrite project-level hooks so they point at the global skill location.
Fix
Codex stop signals
Made the Codex 'stop' hook emit a proper block decision instead of an ambiguous response.
Docs
Trust guidance linked
Added documentation linking readers to guidance on trusting harness hooks.
Chore
Dependency updates
Updated the Bun-related dependencies as a routine maintenance bump.
2026-08-17The busiest recent stretch of scanner accuracy work: fixing false positives in color parsing, comment handling, and grid detection, plus tightening security around the live preview server.6 changes
Fix
Smarter color parsing
Added support for modern oklch colors and nested hex values inside color-mix() so contrast checks stop flagging valid designs.
Fix
Fewer false alarms on comments and grids
Comments in HTML/CSS/Astro files are now stripped before scanning, and single-direction dashed rules no longer get mistaken for grid backgrounds.
Fix
Live server security
Stopped the preview server's /source endpoint from following symlinks that could expose files outside the workspace.
Fix
Safer page-controlled data
Web pages can no longer sneak extra fields into poller data before it reaches the AI agent.
Refactor
Internal cleanup
Centralized framework detection, removed dead parser paths and a redundant MultiEdit tool, and simplified how manual apply failures are reported.
Chore
Regression coverage
Added test fixtures pinning the color, grid, and symlink behaviors so they don't quietly break again.
2026-08-10A large week capped by new releases (skill v4.1.x, CLI v3.6.0, extension v1.3.2), with major fixes to the guided build flow and how the tool judges visual fidelity against reference designs.6 changes
Chore
New releases
Shipped skill v4.1.0/v4.1.1, CLI v3.6.0, and extension v1.3.2 bundling weeks of improvements.
Fix
Comp-fidelity review overhaul
Made the ground-color comparison deterministic and generalized color sampling so builds are judged fairly against reference screenshots.
Fix
Build-path questions fixed
The setup flow now asks about your build setup as its own clear question, records only real answers, and flipping between modes no longer stacks duplicate inspiration slots.
Fix
Svelte variant cleanup
Stopped emitting unnecessary JSDoc type casts into every generated Svelte component variant.
Refactor
Faster static scanning
Selector lookups in the static scanner now compile once per document instead of repeatedly, speeding up scans.
Fix
Direction page stability
Fixed the concept direction page hanging forever after re-rolling, and made zoom targets resolve through a single handler.
2026-08-03Heavy investment in cross-platform reliability (especially Windows) and in the copy-edit/verify pipeline, alongside richer visuals for the concept-picking pages.6 changes
Fix
Windows stability
Fixed crashes on Windows including a libuv abort after concept seeding and the question browser failing to open.
Fix
Safer shell quoting
Replaced fragile JSON-based shell quoting at four execution sites that could break commands with special characters.
Feature
Verify-and-review pipeline
Added a native leg for the verify-and-review pipeline and mapped its evidence and verification steps per platform.
Fix
Install flow improvements
Installing now points you to your agent chat rather than the terminal, and explicitly selected providers install without needing --force.
Feature
Richer decision and direction pages
Upgraded the concept-picker UI with full-fidelity comparisons, a raised cycler, verdict-routed cards, and MY PICK / Safer-Bolder framing.
Refactor
Guidance and parsing cleanups
Restored reduced-motion animation guidance, simplified CSS color channel parsing, centralized critique snapshot reading, and let each world declare which kinds of slop it's most at risk of.
2026-07-27The biggest week by volume: two new AI providers joined the lineup (Google Antigravity and Hermes Agent) while the team cut startup overhead and hardened security for non-local development hosts.6 changes
Feature
New providers supported
Added Google Antigravity (with correct global skills path and regression tests) and Hermes Agent as supported AI providers.
Fix
CORS security for dev servers
Design-hook scans now skip files outside the project root, and token-authorized CORS preflights correctly send Vary: Origin on non-localhost dev hosts.
Refactor
Faster startup
Trimmed the spawn tax by skipping unnecessary agent-definition reads, long waits, and repeated converter probes at boot.
Feature
Cross-harness boot detection
Tool detection at startup and native-first image generation now work consistently across harnesses and operating systems.
Fix
Design data fixes
Fixed wrapped design characteristics, seed component coverage, and clarified where curated patterns come from.
Refactor
Internal simplification
Removed the legacy pattern parser, simplified import graph scanning and curated pattern loading, and shared a containment gate between hook checks.
Dependencies and code review
Dependency advisories
Security Watch
No known advisories across 17 scanned dependencies.
No known advisories in the scanned dependencies.
Code review
No concrete code-level issues confirmed.
Get this report every week for your repos.
GitZoid learns each repo, reports what changed, and flags what needs attention. One flat price for the whole team.
$19 a month, flat · First 10 outputs free · No card required