# Set up PixilUI in this project

These steps are for a coding agent (Claude Code, Cursor, Codex or another) that was asked to set up PixilUI. Run the commands yourself, in order, in the project's root folder. Ask the person only where a step says to. Finish with the report in step 6, and do not commit: the person reviews the changes.

PixilUI is a shadcn registry of React components for AI products. Items install as source into `components/pixilui/` and read their tokens from `components/pixilui/foundation.css`. The whole library for agents is at https://pixilui.com/llms.txt.

## 1. Check the project

- Read `package.json`. PixilUI needs React 19 and Tailwind CSS v4.
- On Tailwind 3, stop and tell the person: PixilUI needs v4, and `npx @tailwindcss/upgrade` moves the project. Do not upgrade without asking.
- Find the package manager from the lockfile: `pnpm-lock.yaml` is pnpm, `yarn.lock` is yarn, `bun.lock` or `bun.lockb` is bun, otherwise npm. Use it for every command below (`pnpm dlx`, `yarn dlx`, `bunx --bun` in place of `npx`).

## 2. Add the registry, the foundation and the rules file

```bash
npx pixilui@latest init --yes
```

This one command:

- runs `shadcn init` with its defaults when there is no `components.json`;
- adds `"@pixilui": "https://pixilui.com/r/{name}.json"` under `registries` in `components.json`, keeping every other registry;
- installs the foundation (tokens, motion presets, `cn`) and the npm packages it needs (`clsx`, `tailwind-merge`);
- writes the rules file: a PixilUI block in `AGENTS.md` (the rest of the file is kept) and `.cursor/rules/pixilui.mdc`.

It is safe to run again; nothing is added twice.

If the person asked for a design style (`quiet`, the default, or `lively`), add `--style <name>`: it also sets `data-style="<name>"` on `<html>` (Next.js `app/layout.tsx`, Vite `index.html` or an Astro layout) and names the style in the rules. Do not pick one for them; without the flag the app stays on the default.

If the PixilUI CLI cannot run, do the same by hand: add the registry line above to `components.json`, then run `npx shadcn@latest add @pixilui/foundation`. Fetch https://pixilui.com/r/skill.json and copy `INSTRUCTIONS.md` from it into `AGENTS.md` as the rules.

Never pass a Pro key and never ask for one. If the person has PixilUI Pro, tell them to run `npx pixilui@latest login` themselves: it opens their browser.

## 3. Connect the MCP server

The server at `https://mcp.pixilui.com/mcp` lets you search the library, read an item and get its install command from the chat. Free items need no login. Connect the one for the agent you are, and keep any servers already configured.

| Agent | Do this |
| --- | --- |
| Claude Code | `claude mcp add --transport http --scope project pixilui https://mcp.pixilui.com/mcp` (writes `.mcp.json`) |
| Cursor | Add `"pixilui": { "url": "https://mcp.pixilui.com/mcp" }` under `mcpServers` in `.cursor/mcp.json`, creating the file if needed |
| Codex | `codex mcp add pixilui --url https://mcp.pixilui.com/mcp` |
| VS Code (Copilot) | Add `"pixilui": { "type": "http", "url": "https://mcp.pixilui.com/mcp" }` under `servers` in `.vscode/mcp.json` |

If you cannot run the command or edit the file, say so in the report and give the person the line. A new server is usually picked up in the next session, not this one. Other clients and the Pro login: https://pixilui.com/docs/mcp.

## 4. Make sure the rules load

`init` wrote `AGENTS.md` and `.cursor/rules/pixilui.mdc`. Check both exist and hold the PixilUI rules.

- Claude Code reads `CLAUDE.md`. If there is one and it does not mention `AGENTS.md`, add a line `@AGENTS.md` at the end. If there is none, create `CLAUDE.md` with that one line.
- Claude Code only: also run `npx pixilui@latest skill`. It installs the PixilUI skill into `.claude/skills/pixilui/`, where Claude Code loads it on its own.

## 5. Check it works

- The global stylesheet named in `components.json` (`tailwind.css`) imports `tailwindcss` first, then `components/pixilui/foundation.css`. In a Next.js app that is `@import "../components/pixilui/foundation.css";` in `app/globals.css`. Fix the path if it does not resolve.
- If the project has a quick typecheck (`tsc --noEmit` or a `typecheck` script), run it and fix only what this setup broke.

## 6. Report what changed

End with a short report for the person:

- every file you created or changed, one line each, with what changed (for example `components.json: added the @pixilui registry`);
- the commands you ran;
- anything you skipped, and why;
- one next step to try, such as: "Add a PixilUI approval card before the agent sends the email. Read https://pixilui.com/components/approval-card/markdown first."

If the person asked for an item as well ("then add @pixilui/approval-card"), install it after step 5 with `npx pixilui@latest add approval-card`, read its page first, and list its files in the report.