Skip to content
helixui

Claude Code

Claude Code is Anthropic’s CLI agent. helixui ships an MCP server it can speak to natively.

One-line setup

From a checkout of helixui (or a project with helixui installed):

Terminal window
claude mcp add helixui node ./node_modules/@helixui/mcp/bin/server.mjs

Restart Claude Code and the helixui.* tools are available. Ask it something like:

Use helixui.search to find the right component for “selectable list of options with chips” — then write the JSX.

Project-level CLAUDE.md

Drop this into your repo root so every Claude Code session in this project starts with the right context:

# CLAUDE.md — conventions for this project


This project uses **helixui** as its design system. helixui is AI-native;
you should treat it as a first-class source of truth.


## Components & tokens


- Import components from `@helixui/core`. Never inline-style what a
  helixui component already provides.
- Token names live in `tokens-manifest.json`. If you need a token, use
  the helixui MCP server's `helixui.search` to find it; do not invent
  values.
- Each component's contract lives next to its source as `spec.md`.


## How to look things up


Before writing UI, use the MCP server:


- `helixui.search` — BM25 lookup across every component spec.
- `helixui.validate` — confirm a generated JSX snippet is legal.
- `helixui.list_presets` — list DNA presets.
- `helixui.express_dna` — expand a DNA shorthand into a DESIGN.md.


## What to avoid


- Don't write CSS-in-JS. Use CSS variables.
- Don't pass `style={{ color: '#...' }}`. Use tokens.
- Don't add a new dependency without justification in the PR.


## When unsure


- Read `DESIGN.md` at the repo root.
- Read `/llms-full.txt` for the full system snapshot.

Example prompts that work

These all should succeed on the first try:

Build me a settings page with:
- email notifications toggle
- two-factor auth section with a "Configure" button
- a danger zone with a "Delete account" red button


Use helixui components and the helixui DNA theme.
Take this DNA shorthand: { basePreset: 'noir', mutations: [{ gene:
'accent', value: 'violet' }] }, expand it via helixui.express_dna,
and apply it as DESIGN.md to a new module.
The user just dropped a screenshot at ./logo.png. Use
helixui.derive_dna_from_image with adapter:'anthropic' to pick the
closest helixui DNA, then preview the result.

Troubleshooting

“Tool helixui.search not found.” → Restart Claude Code. The MCP servers list is read at startup.

The server starts but tools are empty. → Run pnpm build:all once. The MCP server reads from apps/site/dist/*.json; without a build the manifest is empty.

The vision adapter throws. → OPENAI_API_KEY / ANTHROPIC_API_KEY must be in the MCP launch env, not your shell env. Add them to the env block in your Claude Code config.

Where the server lives

In a checkout: packages/mcp/bin/server.mjs. After pnpm add @helixui/mcp: node_modules/@helixui/mcp/bin/server.mjs.

See the package README for the full tool list and protocol details.