claude

What it does

Provider. claude runs the local Claude Code CLI, claude -p --output-format json, on the user's Claude plan. The marginal price of one answer is $0, so costUsd is always 0. The CLI's own list-price figure is kept in meta.listCostUsd for reference. It registers one handler with registry in onInit: ("prompt-gen", "claude"). No events, no state.

Each call owns one temp dir, moku-claude-*, under workDir:

1. params.images are copied in as image-1.png, image-2.jpg and so on. Store paths have no extension, and the Read tool needs one.
2. claude -p runs with the dir as cwd. The dir is outside the repo, so no project CLAUDE.md is loaded.
3. The prompt goes to stdin, then stdin is closed. stdout is the JSON result.
4. The dir is removed in finally, on success and on every failure.

Its own public API is one method, app.claude.info().

Setup

No API key. The CLI is found on PATH, read through ctx.env, and must be logged in.

info().configured is true when bin exists: a path-like bin is checked directly, a bare name is searched on PATH.

Tasks it serves

prompt-gen

Single turn only. The command:

claude -p --output-format json --no-session-persistence
  --setting-sources user --strict-mcp-config --disable-slash-commands
  --system-prompt <request.system or the default>
  --restricted --tools Read --allowedTools Read --permission-prompts none    (with images)
  --tools ""                                                    (without images)
  [--model <mapped>] [--effort <low|medium|high>] [--json-schema <schema>]

The default system prompt is Answer the request directly. Output only the answer. It replaces Claude Code's coding-agent prompt. --bare is never used: it disables OAuth, so plan billing breaks.

A bad images, responseSchema or reasoning throws a plain Error before anything is spawned, from estimate() too. --json-schema carries the schema as compact JSON without a top-level $schema: the CLI rejects that key.

Model mapping:

meta.modelRequested keeps the original id whenever the request names a model.

The result: toolCalls is always [], finishReason always "stop". usage.promptTokens is input_tokens + cache_read_input_tokens + cache_creation_input_tokens, completionTokens is output_tokens, cachedTokens the cache reads and cacheWriteTokens the cache writes. A count the CLI does not report is 0. cacheSystem and cacheTtl are ignored. meta is Claude.ClaudePromptMeta: { provider: "claude", model?, modelRequested?, effort?, listCostUsd, usage: { inputTokens, outputTokens }, ignored? }.

  - id: score
    task: prompt-gen
    provider: claude
    input:
      prompt: "Score this frame from 1 to 10."
      model: anthropic/claude-opus-5.5
    params:
      reasoning: low
      responseSchema: { type: object, properties: { score: { type: number } }, required: [score] }

Models and prices

No price table. Every answer is plan-billed: estimate() returns { usd: 0 } and every result has costUsd: 0. The CLI's total_cost_usd is kept in meta.listCostUsd and never counted.

Make claude the default prompt-gen provider and cap how many local processes run at once:

import { createApp } from "@moku-labs/ai";

const app = createApp({
  pluginConfigs: {
    claude: { textModel: "claude-sonnet-5-5" },
    promptGen: { defaultProvider: "claude", fallback: ["codex"] },
    limits: { lanes: { "prompt-gen/claude": { concurrency: 2 } } }
  }
});

console.log(app.claude.info().configured);

Config

pluginConfigs.claude.

API

Mounted at app.claude.

import { app } from "./app";

const { configured } = app.claude.info();
if (!configured) throw new Error("Install the Claude Code CLI first.");

Types ship under the Claude namespace: Claude.Config, Claude.ClaudeInfo, Claude.ClaudePromptMeta, Claude.Reasoning, Claude.Effort.

Errors

stdout JSON is parsed first, even on a non-zero exit: the not-logged-in result exits 1 with valid JSON. The login and limit patterns also apply to stderr when stdout is not JSON.

Terminal and unavailable errors carry neither kind nor status, so the runner classifies them as unknown, which is terminal: the item is failed and never re-run.

The classes are values under ClaudeErrors:

import { ClaudeErrors, isPromptGenUnavailable } from "@moku-labs/ai";
import { app } from "./app";

try {
  await app.promptGen.generate({ prompt: "Say ok." }, { provider: "claude" });
} catch (error) {
  if (isPromptGenUnavailable(error)) {
    console.warn("claude cannot serve now; promptGen would fall back");
  } else if (error instanceof ClaudeErrors.RetryableProviderError) {
    console.warn("timed out", error.kind);
  } else if (error instanceof ClaudeErrors.TerminalProviderError) {
    console.error("failed", error.message);
  } else {
    throw error;
  }
}

Events

Emits

None.

Listens to

None. Diagnostics go through ctx.log: claude:prompt-gen:done with { model, chars }, where chars is the answer length. The prompt and the answer are never logged.

Depends on

• registry: the register call.

Related

• prompt-gen: the task, defaultProvider and fallback.
• anthropic: the same models through the API, with tools and a prompt cache.
• codex: the same shape over the Codex CLI.