claude-agent-driver

A tiny, transport-agnostic kernel for driving the local Claude CLI on your subscription through the Claude Agent SDK's query() — no API key. You bring the transport (an HTTP server, a WebSocket, a CLI) and the turn-control (session pooling, single-shot); this owns the two pieces every integration ends up rewriting:

• buildOptions(fields) → assemble the query() Options: the Claude Code preset prompt with your system as an append (or a fully custom systemPrompt), mcpServers, allowedTools / disallowedTools, permissionMode, includePartialMessages.

• mapMessage(msg, state) → normalize the SDK's message stream into a flat event stream:

  event	from	fields
  session	system/init	sessionId
  text	streamed text_delta (or non-streaming fallback)	text
  tool_use	assistant	id, name, input
  tool_result	user	id, name, result, isError
  result	result	text, subtype, isError, sessionId, costUsd, numTurns, usage, durationMs, errors

That's it — pooling, resume, streaming-input queues, and abort/interrupt stay in your app, where they differ per transport.

Install

npm i @nevescloud/claude-agent-driver

Requires the claude CLI installed and logged in (claude runs on your subscription; the SDK reads the same credentials).

Use

Single-turn (string prompt, no pooling) — streamTurn:

import { streamTurn } from '@nevescloud/claude-agent-driver';

let answer = '';
for await (const ev of streamTurn({
  prompt: 'Summarize the repo README.',
  system: 'Be concise.',                 // appended to the Claude Code preset
  permissionMode: 'dontAsk',             // run pre-approved tools, deny the rest, never prompt
  mcpServers: { mytools: { type: 'http', url: 'http://127.0.0.1:8771/mcp' } },
  allowedTools: ['mcp__mytools'],
})) {
  if (ev.type === 'text') process.stdout.write(ev.text);   // live typing
  else if (ev.type === 'tool_result') console.log('\n[tool]', ev.name, ev.result);
  else if (ev.type === 'result') answer = ev.text;         // durable final text
}

Pooled / streaming-input — assemble options and map messages around your own long-lived query() loop:

import { query, buildOptions, mapMessage, newState, userMessage } from '@nevescloud/claude-agent-driver';

const q = query({ prompt: myStreamingInput, options: buildOptions({ system, permissionMode: 'bypassPermissions' }) });
const state = newState();
for await (const msg of q) {
  for (const ev of mapMessage(msg, state)) { /* ... */ }
}

resolveClaudeBin() resolves the operator's own claude for version parity (pass to pathToClaudeCodeExecutable).

API

export	what
streamTurn({ prompt, ...optionFields, queryFn? })	single-turn async generator of normalized events
buildOptions(fields)	build the query() Options object
mapMessage(msg, state)	generator: one SDK message → zero or more flat events
newState()	per-turn state for mapMessage
userMessage(text)	the streaming-input user message shape
resolveClaudeBin(envOverride?)	resolve the claude binary path
query	re-export of the Agent SDK's query

License

MIT