Your agent builds the UI. Coherent holds every edit to account.
Agent mode puts Coherent inside your coding agent’s loop. The agent designs and writes code with its own tools; for each change it declares what it will touch, and Coherent checks the result in a real browser before the edit counts.
Install
In an empty folder init runs the official create-next-app and shadcn init and adds a welcome page; in an existing app it adds the agent only. Running it again updates the agent files. Then open the folder in Claude Code (CLI or desktop) and approve the coherent MCP server once. For Codex: codex mcp add coherent -- npx --no-install coherent mcp --profile agent.
| File | What it does |
|---|---|
| .claude/agents/coherent.md | The Coherent agent: how to scope, declare, verify and report. |
| .mcp.json | The coherent MCP server (coherent mcp --profile agent). Your other servers are kept. |
| .claude/settings.json | Makes coherent the default agent (unless you already have one) and adds the write guard hook. Merged with your settings. |
| AGENTS.md | A managed section with the same rules for agents without hooks, such as Codex. |
| .gitignore | Local state under .coherent/ (transactions, screenshots). |
| package.json | @getcoherent/cli and playwright as dev dependencies, installed with your package manager. |
The five tools
Coherent does not draw the interface. It gives your coding agent five tools: map the app, declare a change, check it, undo it, and build the design-system section. Designing is the agent’s job.
| Tool | What it does |
|---|---|
| coherent_inventory | The app as a graph from its code: pages, layouts, shared components, imports. The design system: every component with its ID, every token with the components that use it. The open edit, if any, and files changed outside Coherent since the last edit. |
| coherent_begin_edit | Scope (tokens, component, variant, page, new-component) and the files to modify or create, plus an optional target (CID-008, KpiCard, --radius) that holds the edit to exactly that. Returns every route those files reach and which must stay identical, IDs for new components, takes the "before" render and opens a transaction. amend adds files to the open edit, under the same rules. |
| coherent_verify_edit | fast: write set, new type errors, identity leaks, in seconds. final: plus a production build, renders, pixel diff and browser errors; commits the edit unless it failed. Returns warnings for hardcoded colors and sizes the edit added. |
| coherent_rollback_edit | Restores only that edit’s files, byte for byte. Refuses if a newer edit touched them, unless forced. |
| coherent_ds_sync | Gives every component an ID and writes the /design-system section of the app, as one verified edit in which the pages are checked to render exactly as before. Later edits keep it current. |
What final verification checks
- Only the declared files changed (the whole project is diffed, not just what the hook saw).
- No new TypeScript errors compared with the state before the edit.
- A production build succeeds.
- Every affected route (up to 12 per edit) rendered on desktop and mobile, and at least one of them changed; any not rendered are named in the verdict.
- Control routes are pixel-identical (±1 per channel for anti-aliasing).
- No new console, page or hydration errors. The browser runs in Pacific/Kiritimati with the de-DE locale, so server/client mismatches surface.
- No real names or emails from git config in the UI.
- Once the app has a design system: every new or touched component carries its own ID.
Verdicts
A verdict is never better than the checks that actually ran, and the agent is told to report it exactly as returned. It can’t switch renders off to get a faster pass: only a person can, from the CLI.
| Verdict | Meaning |
|---|---|
| verified | Every check ran and passed: affected routes changed, controls identical, no new errors. |
| partially_verified | Passed, but some coverage is missing, for example a dynamic route with no example URL. |
| verified_without_visual | Code checks passed, but nothing was rendered: renders were switched off from the CLI, or no browser was available. |
| blocked_by_preexisting_failure | The project already failed its checks or build before the edit, so nothing could be rendered and the result can’t be proven. |
| failed | A check failed. Not committed: fix and verify again, or roll back. |
Where the boundary is
In Claude Code a PreToolUse hook denies writes outside the open edit, with a message saying which tool to call. That is fast feedback, not enforcement: shell commands, subagents and your IDE go around it. The boundary is verification, which compares the whole project before and after. Agents without hooks, like Codex, are covered the same way, and the inventory lists any files changed outside Coherent since the last edit.
The hook lives in the project’s settings, so it applies to every Claude Code session in that project, not only the Coherent agent. Remove the coherent hook pre-write entry from .claude/settings.json to opt out.
Limits today
- Next.js App Router projects only.
- Dynamic routes need an example URL in .coherent/preview-params.json, e.g. {"/items/[id]": "/items/1"}.
- Pages that depend on live data or the current time need fixtures to compare cleanly.
- Yarn Plug’n’Play is not supported; Windows is untested.
- Tested end to end with Claude Code. Codex is set up through AGENTS.md and the MCP server; other MCP clients can call the same tools but are untested.
Why Coherent stopped generating UI: ADR-0011. How agent mode is built: ADR-0012. Upgrading from the generator: migration guide.