# Get started with Candor UI

Install the free tier in two commands, connect your agent, and add Pro or Premium items with a licence key when you need them.

## 1. Install the free tier

In a React 19 app with Tailwind 4 (Next.js or Vite). `init` adds the `@candor` registry to `components.json`, installs the theme and imports it after Tailwind. In a project without shadcn yet it sets shadcn up first; `--yes` answers its questions (Radix, the nova preset) for CI or a coding agent.

Set up Candor:

```bash
npx candor-ui@latest init
```

Add the chat core:

```bash
npx candor-ui add thread message composer
```

See: [Thread](https://candor.themethodic.com/docs/thread.md), [Message](https://candor.themethodic.com/docs/message.md), [Composer](https://candor.themethodic.com/docs/composer.md)

## 2. Render it

Put this in a page (`app/page.tsx` in Next.js) to see a working chat with a canned reply. The imports are where `add` put the files: `@/components/…` and `@/lib/…`.

`app/page.tsx`:

```tsx
"use client"

import * as React from "react"
import { Composer } from "@/components/composer"
import { Message } from "@/components/message"
import { Thread } from "@/components/thread"
import type { Message as MessageData } from "@/lib/chat"

const agent = { id: "a1", name: "Support agent", role: "assistant" }

const line = (i: number): MessageData => ({
  id: `h${i}`,
  author: i % 2 ? { role: "agent", agent } : { role: "user" },
  status: "complete",
  blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text: i % 2 ? `Order ${1000 + i} shipped on Tuesday.` : `Where is order ${1001 + i}?` }] }],
})
const history = Array.from({ length: 600 }, (_, i) => line(i))

export default function Example() {
  const [value, setValue] = React.useState("")
  const [messages, setMessages] = React.useState<MessageData[]>([])
  const [long, setLong] = React.useState(false)
  const shown = long ? [...history, ...messages] : messages
  const send = (text: string) => {
    setMessages((m) => [
      ...m,
      { id: `u${m.length}`, author: { role: "user" }, status: "complete", blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text }] }] },
      { id: `a${m.length}`, author: { role: "agent", agent }, status: "complete", blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text: "Got it. I’ll look into that." }] }] },
    ])
    setValue("")
  }
  return (
    <div className="flex flex-col gap-2">
      <label className="flex items-center gap-1.5 text-xs text-muted-foreground">
        <input type="checkbox" checked={long} onChange={(e) => setLong(e.target.checked)} />
        A history of 600 messages, virtualised
      </label>
      <div className="h-80 overflow-hidden rounded-lg border">
        <Thread
          className="h-full"
          // virtualize renders only the messages in or near view; each child needs a key.
          virtualize={long}
          empty={<p className="text-sm text-muted-foreground">Ask about an order to start.</p>}
          footer={<Composer value={value} onChange={setValue} onSubmit={send} placeholder="Ask about an order" />}
        >
          {shown.length ? shown.map((m) => <Message key={m.id} message={m} />) : null}
        </Thread>
      </div>
    </div>
  )
}
```

## 3. Connect your agent

Candor's components take plain data, so they work with any backend. The adapters turn an SDK's messages into that data: the Vercel AI SDK (`useCandorChat`), the Claude Agent SDK (`useClaudeAgent`) and AG-UI (`useAgUi`). They're free.

Add an adapter:

```bash
npx candor-ui add ai-sdk
```

See: [AI SDK](https://candor.themethodic.com/docs/ai-sdk.md), [Claude Agent SDK](https://candor.themethodic.com/docs/claude-agent-sdk.md), [AG-UI](https://candor.themethodic.com/docs/ag-ui.md)

## 4. Or start from a working app

The starter is a Next.js app with an agent chat built from the free items, for the AI SDK and the Claude Agent SDK. It needs an Anthropic API key to run.

Copy the starter:

```bash
npx degit MethodicDev/candor/starter my-agent-app
```

See: [Free tier on GitHub](https://github.com/MethodicDev/candor)

## 5. Pro and Premium

After you buy, your licence key is in the receipt email and the Polar customer portal. Save it in the app (it goes in `.env.local`, which you keep out of git), then add any item. In CI and on your host, set `CANDOR_LICENSE_KEY` as a secret.

Save your licence key:

```bash
npx candor-ui key <your licence key>
```

Add a Pro item:

```bash
npx candor-ui add plan approval-request
```

See: [Pricing](https://candor.themethodic.com/#pricing), [Licence](https://candor.themethodic.com/licence)

## 6. Keep it up to date

`add` records each item in `candor-lock.json`: the version it came from and a hash of each file as it was installed. Commit it. `update` compares each file with that hash: one you haven't touched is replaced with the new version; one you changed gets a three-way merge, with conflict markers (`<<<<<<<`) only where your edit and the new version touch the same lines. `--dry-run` says what would change and writes nothing; `--to <version>` picks a version; items installed before the lockfile need `--from <the version you installed>`. If you moved a file, `update` finds it when it's still as installed, or you say where with `--moved <installed path>=<where it is now>`; the lockfile remembers, even for an item already at the latest version. An item with a file it can't find stays at its old version until the file is found.

See what an update would change:

```bash
npx candor-ui update --dry-run
```

Update installed items:

```bash
npx candor-ui update
```

Update a moved theme:

```bash
npx candor-ui update theme --moved styles/candor.css=web/styles/candor.css
```

See: [Changelog](https://candor.themethodic.com/changelog)

## 7. Check it in CI

`verify` checks `candor-lock.json` against the registry's versioned snapshots and the files in your repository, without running shadcn: every recorded item exists at its version, and every file is there. Files you've changed since install are listed, not failed. It exits 1 on anything missing or unknown. Paid items need `CANDOR_LICENSE_KEY` set as a CI secret.

Verify the lockfile:

```bash
npx candor-ui verify
```

## 8. With a coding agent

The docs MCP server lets Claude Code, Cursor, VS Code and other agents search these docs, read any page and pick components for a task while they work. It's free and read-only: no licence key, and it serves docs, never paid source. For other clients, add `https://candor.themethodic.com/mcp` as a remote (streamable HTTP) server; the setup guides have each tool's own config. The skill teaches which component fits which job and the rules the kit keeps. Every docs page is also Markdown at the same address plus `.md`, listed in llms.txt.

Add the docs MCP server to Claude Code:

```bash
claude mcp add --transport http candor https://candor.themethodic.com/mcp
```

Install the skill:

```bash
npx skills add MethodicDev/candor
```

See: [Setup guides, tool by tool](https://candor.themethodic.com/guides), [llms.txt](https://candor.themethodic.com/llms.txt), [This page as Markdown](https://candor.themethodic.com/get-started.md)

## 9. If something looks wrong

`doctor` checks the registry, your key, the theme import, React and Tailwind versions, and says how to fix each. Premium and Team include email support at info@themethodic.com.

Check the setup:

```bash
npx candor-ui doctor
```