
coherent
io.github.skovtun/coherent
Governs UI edits by coding agents in Next.js: scope, real-browser verification, rollback.
Documentation
Coherent Design Method
The model designs. Coherent governs.
An open-source platform that governs AI-built frontends: your coding agent designs and builds the UI;
Coherent scopes every edit, verifies it in a real browser and rolls back what fails.
What is Coherent?
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.
Coherent is that layer. Since v0.27.0 it no longer generates design itself (ADR-0011: 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:
- 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.
- 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. - 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.
- Verdict.
verified,partially_verified,verified_without_visual,blocked_by_preexisting_failureorfailed. A failed edit is never committed: in agent mode it stays open until the agent fixes it or rolls it back;coherent editrolls it back by default. Rollback touches only that edit's own files, so your concurrent hand edits survive.
Quick Start
Prerequisites: Node.js 20 or later, and 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).
How It Works
agent ──► coherent_inventory code graph, open edit, files changed outside Coherent
──► coherent_begin_edit scope + write set → impact, baseline renders, transaction
──► (agent writes files) PreToolUse hook denies writes outside the write set
──► coherent_verify_edit fast: write set, new type errors, identity leaks
final: + production build, renders, pixel diff → verdict
──► coherent_rollback_edit restore only this edit's files
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.
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.
Without an agent
The same governed session is available from the CLI, with Coherent's own model routing the request:
coherent edit "make the primary color emerald" # plan → impact → apply → verify
coherent edit "tighten the pricing cards" --dry-run # scope and affected routes only
coherent edit --undo # byte-exact rollback of the last edit
Classic generator (deprecated)
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.
CLI Commands
| Command | Description |
|---|---|
coherent init [dir] | Agent mode setup: new Next.js app in an empty folder, agent only in an existing app |
coherent edit "<request>" | Governed edit from the CLI: scope, impact, apply, verify, undo |
coherent mcp --profile agent | MCP server with the four governance tools |
coherent init --classic | Deprecated: old generator project with design system viewer |
coherent chat "<message>" | Generate or modify pages using natural language |
coherent preview | Start the dev server with auto-fix and file watching |
coherent check | Show all problems: page quality, component integrity, broken links |
coherent fix | Auto-fix everything: cache, dependencies, components, syntax, quality |
coherent fix --journal | Capture fix session to .coherent/fix-sessions/ for later review |
coherent journal list / aggregate / prune | Review captured fix sessions, rank recurring issues, prune old entries |
coherent sync | Sync Design System with code after manual edits in your editor |
coherent export | Export a clean, deployable Next.js project (strips DS overlay) |
coherent undo | Restore project to state before the last coherent chat |
coherent rules | Regenerate .cursorrules and CLAUDE.md (AI editor context) |
coherent update | Apply platform updates to an existing project |
coherent status | Show current project status |
coherent components list | List all shared and UI components |
coherent chat -i | Interactive chat mode (REPL) |
Examples
# Generate a complete multi-page app
coherent chat "create an e-commerce site with product catalog, cart, checkout, and account pages"
# Modify design tokens
coherent chat "change primary color to #6366f1 and use Inter font"
# Target a specific component
coherent chat --component "Header" "add a search button"
# Target a specific page — surgical edit (single LLM call, minimal diff)
coherent chat --page "pricing" "add a fourth enterprise tier"
# Target a design token
coherent chat --token "primary" "change to indigo"
# Interactive mode
coherent chat -i
# After editing code manually in Cursor/VS Code
coherent sync
# Export for deployment
coherent export
Two Workflows
Coherent supports two ways of working. Use whichever fits your task — or combine them.
CLI (fast scaffolding)
Run commands in your terminal. Each command goes through the full pipeline: AI generation, component reuse, validation, and auto-fix.
coherent chat "add a dashboard with revenue stats and user growth chart"
coherent chat "add a settings page with profile form and notification preferences"
coherent preview
Best for: creating pages, changing tokens, batch operations, quick prototyping.
Editor (fine-grained control)
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.
After manual edits, run coherent sync to update the Design System:
# Edit files in your editor...
coherent sync # updates Design System to match your code
coherent check # verify everything is consistent
Best for: custom components, complex logic, pixel-perfect styling, detailed work.
Recommended workflow
# 1. Scaffold with CLI
coherent chat "add e-commerce: products, cart, checkout"
# 2. Fix any generation issues
coherent fix
# 3. Preview
coherent preview
# 4. Polish in your editor
# - Customize ProductCard component
# - Add business logic
# - Fine-tune responsive styles
# 5. Sync and commit
coherent sync
git commit -m "Product catalog complete"
# 6. Continue building
coherent chat "add admin panel with order management"
What Coherent Creates
When you run coherent init followed by coherent chat, your project gets this structure:
my-app/
├── app/
│ ├── layout.tsx # Root layout with shared header/footer
│ ├── page.tsx # Home page
│ ├── about/page.tsx # Generated pages...
│ ├── pricing/page.tsx
│ ├── AppNav.tsx # Platform navigation + Design System button
│ ├── ShowWhenNotAuthRoute.tsx # Route-based component visibility
│ └── design-system/ # Design System viewer (auto-generated)
│ ├── page.tsx # Overview
│ ├── components/page.tsx # Component library
│ ├── shared/page.tsx # Shared components (CID-xxx)
│ ├── tokens/page.tsx # Design tokens
│ ├── sitemap/page.tsx # Page architecture
│ └── docs/ # Documentation & recommendations
├── components/
│ ├── ui/ # shadcn/ui components (Button, Card, Input...)
│ └── *.tsx # Custom components (auto-detected by sync)
├── design-system.config.ts # Single source of truth for the design system
├── coherent.components.json # Shared component manifest (CID registry)
├── .cursorrules # AI context for Cursor
├── CLAUDE.md # AI context for Claude Code
└── globals.css # Tailwind CSS with design tokens
Key files
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.
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.
.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.
AI Provider Setup
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:
| Mode | Auto-picked when | API key required? | Command |
|---|---|---|---|
| Claude Code skill | .claude/ is reachable (Claude Code installed), no API key present. | ❌ No | /coherent-generate (in Claude Code) |
| Standalone CLI | An API key is set in the environment, or Claude Code isn't detected. | ✅ Yes | coherent chat "..." |
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.
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.
Claude Code skill path (no API key)
- Run
coherent init. With Claude Code detected, it auto-writes.claude/skills/coherent-generate/SKILL.mdplus supporting.claude/commands/entries and skips the API-key prompt. - Open the project in Claude Code.
- 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.
Already have a project on an older Coherent version? Run coherent update to refresh the .claude/ skills and commands.
Standalone CLI path (API key)
- Go to console.anthropic.com, create a key.
- During
coherent init, enter the key when prompted — it's saved to.envin your project (already in.gitignore). Force this path withcoherent init --api-modeif Claude Code is also present. Or set manually:
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
# or
export ANTHROPIC_API_KEY=sk-ant-...
- Model override (optional):
export CLAUDE_MODEL=claude-sonnet-4-20250514.
Security
- Your API key (if any) is stored locally in
.env, never committed to git. - Coherent has no servers — all AI calls go directly from your machine to Anthropic.
- Skill mode sends nothing to Anthropic on Coherent's behalf — your Claude Code session does, as usual.
Why can't Coherent CLI just use my Claude Code subscription?
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 and discussion in claude-code#6536.
If you accidentally expose an API key, revoke it immediately at console.anthropic.com/settings/keys and create a new one.
Design System Viewer
Every Coherent project includes a live Design System viewer at /design-system. It shows:
- Overview — Project summary, page count, component count
- Components — All UI components with variants, sizes, and code examples
- Shared Components — Reusable layout/section components with CID tracking
- Tokens — Color palette, typography scale, spacing, border radius
- Sitemap — Visual map of all pages and their connections
- Documentation — Auto-generated docs and UX recommendations
The viewer updates automatically when you add pages or run coherent sync.
Quality System
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).
coherent check (read-only diagnostics)
coherent check
Reports:
- Raw Tailwind colors (should use semantic tokens like
bg-primary) - Missing accessibility labels
- Heading hierarchy issues
- Native HTML elements (should use design system components)
- Broken internal links
- Orphaned or unused shared components
coherent fix (auto-repair)
coherent fix
A unified self-healing command that fixes most issues in one run:
- 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
- Missing components — auto-installs shadcn/ui components referenced in code
- Raw colors → semantic tokens (
bg-blue-500→bg-primary) - CSS variables — syncs
globals.csswith design tokens - Route group layouts — verifies public/app/auth layout structure
- Build cache — clears stale
.nextartifacts - Component manifest — removes stale entries, adds missing ones
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.
coherent sync (reverse sync)
After editing code manually in your editor, run coherent sync to update the Design System:
coherent sync # full sync
coherent sync --tokens # only CSS variables
coherent sync --components # only component detection
coherent sync --patterns # only style patterns
coherent sync --dry-run # preview changes without writing
This extracts CSS variables, detects new custom components, captures style patterns, updates page metadata, and regenerates the Design System viewer.
Development from Source
Prerequisites
- Node.js 20+
- pnpm 8+
Setup
git clone https://github.com/skovtun/coherent-design-method.git
cd coherent-design-method
# Install all dependencies
pnpm install
# Build packages (core first, then CLI)
pnpm build
# Link CLI globally so you can use `coherent` command
cd packages/cli
pnpm link --global
# Verify installation
coherent --version
Project structure
coherent-design-method/
├── packages/
│ ├── core/ # @getcoherent/core — design system engine, generators, managers
│ ├── cli/ # @getcoherent/cli — CLI commands, AI providers, quality tools
│ └── templates/ # Project templates
├── docs/ # Documentation
└── package.json # Monorepo root (pnpm workspaces)
Development workflow
# Watch mode for core package
cd packages/core && pnpm dev
# Watch mode for CLI package (in another terminal)
cd packages/cli && pnpm dev
# After changes, rebuild
pnpm build # from monorepo root
Troubleshooting
"Not a Coherent project"
You're running a command outside a Coherent project directory. Make sure you're in a directory with design-system.config.ts:
cd my-app # your project directory
coherent preview # now it works
"No API key found"
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.
Build errors after generation
Run the auto-fixer:
coherent fix
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.
Pages look inconsistent
If pages were generated one-by-one (not in a batch), they may not share styles. Fix this:
coherent sync # extracts style patterns from existing pages
Then generate new pages — they'll match the extracted patterns.
"Module not found" for components
Coherent auto-installs missing shadcn components. If one is missing:
coherent fix # auto-installs missing components
For the full list of known issues and solutions, see TROUBLESHOOTING.md.
FAQ
Common user-facing questions with answers in docs/FAQ.md:
- Why does Coherent CLI need an API key even though I have Claude Code?
- How is Coherent different from v0 / bolt / lovable / tasteui?
- Where does Coherent store design decisions about my project?
- Can I use Coherent without Next.js?
Contributing
We welcome contributions! See CONTRIBUTING.md for:
- Development setup instructions
- How to make changes to core vs CLI
- Testing your changes locally
- Commit message conventions
- Pull request process
License
MIT — Sergei Kovtun
@getcoherent/clinpm install @getcoherent/cli