AI SDK Provider for Claude Code SDK

Latest Release: Version 2.x uses the Claude Agent SDK with native structured outputs support (v2.2.0+). For AI SDK v4 support, use the ai-sdk-v4 tag or version 0.2.x.

ai-sdk-provider-claude-code lets you use Claude via the Vercel AI SDK through the official @anthropic-ai/claude-agent-sdk and the Claude Code CLI.

Version Compatibility

Provider Version	AI SDK Version	Underlying SDK	NPM Tag	Status	Branch
2.x.x	v5	@anthropic-ai/claude-agent-sdk	latest	Stable	main
1.x.x	v5	@anthropic-ai/claude-code (legacy)	v1-claude-code-sdk	Stable	v1
0.x.x	v4	@anthropic-ai/claude-code	ai-sdk-v4	Legacy	ai-sdk-v4

Installing the Right Version

For AI SDK v5 with Claude Agent SDK (recommended):

npm install ai-sdk-provider-claude-code ai
# or explicitly: npm install ai-sdk-provider-claude-code@latest

For AI SDK v5 with Claude Code SDK (legacy):

npm install ai-sdk-provider-claude-code@v1-claude-code-sdk ai

For AI SDK v4 (legacy):

npm install ai-sdk-provider-claude-code@ai-sdk-v4 ai@^4.3.16
# or use specific version: npm install ai-sdk-provider-claude-code@^0.2.2

Zod Compatibility

This package is tested and compatible with both Zod 3 and Zod 4, but there's an important peer dependency consideration:

Current Status

• ✅ Zod 3 (fully supported, no warnings)
• ⚠️ Zod 4 (functional, but requires --legacy-peer-deps)

While this package declares support for both versions (peerDependencies: "zod": "^3.0.0 || ^4.0.0"), the underlying @anthropic-ai/claude-agent-sdk currently only declares support for Zod 3 (peerDependencies: "zod": "^3.24.1").

All 302 tests pass with both Zod 3 and Zod 4. See examples/zod4-compatibility-test.ts for comprehensive compatibility verification.

Installation Instructions

With Zod 3 (recommended for now):

npm install ai-sdk-provider-claude-code ai zod@^3.0.0

With Zod 4 (requires package manager-specific flags):

For npm:

npm install ai-sdk-provider-claude-code ai zod@^4.0.0 --legacy-peer-deps

For pnpm:

pnpm install ai-sdk-provider-claude-code ai zod@^4.0.0 --no-strict-peer-dependencies
# Or configure it project-wide:
pnpm config set strict-peer-dependencies false

For Yarn (Berry/v2+):

yarn add ai-sdk-provider-claude-code ai zod@^4.0.0
# Yarn's peer resolution typically doesn't error here

For Package Developers

If you're developing with this package in your repository, add a configuration file to avoid needing the flag on every install:

For npm (.npmrc):

# .npmrc
legacy-peer-deps=true

For pnpm (.npmrc):

# .npmrc
strict-peer-dependencies=false

Note: The .npmrc file in this repository is committed for CI/development consistency but is not included in the published package (it's excluded via the files field in package.json). End users will still need to use the appropriate flags when installing with Zod 4.

Temporary Workaround: This configuration is needed until @anthropic-ai/claude-agent-sdk adds official Zod 4 support to their peer dependencies. Track progress in the claude-agent-sdk repository.

Installation

1. Install and authenticate the CLI

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

2. Add the provider

# For v5 (recommended)
npm install ai-sdk-provider-claude-code ai

# For v4 (legacy)
npm install ai-sdk-provider-claude-code@ai-sdk-v4 ai@^4.3.16

Disclaimer

This is an unofficial community provider and is not affiliated with or endorsed by Anthropic or Vercel. By using this provider:

• You understand that your data will be sent to Anthropic's servers through the Claude Code SDK
• You agree to comply with Anthropic's Terms of Service
• You acknowledge this software is provided "as is" without warranties of any kind

Please ensure you have appropriate permissions and comply with all applicable terms when using this provider.

Quick Start

AI SDK v5

import { streamText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';

const result = streamText({
  model: claudeCode('haiku'),
  prompt: 'Hello, Claude!',
});

const text = await result.text;
console.log(text);

AI SDK v4

import { generateText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';

const { text } = await generateText({
  model: claudeCode('haiku'),
  prompt: 'Hello, Claude!',
});

console.log(text);

Breaking Changes

Version 2.0.0 (Claude Agent SDK Migration)

This version migrates to @anthropic-ai/claude-agent-sdk with new defaults for better control:

• System prompt is no longer applied by default
• Filesystem settings (CLAUDE.md, settings.json) are no longer loaded by default
• See Migrating to Claude Agent SDK section below for migration details

Version 1.x (AI SDK v5)

See Breaking Changes Guide for details on migrating from v0.x to v1.x.

Key changes:

• Requires AI SDK v5
• New streaming API pattern
• Updated token usage properties
• Changed message types

Models

• opus - Claude Opus (most capable)
• sonnet - Claude Sonnet (balanced performance)
• haiku - Claude Haiku (fastest, most cost-effective)

You can also use full model identifiers directly (e.g., claude-opus-4-5, claude-sonnet-4-5-20250514).

Documentation

• Usage Guide - Comprehensive examples and configuration
• Breaking Changes - v0.x to v1.x migration guide
• Troubleshooting - Common issues and solutions
• Examples - Sample scripts and patterns
• Tool Streaming Support - Event semantics and performance notes

Migrating to Claude Agent SDK (v2.0.0)

Version 2.0.0 migrates from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk. Two defaults changed:

• System prompt is no longer applied by default.
• Filesystem settings (CLAUDE.md, settings.json) are not loaded by default.

Restore old behavior explicitly:

import { claudeCode } from 'ai-sdk-provider-claude-code';

const model = claudeCode('sonnet', {
  systemPrompt: { type: 'preset', preset: 'claude_code' },
  settingSources: ['user', 'project', 'local'],
});

CLAUDE.md requires:

• systemPrompt: { type: 'preset', preset: 'claude_code' }
• settingSources includes 'project'

New recommended behavior (explicit config):

const model = claudeCode('sonnet', {
  systemPrompt: 'You are a helpful assistant specialized in ...',
  settingSources: ['project'], // or omit for no filesystem settings
});

CLI install and auth are unchanged:

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

Migrating from v1.x to v2.0.0

If you're upgrading from version 1.x:

1. Update the package: npm install ai-sdk-provider-claude-code@latest
2. If you relied on default system prompt or CLAUDE.md, add explicit configuration:

   const model = claudeCode('sonnet', {
     systemPrompt: { type: 'preset', preset: 'claude_code' },
     settingSources: ['user', 'project', 'local'],
   });

3. If you never used CLAUDE.md or custom system prompts, no changes needed - v2.0.0 works the same for you.

Benefits of v2.0.0:

• Predictable behavior across environments (no hidden filesystem settings)
• Better suited for CI/CD and multi-tenant applications
• Explicit configuration over implicit defaults
• Future-proof alignment with Claude Agent SDK design

Structured Outputs

This provider supports native structured outputs via the Claude Agent SDK (v0.1.45+). When using generateObject() or streamObject(), the SDK guarantees schema-compliant JSON responses through constrained decoding.

import { generateObject } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';
import { z } from 'zod';

const result = await generateObject({
  model: claudeCode('sonnet'),
  schema: z.object({
    name: z.string(),
    age: z.number(),
    email: z.string().email(),
  }),
  prompt: 'Generate a user profile for a software developer',
});

console.log(result.object); // Guaranteed to match schema
// { name: "Alex Chen", age: 28, email: "alex@example.com" }

Benefits:

• ✅ Guaranteed schema compliance - Constrained decoding ensures valid output
• ✅ No JSON parsing errors - SDK handles all validation
• ✅ No prompt engineering - Schema enforcement is native to the SDK
• ✅ Better performance - No retry/extraction logic needed

Note: A schema is required for JSON output. Using responseFormat: { type: 'json' } without a schema is not supported by Claude Code (matching Anthropic's official provider behavior). An unsupported-setting warning will be emitted and the call will be treated as plain text. Always use generateObject() or streamObject() with a Zod schema for guaranteed JSON output.

Core Features

• 🚀 Vercel AI SDK compatibility
• 🔄 Streaming support
• 💬 Multi-turn conversations
• 🎯 Native structured outputs with guaranteed schema compliance
• 🛑 AbortSignal support
• 🔧 Tool management (MCP servers, permissions)
• 🧩 Callbacks (hooks, canUseTool)

Image Inputs (Streaming Only)

• Enable streaming input (streamingInput: 'always' or provide canUseTool) before sending images.
• Supported payloads: data URLs (data:image/png;base64,...), strings prefixed with base64:<mediaType>,<data>, or objects { data: '<base64>', mimeType: 'image/png' }.
• Remote HTTP(S) image URLs are ignored with the warning "Image URLs are not supported by this provider; supply base64/data URLs." (supportsImageUrls remains false).
• When streaming input is disabled, image parts trigger the streaming prerequisite warning and are omitted from the request.
• Use realistic image payloads—very small placeholders may result in the model asking for a different image.
• examples/images.ts accepts a local image path and converts it to a data URL on the fly: npx tsx examples/images.ts /absolute/path/to/image.png.

Limitations

• Requires Node.js ≥ 18
• Image inputs require streaming mode with base64/data URLs (remote fetch is not supported)
• Some AI SDK parameters unsupported (temperature, maxTokens, etc.)
• canUseTool requires streaming input at the SDK level (AsyncIterable prompt). This provider supports it via streamingInput: use 'auto' (default when canUseTool is set) or 'always'. See GUIDE for details.

Tool Error Parity (Streaming)

• In addition to tool-call and tool-result, this provider emits a distinct tool-error stream event when a tool execution fails.
• For parity with other tool events, tool-error includes providerExecuted: true and providerMetadata['claude-code'] (e.g., rawError). These fields are documented extensions; downstream consumers may safely ignore them if unused.
• See Tool Streaming Support for full event list, ordering guarantees, and performance considerations.

Contributing

We welcome contributions, especially:

• Code structure improvements
• Performance optimizations
• Better error handling
• Additional examples

See Contributing Guidelines for details.

For development status and technical details, see Development Status.

License

MIT