Install & first steps

You’ll need a coding tool, a project folder, and Node.js 22.18 or later. An empty project or freshly scaffolded app is fine.

Which coding tools can I use?

Impeccable supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Pi, and other coding tools. The installer lets you choose your tool and installs the matching build.

Using the GitHub Copilot app? Impeccable is built in. Enable it in Settings → Experimental, then skip to step 2. You don’t need the terminal installer for this route.

For other install methods, see installation options on the homepage.

1. Install Impeccable

In your terminal, open your project folder and run:

npx impeccable install

Follow the prompts to choose your coding tool and install for this project or all your projects. Then reload your coding tool.

For other methods, see installation options on the homepage.

Keep a shared team version with a Git submodule

From your project folder, add Impeccable as a submodule and link the coding tools your team uses:

git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor

Replace claude,cursor with your team’s providers. To use an existing local checkout instead, point --source at that folder. Linking uses the local source; you do not need a global Impeccable installation. Existing skill directories stay in place unless you explicitly replace them with --force.

Commit .gitmodules, the submodule reference, and the generated links. Teammates fetch the recorded version with:

git submodule update --init --recursive

To adopt a newer version, update the submodule, refresh the links, and review and commit the new reference:

git submodule update --remote vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor

Reload your coding tool after installation or an update. Linking installs the skills, not the design hooks; follow automatic check setup and your tool’s trust requirements separately.

The remaining commands go in your agent chat. Choose your coding tool in any command box; the examples will use its syntax.

Not showing up, or enabled automatic checks?

If Impeccable doesn’t appear after reloading, run the installer again and check your coding tool and installation scope.

If you enabled the automatic design hook, allow it to run in your coding tool. It checks UI edits and sends findings back to your agent.

2. Give Impeccable the context for your project

Impeccable needs to know who your project serves and what those people need to do. Save that context with:

/impeccable init

Impeccable reads the project first, then asks you to fill the gaps. Describe the people who will use it and the decisions their needs should shape. For example:

Our customers reorder the same supplies every week. They need to find their usual items and check out quickly, often on a phone.

Include anything the work must preserve, such as established product names or accessibility requirements. You can leave colors and fonts for the design work.

Impeccable saves the agreed context in PRODUCT.md. Read it before moving on. Correct anything it misunderstood; future commands will use this file to guide their work.

Choose how new designs start

Mockup first (comp-led) can push the visual direction further, but translating the image into code loses detail; expect a few rounds of prompting and review. Build directly (code-led) tends to give you a more coherent first implementation, with less ambitious visuals. Both paths include a design direction and review.

Init may ask which path to save as the default. You can switch in the design picker later. Compare workflows and defaults.

Already have a design system? Record it before you build

/impeccable document

Impeccable reads the interface and records colors, typography, and component rules in DESIGN.md. Review the file so later work follows the decisions you want to keep. Skip this for an unstyled scaffold.

See Work with a design system for the workflow.

3. Choose your first task

Ordinary language is enough. Choose the path that fits your project:

Build something newCreate a page or redesign an interface.
Improve an existing designRefine a page while keeping what works.

Build something new

Describe a page, its audience, and what visitors should be able to do:

/impeccable design a signup page for our monthly book club. Help visitors understand the next event and reserve a seat.

Impeccable helps resolve missing details, develops a direction you can choose and steer, then builds and reviews the interface. In the mockup-first workflow, you approve a composition before implementation. A new page inside an established product follows that product’s visual system.

Follow Build something new for the direction picker, mockups, redesigns, and what carries into future sessions. Use shape if you want to stop at a plan before implementation.

Improve an existing design

Describe what feels wrong, or name a page for a focused polish pass:

/impeccable polish the pricing page

polish refines spacing, typography, labels, and interaction states within the existing design. Add any constraints to your request: “Keep our colors and the current plan names.”

Unsure what needs fixing? Ask for /impeccable critique the pricing page, read the findings, then choose what to address. See Improve an existing design for examples.

4. Review the result

Open the page and try its main task. Can you reserve a seat, or compare the pricing plans and choose one? Check a narrow screen too, and review the code changes.

Tell your agent what to keep or adjust. For example:

The plan comparison is easier to read now. Keep that, but restore the monthly/yearly switch above it.

If the overall design still feels wrong, describe what you want to change or ask for a redesign. A polish pass is for refining the design you have.

What to try next

Keep future pages consistent: Work with a design system to record shared decisions and reuse existing components.
Compare visual alternatives: Generate variations by naming an element and direction in chat, or pick it in Live Mode. Compare on the page and accept one into your code.
Check before shipping: /impeccable audit the pricing page reviews accessibility, performance, responsive behavior, and other implementation issues.

To update an installation made with npx impeccable install, run npx impeccable update in your terminal. Marketplace installations update through your coding tool’s plugin menu.