AI SDK Provider for Claude Code SDK

Latest Release: Version 2.x uses the Claude Agent SDK with explicit configuration defaults. Version 1.x is the previous stable release. 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

## Installation

### 1. Install and authenticate the CLI
```bash
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('sonnet'),
  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('sonnet'),
  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 4 Opus (most capable)
• sonnet - Claude 4 Sonnet (balanced performance)

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

Core Features

• 🚀 Vercel AI SDK compatibility
• 🔄 Streaming support
• 💬 Multi-turn conversations
• 🎯 Object generation with JSON schemas
• 🛑 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