AI SDK Provider for Claude Agent SDK

Latest Release: Version 3.x supports AI SDK v6 stable with the Claude Agent SDK. For AI SDK v5 support, use the ai-sdk-v5 tag.

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 | | ---------------- | -------------- | ------------------------------------ | -------------------- | ------ | --------------------------------------------------------------------------------------- | | 3.x.x | v6 | @anthropic-ai/claude-agent-sdk | latest | Stable | main | | 2.x.x | v5 | @anthropic-ai/claude-agent-sdk | ai-sdk-v5 | Stable | ai-sdk-v5 | | 1.x.x | v5 | @anthropic-ai/claude-code (legacy) | v1-claude-code-sdk | Legacy | v1 | | 0.x.x | v4 | @anthropic-ai/claude-code (legacy) | ai-sdk-v4 | Legacy | ai-sdk-v4 |

Installing the Right Version

For AI SDK v6 (recommended):

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

For AI SDK v5:

npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0

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

Starting from v3.2.0, this package requires Zod 4.

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

Note: Zod 3 support was dropped in v3.2.0 due to the underlying @anthropic-ai/claude-agent-sdk@0.2.x requiring Zod 4. If you need Zod 3 support, use ai-sdk-provider-claude-code@3.1.x.

Installation

1. Install and authenticate the CLI

See the official docs for platform-specific options.

curl -fsSL https://claude.ai/install.sh | bash
claude auth login

2. Add the provider

# For AI SDK v6 (recommended)
npm install ai-sdk-provider-claude-code ai@^6.0.0

# For AI SDK v5
npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0

# For AI SDK 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 Agent 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 v6

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 v5

// npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0
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);

Breaking Changes

Version 3.0.0 (AI SDK v6 Stable)

This version upgrades to AI SDK v6 stable with updated provider types:

• usage.raw now contains raw provider usage (previously in providerMetadata['claude-code'].rawUsage)
• Internal type changes for LanguageModelV3Usage and LanguageModelV3FinishReason (transparent to most users)

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:

curl -fsSL https://claude.ai/install.sh | bash
claude auth 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 returns schema-compliant JSON for supported JSON Schema features via 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().describe('Email address (validate client-side)'),
  }),
  prompt: 'Generate a user profile for a software developer',
});

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

Benefits:

• ✅ Schema compliance (supported features) - 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.

**Current CLI li