@kybernesis/brain-llm-claude

The default LLMProvider for Cortex — runs Claude through the local claude CLI as a subprocess. It powers the kernel's reasoning features: relationship and fact extraction, contradiction detection, user profiles, and sleep-cycle reasoning.

Used with @kybernesis/brain-core. It satisfies the LLMProvider interface; you inject it, the kernel calls callClaude / callClaudeJSON through it.

Install

pnpm add @kybernesis/brain-llm-claude @kybernesis/brain-core

Requires the claude CLI on PATH (authenticated). The kernel works without an LLM seam — the reasoning features simply skip — so this provider is optional.

Usage

import { createSubprocessProvider, isClaudeAvailable } from '@kybernesis/brain-llm-claude';
import { setLLMProvider } from '@kybernesis/brain-core';

if (await isClaudeAvailable()) {
  setLLMProvider(createSubprocessProvider());
}
// brain-core's LLM-backed steps now run; without it they no-op.

Behaviour

• Shells out to claude --print per call; resolves the model from CLAUDE_MODEL_ALIASES in @kybernesis/brain-contracts.
• Never throws into the kernel — spawn errors, non-zero exits, empty output, and timeouts all resolve to null (the kernel treats a null LLM result as "skip"). Surface failures via the onError hook (reason: 'spawn' | 'exit' | 'empty' | 'timeout').
• timeoutMs (default 60_000) sends SIGTERM to a hung process so a stuck claude can't wedge a sleep cycle.

setLLMProvider(createSubprocessProvider({
  timeoutMs: 30_000,
  onError: (reason, detail) => log.warn(`claude ${reason}`, detail),
}));

Notes

• ESM-only, TypeScript strict.
• maxTokens is not supported by the CLI surface and is documented as a no-op.
• Part of Cortex — @kybernesis/brain-*.