not-claude-agent-sdk

A lightweight, zero-dependency alternative to @anthropic-ai/claude-agent-sdk. Instead of bundling the SDK, it spawns the claude CLI as a subprocess and streams back the same typed messages — giving you an identical async-generator API with no extra runtime dependencies.

Prerequisites

You must have Claude Code installed and authenticated before using this package.

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Authenticate

Run claude once in your terminal and follow the prompts to sign in with your Anthropic account (or configure an API key):

claude

You'll be guided through authentication on first launch. Once complete, the CLI stores your credentials locally and you're ready to go.

Tip: You can verify everything is working by running claude "Hello" — you should see a response streamed to your terminal.

Installation

npm install not-claude-agent-sdk

Or with your preferred package manager:

pnpm add not-claude-agent-sdk
yarn add not-claude-agent-sdk

Quick Start

import { query } from "not-claude-agent-sdk";

for await (const message of query({ prompt: "What is 2 + 2?" })) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  if (message.type === "result" && message.subtype === "success") {
    console.log(`\nCost: $${message.total_cost_usd.toFixed(4)}`);
  }
}

Usage

The query() function returns an async generator that yields typed SDKMessage objects — the same types as the official SDK.

import { query, type SDKMessage } from "not-claude-agent-sdk";

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    model: "claude-sonnet-4-6",
    permissionMode: "plan",
    maxTurns: 20,
    systemPrompt: "You are a senior TypeScript engineer.",
  },
});

for await (const message of conversation) {
  switch (message.type) {
    case "system":
      if (message.subtype === "init") {
        console.log(`Model: ${message.model}, Tools: ${message.tools.length}`);
      }
      break;

    case "assistant":
      for (const block of message.message.content) {
        if (block.type === "text") process.stdout.write(block.text);
        if (block.type === "tool_use") console.log(`\n[tool] ${block.name}`);
      }
      break;

    case "result":
      console.log(`Done — ${message.num_turns} turns, $${message.total_cost_usd.toFixed(4)}`);
      break;
  }
}

Interrupting & Closing

const conversation = query({ prompt: "Do a long task" });

// Interrupt current tool execution (sends SIGINT)
await conversation.interrupt();

// Gracefully terminate the process
conversation.close();

Using an AbortController

const controller = new AbortController();

const conversation = query({
  prompt: "Analyze the codebase",
  options: { abortController: controller },
});

// Cancel from anywhere
setTimeout(() => controller.abort(), 30_000);

for await (const message of conversation) {
  // ...
}

MCP Servers

const conversation = query({
  prompt: "List all open issues",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
      },
    },
  },
});

Custom Claude Binary Path

If claude isn't on your PATH, you can point to it explicitly:

query({
  prompt: "Hello",
  options: {
    pathToClaudeCodeExecutable: "/usr/local/bin/claude",
  },
});

Or set the CLAUDE_BIN environment variable:

CLAUDE_BIN=/usr/local/bin/claude node my-script.js

API Reference

query(params: QueryParams): Query

| Parameter | Type | Description | |---|---|---| | params.prompt | string | The prompt to send to Claude | | params.options | QueryOptions | Optional configuration (see below) |

Returns a Query object — an async generator yielding SDKMessage objects, with additional control methods:

| Method / Property | Description | |---|---| | interrupt() | Send SIGINT to interrupt the current tool execution | | close() | Gracefully terminate the Claude process | | childProcess | The underlying ChildProcess (available after iteration starts) |

QueryOptions

| Option | Type | Default | Description | |---|---|---|---| | model | string | CLI default | Model to use (e.g. "claude-sonnet-4-6") | | permissionMode | PermissionMode | "default" | Permission mode for tool execution | | maxTurns | number | — | Maximum number of agentic turns | | maxBudgetUsd | number | — | Maximum spend in USD | | systemPrompt | string | — | Custom system prompt | | allowedTools | string[] | — | Whitelist of allowed tools | | disallowedTools | string[] | — | Blacklist of disallowed tools | | tools | string[] | — | Additional tools to register | | mcpServers | Record<string, McpServerConfig> | — | MCP server configurations | | cwd | string | process.cwd() | Working directory for the Claude process | | env | Record<string, string> | — | Additional environment variables | | abortController | AbortController | — | Controller for cancellation | | thinking | ThinkingConfig | — | Extended thinking configuration | | effort | "low" \| "medium" \| "high" \| "max" | — | Reasoning effort level | | continue | boolean | — | Continue the most recent conversation | | resume | string | — | Resume a specific session by ID | | sessionId | string | — | Use a specific session ID | | debug | boolean | — | Enable debug output | | pathToClaudeCodeExecutable | string | "claude" | Path to the Claude CLI binary |

Message Types

The generator yields these message types (discriminated by message.type):

| Type | Description | |---|---| | system | Init info, status updates, task progress, hooks | | assistant | Claude's responses (text, tool calls, thinking) | | user | Tool results flowing back to Claude | | stream_event | Partial streaming events (when includePartialMessages is enabled) | | result | Final result with usage stats and cost | | tool_progress | Progress updates for long-running tools | | tool_use_summary | Summaries of tool usage | | auth_status | Authentication status changes | | rate_limit_event | Rate limit information | | prompt_suggestion | Suggested follow-up prompts |

License

ISC