# useClaudeAgent

Wires a Claude Agent SDK server route to Candor: messages for <Thread>/<Message>, props for <Composer>, and the tool calls waiting on a person. The same shape as useCandorChat, so screens work with either.

const { messages, composer, approvals, respond } = useClaudeAgent({ api: "/api/agent", approveApi: "/api/agent/approve", agent }) <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>

Each message continues the same agent session (the SDK's `resume`). Mentions are sent as structured `references`, not pasted into the text.

- Registry name: `use-claude-agent` (`@candor/use-claude-agent`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/use-claude-agent

## Install

```bash
npx candor-ui add use-claude-agent
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/use-claude-agent`.
It brings in: chat, claude-agent-sdk, composer.

## Functions

### useClaudeAgent

```ts
useClaudeAgent(options: UseClaudeAgentOptions)
```

Wires a Claude Agent SDK server route to Candor: messages for <Thread>/<Message>, props for <Composer>, and the tool calls waiting on a person. The same shape as useCandorChat, so screens work with either.

const { messages, composer, approvals, respond } = useClaudeAgent({ api: "/api/agent", approveApi: "/api/agent/approve", agent }) <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>

Each message continues the same agent session (the SDK's `resume`). Mentions are sent as structured `references`, not pasted into the text.

## Types

### UseClaudeAgentOptions

```ts
Omit<FromClaudeAgentOptions, "running"> & { /** Your route that runs the agent with streamClaudeAgent. It receives `{ prompt, promptId, references, sessionId, ...body }`. */ api: string /** * Your route that records an answer (answerClaudeApproval). It receives `{ id, approved, reason, updatedInput, * answers, alwaysAllow }` and returns `{ ok }`. Not needed with `onRespond`. */ approveApi?: string
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.