Skip to content
Back to search

coherent

MarketplaceWorks with Claude CodeGitHub

Coherent: governed, verified UI edits for coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skovtun--coherent-design-method/badge.svg)](/listings/skovtun--coherent-design-method)

HTML

<a href="/listings/skovtun--coherent-design-method"><img src="/api/listings/skovtun--coherent-design-method/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** [Node.js](https://nodejs.org/) 20 or later, and [Claude Code](https://claude.com/claude-code) (CLI or desktop app) or Codex.

New app

npx @getcoherent/cli init my-app

In an empty folder this runs the official `create-next-app` and `shadcn init`, adds a welcome page, and installs the Coherent agent. Open `my-app` in Claude Code and describe what you want; the Coherent agent is the project's default agent, so there is nothing to select.

Existing Next.js app

cd my-next-app
npx @getcoherent/cli init

Adds only the agent; your code is not touched. Run it again later to update the agent files.

As a plugin (Claude Code, Codex)

/plugin marketplace add skovtun/coherent-design-method
/plugin install coherent@coherent

Adds the `coherent` skill: your agent sets Coherent up in a Next.js app when you ask, and follows the governed edit loop.

What init writes

| File | Purpose | |------|---------| | `.claude/agents/coherent.md` | The Coherent agent (prompt + the `coherent` MCP server) | | `.mcp.json` | `coherent mcp --profile agent`: four governance tools | | `.claude/settings.json` | Makes `coherent` the default agent and adds the write guard hook (merged with your settings) | | `AGENTS.md` | A managed section for agents without hooks (Codex) | | `.gitignore` | Local state under `.coherent/` | | `package.json` | `@getcoherent/cli` and `playwright` as dev dependencies, installed with your project's package manager |

Dynamic routes (`/orders/[id]`) need an example URL to be screenshotted; init lists them and tells you where to add one (`.coherent/preview-params.json`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "coherent",
  3. "description": "Coherent: governed, verified UI edits for coding agents",
  4. "owner": {
  5. "name": "Sergei Kovtun",
  6. "url": "https://getcoherent.design"
  7. },
  8. "plugins": [
  9. {
  10. "name": "coherent",
  11. "source": "./plugins/coherent",
  12. "description": "Your agent changes the UI; Coherent proves nothing else moved. Real-browser checks, pixel diff, rollback. Next.js + Tailwind 4.",
  13. "category": "development"
  14. }
  15. ]
  16. }
README.md · README · 482 lines
  1. <h1 align="center">
  2. <strong>Coherent Design Method</strong>
  3. </h1>
  4. <p align="center">
  5. The model designs. Coherent governs.<br>
  6. An open-source platform that governs AI-built frontends: your coding agent designs and builds the UI;<br>
  7. Coherent scopes every edit, verifies it in a real browser and rolls back what fails.
  8. </p>
  9. <p align="center">
  10. <a href="https://www.npmjs.com/package/@getcoherent/cli"><img src="https://img.shields.io/npm/v/@getcoherent/cli.svg" alt="npm version"></a>
  11. <a href="https://github.com/skovtun/coherent-design-method/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  12. <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+">
  13. <img src="https://img.shields.io/badge/next.js-app%20router-black" alt="Next.js App Router">
  14. </p>
  15. ---
  16. ## What is Coherent?
  17. Frontier coding agents already write good UI. What they don't do is prove an edit stayed inside its lane: that "make the KPI cards on Earnings more prominent" changed Earnings and left the two other pages using the same card pixel-identical, that the build still passes, that no hydration error appeared, that your `git config` name didn't end up in a mock profile.
  18. Coherent is that layer. Since v0.27.0 it no longer generates design itself ([ADR-0011](docs/wiki/ADR/0011-governance-not-authorship.md): in a head-to-head on the same spec, plain Claude Code beat Coherent's own generation pipeline on every screen). Instead, every edit the agent makes goes through a governed session:
  19. 1. **Inventory.** A graph of your app built from the code itself (TypeScript AST): pages, layouts, shared components, who imports what. Nothing stored that can drift.
  20. 2. **Begin edit.** The agent declares a scope (`tokens`, `component`, `variant`, `page`, `new-component`) and the files it will write. Coherent answers with the impact: which routes must change, which must not.
  21. 3. **Verify.** Type errors (against a baseline, so pre-existing ones don't block you), a production build, before/after screenshots on desktop and mobile, an exact pixel diff on control routes, new browser and hydration errors, identity leaks.
  22. 4. **Verdict.** `verified`, `partially_verified`, `verified_without_visual`, `blocked_by_preexisting_failure` or `failed`. A failed edit is never committed: in agent mode it stays open until the agent fixes it or rolls it back; `coherent edit` rolls it back by default. Rollback touches only that edit's own files, so your concurrent hand edits survive.
  23. ## Quick Start
  24. **Prerequisites:** [Node.js](https://nodejs.org/) 20 or later, and [Claude Code](https://claude.com/claude-code) (CLI or desktop app) or Codex.
  25. ### New app
  26. ```bash
  27. npx @getcoherent/cli init my-app
  28. ```
  29. In an empty folder this runs the official `create-next-app` and `shadcn init`, adds a welcome page, and installs the Coherent agent. Open `my-app` in Claude Code and describe what you want; the Coherent agent is the project's default agent, so there is nothing to select.
  30. ### Existing Next.js app
  31. ```bash
  32. cd my-next-app
  33. npx @getcoherent/cli init
  34. ```
  35. Adds only the agent; your code is not touched. Run it again later to update the agent files.
  36. ### As a plugin (Claude Code, Codex)
  37. ```
  38. /plugin marketplace add skovtun/coherent-design-method
  39. /plugin install coherent@coherent
  40. ```
  41. Adds the `coherent` skill: your agent sets Coherent up in a Next.js app when you ask, and follows the governed edit loop.
  42. ### What init writes
  43. | File | Purpose |
  44. |------|---------|
  45. | `.claude/agents/coherent.md` | The Coherent agent (prompt + the `coherent` MCP server) |
  46. | `.mcp.json` | `coherent mcp --profile agent`: four governance tools |
  47. | `.claude/settings.json` | Makes `coherent` the default agent and adds the write guard hook (merged with your settings) |
  48. | `AGENTS.md` | A managed section for agents without hooks (Codex) |
  49. | `.gitignore` | Local state under `.coherent/` |
  50. | `package.json` | `@getcoherent/cli` and `playwright` as dev dependencies, installed with your project's package manager |
  51. Dynamic routes (`/orders/[id]`) need an example URL to be screenshotted; init lists them and tells you where to add one (`.coherent/preview-params.json`).
  52. ## How It Works
  53. ```
  54. agent ──► coherent_inventory code graph, open edit, files changed outside Coherent
  55. ──► coherent_begin_edit scope + write set → impact, baseline renders, transaction
  56. ──► (agent writes files) PreToolUse hook denies writes outside the write set
  57. ──► coherent_verify_edit fast: write set, new type errors, identity leaks
  58. final: + production build, renders, pixel diff → verdict
  59. ──► coherent_rollback_edit restore only this edit's files
  60. ```
  61. The hook is fast feedback, not the boundary: Bash, subagents and IDE writes bypass it. The boundary is verification, which diffs the whole tree after the edit. Agents without hooks are covered by `changedOutsideCoherent` in the inventory.
  62. The verification browser runs in a far time zone and another locale (`Pacific/Kiritimati`, `de-DE`) so server/client mismatches show up as errors instead of passing silently on your machine.
  63. ### Without an agent
  64. The same governed session is available from the CLI, with Coherent's own model routing the request:
  65. ```bash
  66. coherent edit "make the primary color emerald" # plan → impact → apply → verify
  67. coherent edit "tighten the pricing cards" --dry-run # scope and affected routes only
  68. coherent edit --undo # byte-exact rollback of the last edit
  69. ```
  70. ## Classic generator (deprecated)
  71. Everything below describes the old generation pipeline (`coherent chat`, `/coherent-generate`, the Design System viewer). It still works in projects created with `coherent init --classic`, but it is no longer developed and will be removed in a future release. See [MIGRATION-v0.27](docs/MIGRATION-v0.27.md).
  72. ## CLI Commands
  73. | Command | Description |
  74. |---------|-------------|
  75. | `coherent init [dir]` | Agent mode setup: new Next.js app in an empty folder, agent only in an existing app |
  76. | `coherent edit "<request>"` | Governed edit from the CLI: scope, impact, apply, verify, undo |
  77. | `coherent mcp --profile agent` | MCP server with the four governance tools |
  78. | `coherent init --classic` | Deprecated: old generator project with design system viewer |
  79. | `coherent chat "<message>"` | Generate or modify pages using natural language |
  80. | `coherent preview` | Start the dev server with auto-fix and file watching |
  81. | `coherent check` | Show all problems: page quality, component integrity, broken links |
  82. | `coherent fix` | Auto-fix everything: cache, dependencies, components, syntax, quality |
  83. | `coherent fix --journal` | Capture fix session to `.coherent/fix-sessions/` for later review |
  84. | `coherent journal list` / `aggregate` / `prune` | Review captured fix sessions, rank recurring issues, prune old entries |
  85. | `coherent sync` | Sync Design System with code after manual edits in your editor |
  86. | `coherent export` | Export a clean, deployable Next.js project (strips DS overlay) |
  87. | `coherent undo` | Restore project to state before the last `coherent chat` |
  88. | `coherent rules` | Regenerate `.cursorrules` and `CLAUDE.md` (AI editor context) |
  89. | `coherent update` | Apply platform updates to an existing project |
  90. | `coherent status` | Show current project status |
  91. | `coherent components list` | List all shared and UI components |
  92. | `coherent chat -i` | Interactive chat mode (REPL) |
  93. ### Examples
  94. ```bash
  95. # Generate a complete multi-page app
  96. coherent chat "create an e-commerce site with product catalog, cart, checkout, and account pages"
  97. # Modify design tokens
  98. coherent chat "change primary color to #6366f1 and use Inter font"
  99. # Target a specific component
  100. coherent chat --component "Header" "add a search button"
  101. # Target a specific page — surgical edit (single LLM call, minimal diff)
  102. coherent chat --page "pricing" "add a fourth enterprise tier"
  103. # Target a design token
  104. coherent chat --token "primary" "change to indigo"
  105. # Interactive mode
  106. coherent chat -i
  107. # After editing code manually in Cursor/VS Code
  108. coherent sync
  109. # Export for deployment
  110. coherent export
  111. ```
  112. ## Two Workflows
  113. Coherent supports two ways of working. Use whichever fits your task — or combine them.
  114. ### CLI (fast scaffolding)
  115. Run commands in your terminal. Each command goes through the full pipeline: AI generation, component reuse, validation, and auto-fix.
  116. ```bash
  117. coherent chat "add a dashboard with revenue stats and user growth chart"
  118. coherent chat "add a settings page with profile form and notification preferences"
  119. coherent preview
  120. ```
  121. **Best for:** creating pages, changing tokens, batch operations, quick prototyping.
  122. ### Editor (fine-grained control)
  123. Edit code directly in Cursor, VS Code, or any editor. Coherent provides AI context via `.cursorrules` and `CLAUDE.md` — your editor's AI knows about your shared components, design tokens, and quality rules.
  124. After manual edits, run `coherent sync` to update the Design System:
  125. ```bash
  126. # Edit files in your editor...
  127. coherent sync # updates Design System to match your code
  128. coherent check # verify everything is consistent
  129. ```
  130. **Best for:** custom components, complex logic, pixel-perfect styling, detailed work.
  131. ### Recommended workflow
  132. ```bash
  133. # 1. Scaffold with CLI
  134. coherent chat "add e-commerce: products, cart, checkout"
  135. # 2. Fix any generation issues
  136. coherent fix
  137. # 3. Preview
  138. coherent preview
  139. # 4. Polish in your editor
  140. # - Customize ProductCard component
  141. # - Add business logic
  142. # - Fine-tune responsive styles
  143. # 5. Sync and commit
  144. coherent sync
  145. git commit -m "Product catalog complete"
  146. # 6. Continue building
  147. coherent chat "add admin panel with order management"
  148. ```
  149. ## What Coherent Creates
  150. When you run `coherent init` followed by `coherent chat`, your project gets this structure:
  151. ```
  152. my-app/
  153. ├── app/
  154. │ ├── layout.tsx # Root layout with shared header/footer
  155. │ ├── page.tsx # Home page
  156. │ ├── about/page.tsx # Generated pages...
  157. │ ├── pricing/page.tsx
  158. │ ├── AppNav.tsx # Platform navigation + Design System button
  159. │ ├── ShowWhenNotAuthRoute.tsx # Route-based component visibility
  160. │ └── design-system/ # Design System viewer (auto-generated)
  161. │ ├── page.tsx # Overview
  162. │ ├── components/page.tsx # Component library
  163. │ ├── shared/page.tsx # Shared components (CID-xxx)
  164. │ ├── tokens/page.tsx # Design tokens
  165. │ ├── sitemap/page.tsx # Page architecture
  166. │ └── docs/ # Documentation & recommendations
  167. ├── components/
  168. │ ├── ui/ # shadcn/ui components (Button, Card, Input...)
  169. │ └── *.tsx # Custom components (auto-detected by sync)
  170. ├── design-system.config.ts # Single source of truth for the design system
  171. ├── coherent.components.json # Shared component manifest (CID registry)
  172. ├── .cursorrules # AI context for Cursor
  173. ├── CLAUDE.md # AI context for Claude Code
  174. └── globals.css # Tailwind CSS with design tokens
  175. ```
  176. ### Key files
  177. **`design-system.config.ts`** — The single source of truth. Contains all pages, components, design tokens (colors, typography, spacing), and page metadata. Every Coherent command reads from and writes to this file.
  178. **`coherent.components.json`** — The shared component registry. Each component gets a unique ID (CID-001, CID-002...) and tracks where it's used. This enables component reuse across pages and powers the Design System viewer.
  179. **`.cursorrules` / `CLAUDE.md`** — AI context files that tell your editor's AI about your design system. Automatically regenerated when you run `coherent sync` or `coherent rules`.
  180. ## AI Provider Setup
  181. Coherent uses Claude (by Anthropic) for code generation. `coherent init` auto-detects which path fits your environment — you don't normally pick. The two paths are:
  182. | Mode | Auto-picked when | API key required? | Command |
  183. |------|------------------|-------------------|---------|
  184. | **Claude Code skill** | `.claude/` is reachable (Claude Code installed), no API key present. | ❌ No | `/coherent-generate` (in Claude Code) |
  185. | **Standalone CLI** | An API key is set in the environment, or Claude Code isn't detected. | ✅ Yes | `coherent chat "..."` |
  186. If both signals are present, init configures both paths and surfaces both commands in its "Get Started" output. Override with `coherent init --skill-mode` / `--api-mode` / `--both` only if you want to force one.
  187. In skill mode, your Claude Code session does the generation using your subscription. Coherent contributes the constraint bundle and the quality validator — no tokens spent on our side, no API key needed, fully within Anthropic's Terms of Service.
  188. ### Claude Code skill path (no API key)
  189. 1. Run `coherent init`. With Claude Code detected, it auto-writes `.claude/skills/coherent-generate/SKILL.md` plus supporting `.claude/commands/` entries and skips the API-key prompt.
  190. 2. Open the project in Claude Code.
  191. 3. Run `/coherent-generate "build a CRM dashboard"` — your session orchestrates the phase rail (plan → anchor → extract-style → components → page × N → log-run) while Coherent's deterministic validator (`coherent check` + `coherent fix`) enforces the constraints on each ingest.
  192. Already have a project on an older Coherent version? Run `coherent update` to refresh the `.claude/` skills and commands.
  193. ### Standalone CLI path (API key)
  194. 1. Go to [console.anthropic.com](https://console.anthropic.com), create a key.
  195. 2. During `coherent init`, enter the key when prompted — it's saved to `.env` in your project (already in `.gitignore`). Force this path with `coherent init --api-mode` if Claude Code is also present. Or set manually:
  196. ```bash
  197. echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
  198. # or
  199. export ANTHROPIC_API_KEY=sk-ant-...
  200. ```
  201. 3. Model override (optional): `export CLAUDE_MODEL=claude-sonnet-4-20250514`.
  202. ### Security
  203. - Your API key (if any) is stored locally in `.env`, never committed to git.
  204. - Coherent has no servers — all AI calls go directly from your machine to Anthropic.
  205. - Skill mode sends nothing to Anthropic on Coherent's behalf — your Claude Code session does, as usual.
  206. ### Why can't Coherent CLI just use my Claude Code subscription?
  207. Anthropic's Terms of Service explicitly prohibit external tools from using OAuth tokens issued to Claude Free / Pro / Max accounts. Coherent CLI piggybacking on your subscription would violate that and could risk your account. The skill mode (Mode B) is the legally sanctioned path: your own Claude Code session does the work, Coherent provides constraints and validation. See [Anthropic authentication docs](https://code.claude.com/docs/en/authentication) and [discussion in claude-code#6536](https://github.com/anthropics/claude-code/issues/6536).
  208. If you accidentally expose an API key, revoke it immediately at [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) and create a new one.
  209. ## Design System Viewer
  210. Every Coherent project includes a live Design System viewer at `/design-system`. It shows:
  211. - **Overview** — Project summary, page count, component count
  212. - **Components** — All UI components with variants, sizes, and code examples
  213. - **Shared Components** — Reusable layout/section components with CID tracking
  214. - **Tokens** — Color palette, typography scale, spacing, border radius
  215. - **Sitemap** — Visual map of all pages and their connections
  216. - **Documentation** — Auto-generated docs and UX recommendations
  217. The viewer updates automatically when you add pages or run `coherent sync`.
  218. ## Quality System
  219. Coherent validates generated code against 38+ validators covering typography, spacing, accessibility, color usage, touch targets, interaction states, and CVA-inheritance traps (Button-as-container patterns).
  220. ### `coherent check` (read-only diagnostics)
  221. ```bash
  222. coherent check
  223. ```
  224. Reports:
  225. - Raw Tailwind colors (should use semantic tokens like `bg-primary`)
  226. - Missing accessibility labels
  227. - Heading hierarchy issues
  228. - Native HTML elements (should use design system components)
  229. - Broken internal links
  230. - Orphaned or unused shared components
  231. ### `coherent fix` (auto-repair)
  232. ```bash
  233. coherent fix
  234. ```
  235. A unified self-healing command that fixes most issues in one run:
  236. - **TypeScript errors** — two-pass auto-fix: deterministic fixers handle field name mismatches, union type casing, and missing event handlers; AI fallback fixes remaining errors when an API key is configured
  237. - **Missing components** — auto-installs shadcn/ui components referenced in code
  238. - **Raw colors** → semantic tokens (`bg-blue-500` → `bg-primary`)
  239. - **CSS variables** — syncs `globals.css` with design tokens
  240. - **Route group layouts** — verifies public/app/auth layout structure
  241. - **Build cache** — clears stale `.next` artifacts
  242. - **Component manifest** — removes stale entries, adds missing ones
  243. Run `coherent fix` after `coherent chat` to catch and repair any generation issues. Most TypeScript and quality problems are fixed automatically — no manual intervention needed.
  244. ### `coherent sync` (reverse sync)
  245. After editing code manually in your editor, run `coherent sync` to update the Design System:
  246. ```bash
  247. coherent sync # full sync
  248. coherent sync --tokens # only CSS variables
  249. coherent sync --components # only component detection
  250. coherent sync --patterns # only style patterns
  251. coherent sync --dry-run # preview changes without writing
  252. ```
  253. This extracts CSS variables, detects new custom components, captures style patterns, updates page metadata, and regenerates the Design System viewer.
  254. ## Development from Source
  255. ### Prerequisites
  256. - Node.js 20+
  257. - pnpm 8+
  258. ### Setup
  259. ```bash
  260. git clone https://github.com/skovtun/coherent-design-method.git
  261. cd coherent-design-method
  262. # Install all dependencies
  263. pnpm install
  264. # Build packages (core first, then CLI)
  265. pnpm build
  266. # Link CLI globally so you can use `coherent` command
  267. cd packages/cli
  268. pnpm link --global
  269. # Verify installation
  270. coherent --version
  271. ```
  272. ### Project structure
  273. ```
  274. coherent-design-method/
  275. ├── packages/
  276. │ ├── core/ # @getcoherent/core — design system engine, generators, managers
  277. │ ├── cli/ # @getcoherent/cli — CLI commands, AI providers, quality tools
  278. │ └── templates/ # Project templates
  279. ├── docs/ # Documentation
  280. └── package.json # Monorepo root (pnpm workspaces)
  281. ```
  282. ### Development workflow
  283. ```bash
  284. # Watch mode for core package
  285. cd packages/core && pnpm dev
  286. # Watch mode for CLI package (in another terminal)
  287. cd packages/cli && pnpm dev
  288. # After changes, rebuild
  289. pnpm build # from monorepo root
  290. ```
  291. ## Troubleshooting
  292. ### "Not a Coherent project"
  293. You're running a command outside a Coherent project directory. Make sure you're in a directory with `design-system.config.ts`:
  294. ```bash
  295. cd my-app # your project directory
  296. coherent preview # now it works
  297. ```
  298. ### "No API key found"
  299. `coherent chat` is the API-key path. If you want key-less generation, use the **skill mode** instead: open the project in Claude Code and run `/coherent-generate "<request>"` — same pipeline, driven by your Claude Code subscription. See [AI Provider Setup](#ai-provider-setup).
  300. ### Build errors after generation
  301. Run the auto-fixer:
  302. ```bash
  303. coherent fix
  304. ```
  305. This resolves most issues — TypeScript type errors, missing imports, component conflicts, and CSS problems. `coherent fix` uses deterministic fixers for common patterns and AI fallback for the rest. If issues persist, check the [full troubleshooting guide](./TROUBLESHOOTING.md).
  306. ### Pages look inconsistent
  307. If pages were generated one-by-one (not in a batch), they may not share styles. Fix this:
  308. ```bash
  309. coherent sync # extracts style patterns from existing pages
  310. ```
  311. Then generate new pages — they'll match the extracted patterns.
  312. ### "Module not found" for components
  313. Coherent auto-installs missing shadcn components. If one is missing:
  314. ```bash
  315. coherent fix # auto-installs missing components
  316. ```
  317. For the full list of known issues and solutions, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
  318. ## FAQ
  319. Common user-facing questions with answers in [docs/FAQ.md](./docs/FAQ.md):
  320. - Why does Coherent CLI need an API key even though I have Claude Code?
  321. - How is Coherent different from v0 / bolt / lovable / tasteui?
  322. - Where does Coherent store design decisions about my project?
  323. - Can I use Coherent without Next.js?
  324. ## Contributing
  325. We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
  326. - Development setup instructions
  327. - How to make changes to core vs CLI
  328. - Testing your changes locally
  329. - Commit message conventions
  330. - Pull request process
  331. ## License
  332. [MIT](./LICENSE) — Sergei Kovtun
  333. ---
  334. <p align="center">
  335. <a href="https://www.linkedin.com/in/sergeikovtun/">LinkedIn</a> ·
  336. <a href="https://github.com/skovtun/coherent-design-method">GitHub</a> ·
  337. <a href="https://getcoherent.design">Website</a>
  338. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.