Get started
Install the Crocotaste GitHub App on the repositories you pick, link the installation to your account, then open a UI pull request. About three minutes.
Crocotaste is a GitHub App and nothing else. There is no CI step to write, no package to add, no configuration file to keep current.
Installing a GitHub App needs the right account permission: the owner of a personal account, or an owner or app manager of an organization. If you are neither, GitHub offers to send the request to someone who is.
1. Install the GitHub App
Open the App on GitHub, choose the account, choose the repositories, install. Private repositories work exactly like public ones. The App asks for these repository permissions and no others:
| Permission | Access | Why |
|---|---|---|
| Contents | read | to read your design system and the pull request diff |
| Pull requests | write | to post the summary comment, inline findings and the approving review |
| Checks | write | to post the check run (with its JSON for agents) |
| Issues | write | to open the one onboarding issue |
| Metadata | read | required by GitHub for every App |
Read is read. Crocotaste never commits, never opens a pull request, never edits a file; permissions is the long version.
Pick a repository that gets UI pull requests. One with a stylesheet full of tokens, a Tailwind config, or a components/ directory gives the first review something to cite.
2. Sign in and link the installation
GitHub redirects you back to Crocotaste when the install finishes. Sign in with GitHub, and the setup page confirms the installation and the repositories it can see.
Signing in authorizes the same App, so there is no second one to approve. It asks to read your account's email addresses, which is what your Crocotaste account is made from.
The link is checked against GitHub, not asserted: your account has to be able to reach that installation itself, and Crocotaste asks GitHub again on every visit. Anyone on your team who passes the same check sees the same dashboard: the balance, the review ledger per repository, the Re-run button and the review mode.
The balance belongs to the GitHub account, not the installation, so it survives uninstalling and reinstalling. Two organizations means two accounts: two balances, two trials, and two plans if you buy them.
3. Ask your coding agent for a DESIGN.md
On the setup page, choose "Open an issue with instructions for your coding agent". Crocotaste opens one issue per repository titled "Generate your DESIGN.md", holding a collapsed block of instructions. Hand that block to Cursor, Claude Code, Copilot, Codex or whatever your team uses; the agent reads the repository and opens a pull request adding the file. You review it, edit it, merge it. That merge is the point, because a file your team merged is a file your team meant. Generate your DESIGN.md walks through it.
You can skip this step. Reviews run on what the repository already contains and the summary says parsed system only instead of naming the file.
A repository whose DESIGN.md already declares a system gets no issue. Crocotaste reads the file when it first sees the repository, at the root or in docs/, and the setup page lists that repository as "DESIGN.md read". A DESIGN.md that reads as nothing, one in another shape with no YAML front matter, is asked for like a missing one.
4. Open a UI pull request
The first three reviews are free, no card. A pull request that was already open when you installed gets a review too: comment @crocotaste review on it. A clean change gets an approving review and a green check with the pass enumerated:
On-system · 6 files · 42 tokens · 12 components · 9 decisions · 0 violations
A drifted one gets cited findings, a committable suggestion, and a prompt for the agent that wrote the code; a violation turns the check neutral until it is fixed or dismissed.
Nothing goes red. The worst a check does is go neutral, with its findings or the next step on its title.
Adding repositories later
Change the repository selection on GitHub, under the App's installation settings. New repositories start reviewing immediately; a repository removed from the installation stops, and its history is kept in case it comes back.
The review mode lives in the dashboard, per repository: automatic, on demand (only @crocotaste review and Re-run start one) or paused. No GitHub event ever changes it; only you do.
Next
Your first review breaks down what lands on the pull request and in what order. Billing and reviews explains what the three free reviews are counted against.