Arbiter

The decision layer for agent-built UI

Website · Live demo · Start guide · Changelog

Quick start · How it works · Share with your team · Commands · FAQ

What is Arbiter?

Arbiter is a decision record for teams building UI with AI agents like Claude Code and Cursor.

As your agent builds, it writes down the design calls it makes: what it chose, what it beat, and why. You approve them in seconds. The agent follows them next time, and everyone on your team can read them.

It's documentation that writes itself.

What you get

Consistency

Your agent follows your design rules. Make a call once and it becomes a rule in DECISIONS.md, which the agent reads before any UI work. No more re-explaining.

Traceability

Build fast without losing the why. Every design decision and change is recorded as it's made: what was chosen, what it beat, who decided and when.

Visibility

See every decision in one place. Publish a board so you and your team can see each screen, the decisions made on it, and what lost.

Why Arbiter

Building with an agent means making product decisions all day, and nobody keeps track of them.

• The agent forgets between sessions. On Tuesday you tell it "no tabs, keep settings on one page." On Thursday, in a new session, the tabs are back.
• Nothing gets written down. Five screens ship before lunch, each one full of calls about layout, copy and flow. None of them are recorded anywhere.
• The reasoning gets lost. Someone asks in review why it's a modal. There was a good reason, but it was in a chat three weeks ago.

Arbiter fixes that without adding work:

• 📄 It's just files in your repo. Rules live in DECISIONS.md. Plain markdown, reviewed in pull requests like everything else.
• 🤫 It stays out of the way. No popups while you iterate. The agent queues what it decided and you judge it when you're ready.
• 🧭 It informs, it doesn't enforce. Rules shape what the agent builds. Nothing blocks a build.

Quick start

npx arbiterdesign init

[!NOTE] On Windows, in PowerShell, type npx.cmd instead of npx, here and in every command after. PowerShell blocks plain npx out of the box, with "running scripts is disabled on this system". Command Prompt and Git Bash don't.

That's the whole install. Run it in the folder your agent works in, or ask the agent to run it. It detects Claude Code or Cursor, teaches your agent the protocol, and adds arbiterdesign to your devDependencies, which is what makes the shorter npx arbiter work from then on. Running it twice changes nothing.

It asks one question, once: how often the agent should check in about decisions while you work. If the agent ran the install, it asks you in chat instead.

No package.json in the project? Add arbiterdesign as a dev dependency yourself. New to the terminal? Follow the step-by-step guide.

If you want the agent to take screenshots of the screens it changes, tell it where your app runs:

npx arbiter setup --app http://localhost:3000

Then build UI the way you normally do. Arbiter picks it up from there.

File	What it's for
DECISIONS.md	Your active rules, grouped by type. Capped at 40. The agent reads this before UI work.
.arbiter/archive.md	Every decision ever made, append-only. Never loaded into the agent.
.arbiter/pending.md	Decisions the agent queued that you haven't judged yet.
.arbiter/candidates/	One page per generated screen or direction: its state, snapshot, decisions, and why it lost.
.arbiter/work/	One picture per piece of work, when the agent could take one. publish carries it to the board.
.arbiter/hosted.json, comments.json, requests.json	Which hosted board is yours, and the comments and change requests pull brings back.
CANDIDATES.md	Index of candidates. Only written when destination is git.
.claude/skills/arbiter/SKILL.md or .cursor/rules/arbiter.mdc	Tells the agent to check your rules before UI work, ask when something clashes with one, then surface its decisions and record what you confirm.
arbiter.json	Config. app.url is where the agent opens screens for pictures.
AGENTS.md	One line appended, pointing at DECISIONS.md. It tells the agent to ask before building when your request or the design system goes against a rule, and that a rule written as an exception beats the design system. Merged, never overwritten. A newer init refreshes only that line.
CLAUDE.md / .cursor/commands/arbiter.md	The same pointer for Claude Code, and an /arbiter command for Cursor.

This is the beginning of the README. Read the rest at the original. Read the full README ↗