@scottwalker/claude-connector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,444 @@
+# claude-connector
+
+Programmatic Node.js interface for [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) CLI.
+
+Use Claude Code from your application code — no terminal required. Works with your existing Max/Team/Enterprise subscription.
+
+**[Website](https://scott-walker.github.io/claude-connector/)** | **[API Reference](./docs/API.md)** | **[Architecture](./docs/ARCHITECTURE.md)**
+
+---
+
+## Why
+
+Claude Code is a powerful AI coding agent, but it only runs in a terminal. **claude-connector** turns it into a programmable API — so you can embed it into CI pipelines, build custom tools, orchestrate multi-agent workflows, or integrate it with any Node.js application.
+
+**Key design decisions:**
+
+- **CLI wrapper, not API client** — uses your local `claude` binary and subscription, not the Anthropic HTTP API
+- **Zero runtime dependencies** — only Node.js built-ins (`child_process`, `events`)
+- **Executor abstraction** — swap CLI for SDK or HTTP backend without changing your code
+- **Full CLI parity** — exposes all 45+ Claude Code flags through typed options
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **Claude Code CLI** installed and authenticated (`claude auth login`)
+
+## Install
+
+```bash
+npm install claude-connector
+```
+
+## Quick Start
+
+```typescript
+import { Claude } from 'claude-connector'
+
+const claude = new Claude()
+
+// Simple query
+const result = await claude.query('Find and fix bugs in auth.ts')
+console.log(result.text)
+console.log(result.sessionId)   // resume later
+console.log(result.usage)       // { inputTokens, outputTokens }
+```
+
+## Features
+
+### Custom CLI Path
+
+Point to a specific Claude Code installation when multiple versions coexist:
+
+```typescript
+const claude = new Claude({
+  executable: '/opt/claude-code/v2/bin/claude',
+  cwd: '/path/to/project',
+})
+```
+
+### Streaming
+
+Real-time output as Claude works:
+
+```typescript
+for await (const event of claude.stream('Rewrite the auth module')) {
+  switch (event.type) {
+    case 'text':
+      process.stdout.write(event.text)
+      break
+    case 'tool_use':
+      console.log(`[Tool] ${event.toolName}`)
+      break
+    case 'result':
+      console.log(`\nDone in ${event.durationMs}ms`)
+      break
+    case 'error':
+      console.error(event.message)
+      break
+  }
+}
+```
+
+### Multi-turn Sessions
+
+Maintain conversation context across queries:
+
+```typescript
+const session = claude.session()
+await session.query('Analyze the architecture of this project')
+await session.query('Now refactor the auth module based on your analysis')
+// ^ Claude remembers the previous context
+
+// Resume a session later (even across process restarts)
+const s2 = claude.session({ resume: session.sessionId! })
+await s2.query('Continue where we left off')
+
+// Fork a session (branch without modifying the original)
+const s3 = claude.session({ resume: session.sessionId!, fork: true })
+```
+
+### Structured Output
+
+Get typed JSON responses via JSON Schema:
+
+```typescript
+const result = await claude.query('Extract all API endpoints from the codebase', {
+  schema: {
+    type: 'object',
+    properties: {
+      endpoints: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            method: { type: 'string' },
+            path: { type: 'string' },
+            handler: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+})
+console.log(result.structured)
+// { endpoints: [{ method: 'GET', path: '/api/users', handler: 'getUsers' }, ...] }
+```
+
+### Parallel Execution
+
+Run independent queries concurrently (each spawns a separate CLI process):
+
+```typescript
+const [bugs, tests, docs] = await claude.parallel([
+  { prompt: 'Find bugs in src/', options: { cwd: './src' } },
+  { prompt: 'Run the test suite', options: { allowedTools: ['Bash'] } },
+  { prompt: 'Review documentation', options: { permissionMode: 'plan' } },
+])
+```
+
+### Recurring Tasks
+
+Node.js-level equivalent of the `/loop` CLI command:
+
+```typescript
+const job = claude.loop('5m', 'Check CI pipeline status and report failures')
+
+job.on('result', (result) => {
+  console.log(`[${new Date().toISOString()}] ${result.text}`)
+})
+
+job.on('error', (err) => {
+  console.error('Check failed:', err.message)
+})
+
+// Stop when no longer needed
+job.stop()
+```
+
+Supported intervals: `'30s'`, `'5m'`, `'2h'`, `'1d'`, or raw milliseconds.
+
+### MCP Servers
+
+Connect Model Context Protocol servers:
+
+```typescript
+const claude = new Claude({
+  // From config file
+  mcpConfig: './mcp.json',
+
+  // Or inline definitions
+  mcpServers: {
+    playwright: {
+      command: 'npx',
+      args: ['@playwright/mcp@latest'],
+    },
+    database: {
+      type: 'http',
+      url: 'http://localhost:3001/mcp',
+    },
+  },
+})
+```
+
+### Custom Subagents
+
+Define specialized agents:
+
+```typescript
+const claude = new Claude({
+  agents: {
+    reviewer: {
+      description: 'Code review expert',
+      model: 'haiku',
+      tools: ['Read', 'Glob', 'Grep'],
+      prompt: 'Review code for bugs, security issues, and style',
+    },
+    deployer: {
+      description: 'Deployment automation agent',
+      tools: ['Bash', 'Read'],
+      permissionMode: 'acceptEdits',
+    },
+  },
+})
+```
+
+### Git Worktree Isolation
+
+Run operations in an isolated copy of the repository:
+
+```typescript
+const result = await claude.query('Refactor the entire auth module', {
+  worktree: 'refactor-auth',  // or `true` for auto-generated name
+})
+```
+
+### Piped Input
+
+Pass data alongside the prompt (like `echo data | claude -p "prompt"`):
+
+```typescript
+import { readFileSync } from 'node:fs'
+
+const result = await claude.query('Analyze this error log and suggest fixes', {
+  input: readFileSync('./error.log', 'utf-8'),
+})
+```
+
+### Lifecycle Hooks
+
+Attach hooks to tool execution:
+
+```typescript
+const claude = new Claude({
+  hooks: {
+    PostToolUse: [
+      {
+        matcher: 'Edit|Write',
+        hooks: [{ command: 'prettier --write ${file_path}' }],
+      },
+    ],
+    PreToolUse: [
+      {
+        matcher: 'Bash',
+        hooks: [{ command: './scripts/validate-command.sh', timeout: 5 }],
+      },
+    ],
+  },
+})
+```
+
+### Full Configuration
+
+All Claude Code CLI capabilities in one place:
+
+```typescript
+const claude = new Claude({
+  // CLI binary
+  executable: '/usr/local/bin/claude',
+  cwd: '/path/to/project',
+
+  // Model
+  model: 'opus',                      // 'opus' | 'sonnet' | 'haiku' | full model ID
+  effortLevel: 'high',                // 'low' | 'medium' | 'high'
+  fallbackModel: 'sonnet',            // auto-fallback on failure
+
+  // Permissions
+  permissionMode: 'acceptEdits',      // 'default' | 'acceptEdits' | 'plan' | 'bypassPermissions'
+  allowedTools: ['Read', 'Edit', 'Bash(npm run *)'],
+  disallowedTools: ['WebFetch'],
+
+  // Prompts
+  systemPrompt: 'You are a senior TypeScript developer',
+  appendSystemPrompt: 'Always write tests for new code',
+
+  // Limits
+  maxTurns: 10,                       // max agentic turns per query
+  maxBudget: 5.0,                     // max USD per query
+
+  // Directories
+  additionalDirs: ['../shared-lib', '../proto'],
+
+  // MCP
+  mcpConfig: './mcp.json',
+  mcpServers: { /* ... */ },
+
+  // Agents
+  agents: { /* ... */ },
+
+  // Hooks
+  hooks: { /* ... */ },
+
+  // Environment
+  env: {
+    MAX_THINKING_TOKENS: '50000',
+    CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
+  },
+
+  // Session
+  noSessionPersistence: true,         // for CI/automation
+})
+
+// Override any option per query
+const result = await claude.query('Analyze this module', {
+  model: 'haiku',                     // cheaper model for this query
+  permissionMode: 'plan',             // read-only
+  maxTurns: 3,
+})
+```
+
+## Error Handling
+
+All errors extend `ClaudeConnectorError` for uniform catching:
+
+```typescript
+import {
+  Claude,
+  ClaudeConnectorError,
+  CliNotFoundError,
+  CliExecutionError,
+  CliTimeoutError,
+  ParseError,
+  ValidationError,
+} from 'claude-connector'
+
+try {
+  const result = await claude.query('Fix the bug')
+} catch (err) {
+  if (err instanceof CliNotFoundError) {
+    // Claude Code CLI not installed or wrong path
+    console.error(`CLI not found: ${err.executable}`)
+  } else if (err instanceof CliExecutionError) {
+    // Non-zero exit code
+    console.error(`Exit ${err.exitCode}: ${err.stderr}`)
+  } else if (err instanceof CliTimeoutError) {
+    // Exceeded timeout
+    console.error(`Timed out after ${err.timeoutMs}ms`)
+  } else if (err instanceof ParseError) {
+    // Unexpected CLI output
+    console.error(`Parse failed: ${err.rawOutput.slice(0, 100)}`)
+  } else if (err instanceof ClaudeConnectorError) {
+    // Any other library error
+    console.error(err.message)
+  }
+}
+```
+
+## Custom Executor
+
+The `IExecutor` abstraction lets you swap the CLI backend for testing, mocking, or future SDK integration:
+
+```typescript
+import { Claude, type IExecutor, type ExecuteOptions, type QueryResult, type StreamEvent } from 'claude-connector'
+
+class MockExecutor implements IExecutor {
+  async execute(args: readonly string[], options: ExecuteOptions): Promise<QueryResult> {
+    return {
+      text: 'Mocked response',
+      sessionId: 'mock-session',
+      usage: { inputTokens: 0, outputTokens: 0 },
+      cost: null,
+      durationMs: 0,
+      messages: [],
+      structured: null,
+      raw: {},
+    }
+  }
+
+  async *stream(args: readonly string[], options: ExecuteOptions): AsyncIterable<StreamEvent> {
+    yield { type: 'text', text: 'Mocked stream' }
+    yield {
+      type: 'result',
+      text: 'Mocked stream',
+      sessionId: 'mock-session',
+      usage: { inputTokens: 0, outputTokens: 0 },
+      cost: null,
+      durationMs: 0,
+    }
+  }
+}
+
+// Use in tests or with future backends
+const claude = new Claude({ model: 'opus' }, new MockExecutor())
+```
+
+## Architecture
+
+```
+┌─────────┐     ┌─────────────┐     ┌────────────┐     ┌──────────────┐
+│  Claude  │────>│ ArgsBuilder │────>│  IExecutor  │────>│ CLI Process   │
+│ (facade) │     │             │     │ (abstract)  │     │ (claude -p)   │
+└─────────┘     └─────────────┘     └────────────┘     └──────────────┘
+     │                                    ^
+     v                                    |
+  Session                          CliExecutor (default)
+  Scheduler                        SdkExecutor (future)
+```
+
+- **Zero dependencies** — only `child_process` and `events` from Node.js
+- **Executor pattern** — swap CLI for SDK/HTTP without touching consumer code
+- **Stateless queries** — each `query()` spawns an independent process
+- **Immutable config** — client options frozen at construction, per-query overrides are non-destructive
+
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for detailed design documentation.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [`examples/interactive-chat`](./examples/interactive-chat) | Terminal chat — ask questions, get answers in real time |
+| [`examples/integration-test`](./examples/integration-test) | Package integration test (mock executor) |
+
+```bash
+# Try the interactive chat:
+cd examples/interactive-chat
+npm install
+npm start          # standard mode
+npm run stream     # streaming mode (word by word)
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](./docs/ARCHITECTURE.md) | Design principles, SOLID breakdown, data flow diagrams |
+| [API Reference](./docs/API.md) | Complete reference for all classes, methods, types, and options |
+| [Changelog](./CHANGELOG.md) | Version history |
+| [Contributing](./CONTRIBUTING.md) | Development setup and guidelines |
+
+## Development
+
+```bash
+git clone git@github.com:scott-walker/claude-connector.git
+cd claude-connector
+npm install
+
+npm run build              # compile TypeScript
+npm test                   # run 82 unit tests
+npm run test:integration   # build + run integration test
+npm run typecheck           # type-check without emitting
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/builder/args-builder.d.ts

@@ -0,0 +1,64 @@
+import type { ClientOptions, QueryOptions } from '../types/index.js';
+/**
+ * Builds the CLI argument array from merged client + query options.
+ *
+ * ## Separation of concerns
+ *
+ * ArgsBuilder is purely functional — it takes options and returns `string[]`.
+ * It has no side effects, no I/O, and no dependency on the executor.
+ * This makes it trivially testable and replaceable.
+ *
+ * ## Merging strategy
+ *
+ * Query-level options override client-level options. Arrays are replaced, not merged.
+ * This follows the principle of least surprise: if you set `allowedTools` per-query,
+ * you get exactly those tools, not a union with client defaults.
+ */
+/** Merged options ready for argument building. */
+export interface ResolvedOptions {
+    readonly prompt: string;
+    readonly outputFormat: 'json' | 'stream-json';
+    readonly cwd: string;
+    readonly model?: string;
+    readonly effortLevel?: string;
+    readonly fallbackModel?: string;
+    readonly permissionMode?: string;
+    readonly allowedTools?: readonly string[];
+    readonly disallowedTools?: readonly string[];
+    readonly systemPrompt?: string;
+    readonly appendSystemPrompt?: string;
+    readonly maxTurns?: number;
+    readonly maxBudget?: number;
+    readonly additionalDirs?: readonly string[];
+    readonly mcpConfig?: string | readonly string[];
+    readonly mcpServers?: Readonly<Record<string, unknown>>;
+    readonly agents?: Readonly<Record<string, unknown>>;
+    readonly hooks?: Readonly<Record<string, unknown>>;
+    readonly noSessionPersistence?: boolean;
+    readonly worktree?: boolean | string;
+    readonly sessionId?: string;
+    readonly continueSession?: boolean;
+    readonly forkSession?: boolean;
+    readonly schema?: Record<string, unknown>;
+}
+/**
+ * Merge client-level defaults with per-query overrides.
+ */
+export declare function mergeOptions(client: ClientOptions, query: QueryOptions | undefined, extra: {
+    prompt: string;
+    outputFormat: 'json' | 'stream-json';
+    sessionId?: string;
+    continueSession?: boolean;
+    forkSession?: boolean;
+}): ResolvedOptions;
+/**
+ * Convert resolved options into a CLI argument array.
+ *
+ * @returns Array of strings to pass to `spawn('claude', args)`.
+ */
+export declare function buildArgs(options: ResolvedOptions): string[];
+/**
+ * Resolve environment variables from client + query options.
+ */
+export declare function resolveEnv(client: ClientOptions, query: QueryOptions | undefined): Record<string, string>;
+//# sourceMappingURL=args-builder.d.ts.map

package/dist/builder/args-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-builder.d.ts","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AAEH,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,KAAK,EAAE;IACL,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,eAAe,CA2BjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CA4F5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxB"}

package/dist/builder/args-builder.js

@@ -0,0 +1,134 @@
+/**
+ * Merge client-level defaults with per-query overrides.
+ */
+export function mergeOptions(client, query, extra) {
+    return {
+        prompt: extra.prompt,
+        outputFormat: extra.outputFormat,
+        cwd: query?.cwd ?? client.cwd ?? process.cwd(),
+        model: query?.model ?? client.model,
+        effortLevel: query?.effortLevel ?? client.effortLevel,
+        fallbackModel: client.fallbackModel,
+        permissionMode: query?.permissionMode ?? client.permissionMode,
+        allowedTools: query?.allowedTools ?? client.allowedTools,
+        disallowedTools: query?.disallowedTools ?? client.disallowedTools,
+        systemPrompt: query?.systemPrompt ?? client.systemPrompt,
+        appendSystemPrompt: query?.appendSystemPrompt ?? client.appendSystemPrompt,
+        maxTurns: query?.maxTurns ?? client.maxTurns,
+        maxBudget: query?.maxBudget ?? client.maxBudget,
+        additionalDirs: query?.additionalDirs ?? client.additionalDirs,
+        mcpConfig: client.mcpConfig,
+        mcpServers: client.mcpServers,
+        agents: client.agents,
+        hooks: client.hooks,
+        noSessionPersistence: client.noSessionPersistence,
+        worktree: query?.worktree,
+        sessionId: extra.sessionId,
+        continueSession: extra.continueSession,
+        forkSession: extra.forkSession,
+        schema: query?.schema,
+    };
+}
+/**
+ * Convert resolved options into a CLI argument array.
+ *
+ * @returns Array of strings to pass to `spawn('claude', args)`.
+ */
+export function buildArgs(options) {
+    const args = ['--print', '--output-format', options.outputFormat];
+    // ── Prompt ──────────────────────────────────────────────────────
+    args.push(options.prompt);
+    // ── Session ─────────────────────────────────────────────────────
+    if (options.continueSession) {
+        args.push('--continue');
+    }
+    if (options.sessionId) {
+        args.push('--resume', options.sessionId);
+    }
+    if (options.forkSession) {
+        args.push('--fork-session');
+    }
+    // ── Model ───────────────────────────────────────────────────────
+    if (options.model) {
+        args.push('--model', options.model);
+    }
+    if (options.fallbackModel) {
+        args.push('--fallback-model', options.fallbackModel);
+    }
+    // ── Permissions ─────────────────────────────────────────────────
+    if (options.permissionMode) {
+        args.push('--permission-mode', options.permissionMode);
+    }
+    if (options.allowedTools?.length) {
+        args.push('--allowedTools', ...options.allowedTools);
+    }
+    if (options.disallowedTools?.length) {
+        args.push('--disallowedTools', ...options.disallowedTools);
+    }
+    // ── System prompt ───────────────────────────────────────────────
+    if (options.systemPrompt) {
+        args.push('--system-prompt', options.systemPrompt);
+    }
+    if (options.appendSystemPrompt) {
+        args.push('--append-system-prompt', options.appendSystemPrompt);
+    }
+    // ── Limits ──────────────────────────────────────────────────────
+    if (options.maxTurns !== undefined) {
+        args.push('--max-turns', String(options.maxTurns));
+    }
+    if (options.maxBudget !== undefined) {
+        args.push('--max-budget-usd', String(options.maxBudget));
+    }
+    // ── Directories ─────────────────────────────────────────────────
+    if (options.additionalDirs?.length) {
+        for (const dir of options.additionalDirs) {
+            args.push('--add-dir', dir);
+        }
+    }
+    // ── MCP ─────────────────────────────────────────────────────────
+    if (options.mcpConfig) {
+        const configs = Array.isArray(options.mcpConfig) ? options.mcpConfig : [options.mcpConfig];
+        for (const cfg of configs) {
+            args.push('--mcp-config', cfg);
+        }
+    }
+    // ── Agents ──────────────────────────────────────────────────────
+    if (options.agents && Object.keys(options.agents).length > 0) {
+        args.push('--agents', JSON.stringify(options.agents));
+    }
+    // ── Structured output ───────────────────────────────────────────
+    if (options.schema) {
+        args.push('--json-schema', JSON.stringify(options.schema));
+    }
+    // ── Worktree ────────────────────────────────────────────────────
+    if (options.worktree) {
+        if (typeof options.worktree === 'string') {
+            args.push('--worktree', options.worktree);
+        }
+        else {
+            args.push('--worktree');
+        }
+    }
+    // ── Misc ────────────────────────────────────────────────────────
+    if (options.noSessionPersistence) {
+        args.push('--no-session-persistence');
+    }
+    return args;
+}
+/**
+ * Resolve environment variables from client + query options.
+ */
+export function resolveEnv(client, query) {
+    const env = {};
+    if (client.env) {
+        Object.assign(env, client.env);
+    }
+    if (query?.env) {
+        Object.assign(env, query.env);
+    }
+    if (client.effortLevel || query?.effortLevel) {
+        env['CLAUDE_CODE_EFFORT_LEVEL'] = (query?.effortLevel ?? client.effortLevel);
+    }
+    return env;
+}
+//# sourceMappingURL=args-builder.js.map

package/dist/builder/args-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-builder.js","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"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"}

package/dist/builder/index.d.ts

@@ -0,0 +1,2 @@
+export { buildArgs, mergeOptions, resolveEnv, type ResolvedOptions } from './args-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builder/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/builder/index.js

@@ -0,0 +1,2 @@
+export { buildArgs, mergeOptions, resolveEnv } from './args-builder.js';
+//# sourceMappingURL=index.js.map