Skip to main content

​
useClaude Hook

Runs the same execution pipeline as <Claude>, but returns state for custom rendering. The source of truth is the Smithers DB (agents table), not React state. 
import { useClaude } from "smithers-orchestrator";

function ClaudePanel() {
  const { status, result, error, tailLog, agentId } = useClaude({
    model: "sonnet",
    children: "Review the diff and suggest fixes.",
  });

  return (
    <panel>
      <text>Status: {status}</text>
      {agentId && <text>Agent: {agentId}</text>}
      {error && <text>Error: {error.message}</text>}
      {result && <text>Output: {result.output}</text>}
      {tailLog.length > 0 && <text>Tail: {tailLog.at(-1)?.content}</text>}
    </panel>
  );
}

​
API

function useClaude(props: ClaudeProps): UseClaudeResult

interface UseClaudeResult {
  status: "pending" | "running" | "complete" | "error"
  agentId: string | null
  executionId: string | null
  model: string
  result: AgentResult | null
  error: Error | null
  tailLog: TailLogEntry[]
}

​
Props

PropTypeDefaultDescription
childrenReactNode—The prompt to send to Claude
model'opus' | 'sonnet' | 'haiku' | string'sonnet'Claude model to use
permissionMode'default' | 'acceptEdits' | 'plan' | 'dontAsk' | 'bypassPermissions''default'Permission mode for file operations
mcpConfigstring—Path to MCP configuration file
allowedToolsstring[]—Specific tools to allow (whitelist)
disallowedToolsstring[]—Specific tools to disallow (blacklist)
maxTurnsnumber—Maximum number of agentic loops
maxTokensnumber—Maximum tokens for output
timeoutnumber—Timeout in milliseconds
cwdstring—Working directory for the agent
systemPromptstring—System prompt for the agent
outputFormat'text' | 'json' | 'stream-json''text'Output format
continueConversationboolean—Continue from previous conversation
resumeSessionstring—Resume a specific session
schemaz.ZodType—Zod schema for structured output validation
schemaRetriesnumber2Maximum retries for schema validation failures
validate(result: AgentResult) => boolean | Promise<boolean>—Validate result before accepting
retryOnValidationFailureboolean—Retry if validation fails
maxRetriesnumber—Maximum retry attempts
retryDelayMsnumber250Base delay in milliseconds for retry backoff
stopConditionsStopCondition[]—Conditions that will stop the agent
middlewareSmithersMiddleware[]—Middleware applied to this execution
tailLogCountnumber10Number of tail log entries to display during execution
tailLogLinesnumber10Number of lines to show per tail log entry
useSubscriptionbooleantrueUse Claude subscription credits instead of API credits
reportingEnabledboolean—Enable database reporting for this agent
recordStreamEventsbooleantrue when reportingEnabledRecord stream events to the database
legacyLogFormatbooleanfalseWrite legacy raw text logs alongside NDJSON stream logs
onFinished(result: AgentResult) => void—Called when agent finishes successfully
onError(error: Error) => void—Called when agent encounters an error
onProgress(message: string) => void—Called for progress updates
onToolCall(tool: string, input: any) => void—Called when agent makes a tool call
onStreamPart(part: SmithersStreamPart) => void—Called for typed stream events (when enabled)

​
Notes

  • Requires SmithersProvider context.
  • Respects ExecutionScope and executionEnabled.
  • tailLog is in-memory; status/result come from the DB.

Claude Component

JSX wrapper around the same execution

Agents API

DB schema and methods