feat: add helper factories for claude and gemini

Author: OhadAssulin

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.14.1] - 2025-11-10
+### ✨ Helper APIs
+- Added `createHeadlessClaude()` and `createHeadlessGemini()` convenience helpers, mirroring the Codex helper so consumers can get a coder without calling `registerAdapter` manually.
+- Both adapters now guard their runtime entry points to ensure they only execute on the server (Node) and emit clearer errors when imported in browser builds.
+- Documentation and smoke tests now demonstrate the helper-based workflows, keeping framework examples (Next.js, etc.) concise.
+
 ## [0.14.0] - 2025-11-10
 ### 🚀 Enhancements
 - Added `createHeadlessCodex()` helper that auto-registers the adapter and returns a coder, reducing the boilerplate needed in most server runtimes.

README.md

@@ -67,12 +67,9 @@ console.log(result.text);
 ## 🌊 Streaming Example (Claude)
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core/factory';
-import { CODER_NAME as CLAUDE_CODER, createAdapter as createClaudeAdapter } from '@headless-coder-sdk/claude-adapter';
-
-registerAdapter(CLAUDE_CODER, createClaudeAdapter);
+import { createHeadlessClaude } from '@headless-coder-sdk/claude-adapter';
 
-const claude = createCoder(CLAUDE_CODER, {
+const claude = createHeadlessClaude({
   workingDirectory: process.cwd(),
   permissionMode: 'bypassPermissions',
 });
@@ -94,12 +91,9 @@ console.log(followUp.text);
 ## 🧩 Structured Output Example (Gemini)
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core/factory';
-import { CODER_NAME as GEMINI_CODER, createAdapter as createGeminiAdapter } from '@headless-coder-sdk/gemini-adapter';
-
-registerAdapter(GEMINI_CODER, createGeminiAdapter);
+import { createHeadlessGemini } from '@headless-coder-sdk/gemini-adapter';
 
-const gemini = createCoder(GEMINI_CODER, {
+const gemini = createHeadlessGemini({
   workingDirectory: process.cwd(),
   includeDirectories: [process.cwd()],
 });
@@ -150,26 +144,13 @@ console.log(followUp.text);
 ## 🔄 Multi-Provider Workflow
 
 ```ts
-import {
-  registerAdapter,
-  createCoder,
-} from '@headless-coder-sdk/core/factory';
-import {
-  CODER_NAME as CODEX,
-  createAdapter as createCodex,
-} from '@headless-coder-sdk/codex-adapter';
-import {
-  CODER_NAME as CLAUDE,
-  createAdapter as createClaude,
-} from '@headless-coder-sdk/claude-adapter';
-import {
-  CODER_NAME as GEMINI,
-  createAdapter as createGemini,
-} from '@headless-coder-sdk/gemini-adapter';
-
-registerAdapter(CODEX, createCodex);
-registerAdapter(CLAUDE, createClaude);
-registerAdapter(GEMINI, createGemini);
+import { createHeadlessCodex } from '@headless-coder-sdk/codex-adapter';
+import { createHeadlessClaude } from '@headless-coder-sdk/claude-adapter';
+import { createHeadlessGemini } from '@headless-coder-sdk/gemini-adapter';
+
+const codex = createHeadlessCodex();
+const claude = createHeadlessClaude();
+const gemini = createHeadlessGemini({ workingDirectory: process.cwd() });
 
 // 1) Claude + Codex perform code review concurrently and emit structured findings.
 const reviewSchema = {
@@ -192,7 +173,6 @@ const reviewSchema = {
 } as const;
 
 async function runMultiProviderReview(commitHash: string) {
-  const [claude, codex] = [createCoder(CLAUDE), createCoder(CODEX)];
   const [claudeThread, codexThread] = await Promise.all([
     claude.startThread(),
     codex.startThread(),
@@ -212,7 +192,6 @@ async function runMultiProviderReview(commitHash: string) {
   ];
 
   // 2) Gemini waits for both reviewers, then fixes each issue sequentially.
-  const gemini = createCoder(GEMINI, { workingDirectory: process.cwd() });
   const geminiThread = await gemini.startThread();
 
   for (const issue of combinedIssues) {
@@ -228,7 +207,11 @@ async function runMultiProviderReview(commitHash: string) {
     ]);
   }
 
-  await Promise.all([claude.close?.(claudeThread), codex.close?.(codexThread), gemini.close?.(geminiThread)]);
+  await Promise.all([
+    claude.close?.(claudeThread),
+    codex.close?.(codexThread),
+    gemini.close?.(geminiThread),
+  ]);
 }
 ```
 
@@ -329,6 +312,7 @@ Open an [issue](https://github.com/OhadAssulin/headless-coder-sdk/issues) or sub
 
 - Every workspace now emits flattened entry points at `dist/*.js` (ESM) and `dist/*.cjs` (CommonJS), with `.d.ts` files sitting beside them for better editor support.
 - You can import `createCoder` or helper utilities directly from `@headless-coder-sdk/core` and `@headless-coder-sdk/codex-adapter` without deep `dist/*/src` paths—the `main`/`module` fields now point at those root files.
+- Helper factories (`createHeadlessCodex/Claude/Gemini`) register adapters and return coders in one call, making server-only integrations simpler.
 - `package.json` is exposed via the exports map (`import '@headless-coder-sdk/core/package.json'`) for tooling that needs to inspect versions at runtime.
 - `@headless-coder-sdk/codex-adapter` forks a worker via `fileURLToPath(new URL('./worker.js', import.meta.url))`; keep `dist/worker.js` adjacent when rebundling so that child processes can spawn correctly.
 

packages/claude-adapter/README.md

@@ -11,15 +11,15 @@ npm install @headless-coder-sdk/core @headless-coder-sdk/claude-adapter @anthrop
 ## Usage
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core';
-import { CODER_NAME as CLAUDE, createAdapter } from '@headless-coder-sdk/claude-adapter';
+import { createHeadlessClaude } from '@headless-coder-sdk/claude-adapter';
 
-registerAdapter(CLAUDE, createAdapter);
-const coder = createCoder(CLAUDE, { permissionMode: 'bypassPermissions' });
+const coder = createHeadlessClaude({ permissionMode: 'bypassPermissions' });
 
 const thread = await coder.startThread({ workingDirectory: process.cwd() });
 const result = await thread.run('Summarise the feature flag rollout plan.');
 console.log(result.text);
 ```
 
+`createHeadlessClaude` registers the adapter (if needed) and returns a coder so you can skip the manual `registerAdapter` boilerplate.
+
 > Heads up: the Anthropic SDK requires Node 18+. Make sure the `CLAUDE_API_KEY` environment variable is available before running the adapter.

packages/claude-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/claude-adapter",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -19,7 +19,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "*",
-    "@headless-coder-sdk/core": "^0.14.0"
+    "@headless-coder-sdk/core": "^0.14.1"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

packages/claude-adapter/src/index.ts

@@ -10,7 +10,12 @@ import {
   type PermissionMode,
 } from '@anthropic-ai/claude-agent-sdk';
 import { randomUUID } from 'node:crypto';
-import { now } from '@headless-coder-sdk/core';
+import {
+  now,
+  registerAdapter,
+  getAdapterFactory,
+  createCoder,
+} from '@headless-coder-sdk/core';
 import type {
   AdapterFactory,
   HeadlessCoder,
@@ -31,6 +36,16 @@ export function createAdapter(defaults?: StartOpts): HeadlessCoder {
 }
 (createAdapter as AdapterFactory).coderName = CODER_NAME;
 
+const isNodeRuntime = typeof process !== 'undefined' && !!process.versions?.node;
+
+export function createHeadlessClaude(defaults?: StartOpts): HeadlessCoder {
+  ensureNodeRuntime('create a Claude coder');
+  if (!getAdapterFactory(CODER_NAME)) {
+    registerAdapter(createAdapter as AdapterFactory);
+  }
+  return createCoder(CODER_NAME, defaults);
+}
+
 interface ClaudeThreadState {
   sessionId: string;
   opts: StartOpts;
@@ -49,6 +64,12 @@ interface ActiveClaudeRun {
 const STRUCTURED_OUTPUT_SUFFIX =
   'You must respond with valid JSON that satisfies the provided schema. Do not include prose before or after the JSON.';
 
+function ensureNodeRuntime(action: string): void {
+  if (!isNodeRuntime) {
+    throw new Error(`@headless-coder-sdk/claude-adapter can only ${action} inside Node.js.`);
+  }
+}
+
 function applyOutputSchemaPrompt(input: PromptInput, schema?: object): PromptInput {
   if (!schema) return input;
   const schemaSnippet = JSON.stringify(schema, null, 2);
@@ -187,8 +208,9 @@ export class ClaudeAdapter implements HeadlessCoder {
    *
    * Raises:
    *   Error: Propagated when the Claude Agent SDK surfaces a failure event.
-   */
-  private async runInternal(thread: ThreadHandle, input: PromptInput, runOpts?: RunOpts): Promise<RunResult> {
+  */
+ private async runInternal(thread: ThreadHandle, input: PromptInput, runOpts?: RunOpts): Promise<RunResult> {
+    ensureNodeRuntime('run Claude');
     const state = thread.internal as ClaudeThreadState;
     this.assertIdle(state);
     const structuredPrompt = applyOutputSchemaPrompt(toPrompt(input), runOpts?.outputSchema);
@@ -250,12 +272,13 @@ export class ClaudeAdapter implements HeadlessCoder {
    *
    * Raises:
    *   Error: Propagated when the Claude Agent SDK terminates with an error.
-   */
-  private runStreamedInternal(
-    thread: ThreadHandle,
-    input: PromptInput,
-    runOpts?: RunOpts,
-  ): EventIterator {
+  */
+ private runStreamedInternal(
+   thread: ThreadHandle,
+   input: PromptInput,
+   runOpts?: RunOpts,
+ ): EventIterator {
+    ensureNodeRuntime('stream Claude events');
     const state = thread.internal as ClaudeThreadState;
     this.assertIdle(state);
     const structuredPrompt = applyOutputSchemaPrompt(toPrompt(input), runOpts?.outputSchema);

packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/codex-adapter",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -27,7 +27,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.14.0",
+    "@headless-coder-sdk/core": "^0.14.1",
     "@openai/codex-sdk": "^0.57.0"
   },
   "devDependencies": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/core",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Unified SDK for headless AI coders (Codex, Claude, Gemini) with standardized threading, streaming, and sandboxing.",
   "type": "module",
   "main": "./dist/index.cjs",

packages/gemini-adapter/README.md

@@ -13,15 +13,18 @@ You will also need the Gemini CLI installed somewhere on your PATH (or pass `gem
 ## Usage
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core';
-import { CODER_NAME as GEMINI, createAdapter } from '@headless-coder-sdk/gemini-adapter';
+import { createHeadlessGemini } from '@headless-coder-sdk/gemini-adapter';
 
-registerAdapter(GEMINI, createAdapter);
-const coder = createCoder(GEMINI, { includeDirectories: [process.cwd()] });
+const coder = createHeadlessGemini({
+  includeDirectories: [process.cwd()],
+  workingDirectory: process.cwd(),
+});
 
 const thread = await coder.startThread();
 const result = await thread.run('List the areas of the repo that need more tests.');
 console.log(result.text);
 ```
 
-> Note: resume support depends on the Gemini CLI version—check the package README or upstream release notes for the latest status.
+`createHeadlessGemini` registers the adapter and returns a coder, so you can instantiate it inside server code without touching the registry manually.
+
+> Note: resume support depends on the Gemini CLI version—check the package README or upstream release notes for the latest status. The adapter shells out via Node’s `child_process`, so keep it on the server (Next.js API routes, background workers, etc.).

packages/gemini-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/gemini-adapter",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -18,7 +18,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.14.0"
+    "@headless-coder-sdk/core": "^0.14.1"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

packages/gemini-adapter/src/index.ts

@@ -5,7 +5,12 @@
 import { spawn, ChildProcess } from 'node:child_process';
 import * as readline from 'node:readline';
 import { once } from 'node:events';
-import { now } from '@headless-coder-sdk/core';
+import {
+  now,
+  registerAdapter,
+  getAdapterFactory,
+  createCoder,
+} from '@headless-coder-sdk/core';
 import type {
   AdapterFactory,
   HeadlessCoder,
@@ -26,9 +31,25 @@ export function createAdapter(defaults?: StartOpts): HeadlessCoder {
 }
 (createAdapter as AdapterFactory).coderName = CODER_NAME;
 
+const isNodeRuntime = typeof process !== 'undefined' && !!process.versions?.node;
+
+export function createHeadlessGemini(defaults?: StartOpts): HeadlessCoder {
+  ensureNodeRuntime('create a Gemini coder');
+  if (!getAdapterFactory(CODER_NAME)) {
+    registerAdapter(createAdapter as AdapterFactory);
+  }
+  return createCoder(CODER_NAME, defaults);
+}
+
 const STRUCTURED_OUTPUT_SUFFIX =
   'Respond with JSON that matches the provided schema. Do not include explanatory text outside the JSON.';
 
+function ensureNodeRuntime(action: string): void {
+  if (!isNodeRuntime) {
+    throw new Error(`@headless-coder-sdk/gemini-adapter can only ${action} inside Node.js.`);
+  }
+}
+
 const SOFT_KILL_DELAY_MS = 250;
 const HARD_KILL_DELAY_MS = 1500;
 const DONE = Symbol('gemini-stream-done');
@@ -161,6 +182,7 @@ export class GeminiAdapter implements HeadlessCoder {
    *   Error: When the Gemini CLI exits with a non-zero status.
    */
   private async runInternal(handle: ThreadHandle, input: PromptInput, opts?: RunOpts): Promise<RunResult> {
+    ensureNodeRuntime('run Gemini');
     const state = handle.internal as GeminiThreadState;
     this.assertIdle(state);
     const prompt = applyOutputSchemaPrompt(input, opts?.outputSchema);
@@ -207,6 +229,7 @@ export class GeminiAdapter implements HeadlessCoder {
    *   Error: When the Gemini CLI process fails before emitting events.
    */
   private runStreamedInternal(handle: ThreadHandle, input: PromptInput, opts?: RunOpts): EventIterator {
+    ensureNodeRuntime('stream Gemini events');
     const state = handle.internal as GeminiThreadState;
     this.assertIdle(state);
     const prompt = applyOutputSchemaPrompt(input, opts?.outputSchema);