tessl/npm-anthropic-ai--claude-agent-sdk

SDK for building AI agents with Claude Code's capabilities to programmatically interact with Claude and build autonomous agents that can understand codebases, edit files, and execute workflows.

Overview

Eval results

Files

Configuration Options

Name: tessl/npm-anthropic-ai--claude-agent-sdk
Author: tessl

Comprehensive configuration via the Options interface.

Interface

interface Options {
  // Model & Execution
  model?: string;
  fallbackModel?: string;
  cwd?: string;
  maxTurns?: number;
  maxBudgetUsd?: number;
  maxThinkingTokens?: number;
  abortController?: AbortController;

  // Tools
  tools?: string[] | {type: 'preset'; preset: 'claude_code'};
  allowedTools?: string[];
  disallowedTools?: string[];

  // Permissions
  permissionMode?: PermissionMode;
  canUseTool?: CanUseTool;
  allowDangerouslySkipPermissions?: boolean;
  permissionPromptToolName?: string;

  // Environment
  additionalDirectories?: string[];
  env?: {[envVar: string]: string | undefined};
  executable?: 'bun' | 'deno' | 'node';
  executableArgs?: string[];
  pathToClaudeCodeExecutable?: string;
  extraArgs?: Record<string, string | null>;

  // Extensions
  agents?: Record<string, AgentDefinition>;
  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
  mcpServers?: Record<string, McpServerConfig>;
  strictMcpConfig?: boolean;

  // System
  systemPrompt?: string | {type: 'preset'; preset: 'claude_code'; append?: string};
  outputFormat?: OutputFormat;
  includePartialMessages?: boolean;

  // Session
  continue?: boolean;
  resume?: string;
  resumeSessionAt?: string;
  forkSession?: boolean;
  settingSources?: SettingSource[];

  // Other
  plugins?: SdkPluginConfig[];
  sandbox?: SandboxSettings;
  betas?: SdkBeta[];
  stderr?: (data: string) => void;
}

Common Configurations

Basic

{
  model: 'claude-sonnet-4-5-20250929',
  cwd: '/path/to/project',
  maxTurns: 20,
  maxBudgetUsd: 1.00
}

Tool Control

// Specific tools only
{allowedTools: ['Read', 'Grep', 'Glob']}

// All except specified
{
  tools: {type: 'preset', preset: 'claude_code'},
  disallowedTools: ['Edit', 'Write', 'Bash']
}

// Minimal toolset
{tools: ['Grep', 'Glob']}

Permission Modes

// Auto-accept edits
{permissionMode: 'acceptEdits'}

// Planning mode (no execution)
{permissionMode: 'plan'}

// Bypass all (requires safety flag)
{
  permissionMode: 'bypassPermissions',
  allowDangerouslySkipPermissions: true
}

// Custom handler
{
  canUseTool: async (toolName, input, opts) => {
    // Custom logic
    return {behavior: 'allow', updatedInput: input};
  }
}

Environment

{
  cwd: '/path/to/project',
  additionalDirectories: ['/path/to/shared'],
  env: {
    NODE_ENV: 'production',
    API_KEY: process.env.API_KEY
  },
  executable: 'bun',
  executableArgs: ['--no-warnings']
}

Session Management

// Continue previous
{continue: true}

// Resume specific session
{resume: 'session-id-123'}

// Resume and fork
{resume: 'session-id-123', forkSession: true}

// Resume from message
{resume: 'session-id', resumeSessionAt: 'msg-uuid'}

Custom Agents

{
  agents: {
    'reviewer': {
      description: 'Reviews code',
      tools: ['Read', 'Grep'],
      prompt: 'Review code for bugs and style',
      model: 'opus'
    }
  }
}

Hooks

{
  hooks: {
    PreToolUse: [{
      hooks: [async (input) => {
        console.log('Tool:', input.tool_name);
        return {continue: true};
      }]
    }]
  }
}

MCP Servers

{
  mcpServers: {
    'db': {
      command: 'node',
      args: ['./db-server.js'],
      env: {DB_HOST: 'localhost'}
    },
    'api': {
      type: 'http',
      url: 'http://localhost:3000/mcp'
    }
  },
  strictMcpConfig: true
}

Sandbox

{
  sandbox: {
    enabled: true,
    autoAllowBashIfSandboxed: true,
    network: {
      allowUnixSockets: ['/var/run/docker.sock'],
      allowLocalBinding: true
    },
    excludedCommands: ['docker']
  }
}

System Prompt

// Custom
{systemPrompt: 'You are a TypeScript expert.'}

// Extend default
{
  systemPrompt: {
    type: 'preset',
    preset: 'claude_code',
    append: 'Explain reasoning step by step.'
  }
}

Structured Output

{
  outputFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        complexity: {type: 'number'},
        issues: {type: 'array', items: {type: 'object'}}
      },
      required: ['complexity']
    }
  }
}

Settings Sources

// All settings
{settingSources: ['user', 'project', 'local']}

// Isolated (no filesystem settings)
{settingSources: []}

// Project only (for CLAUDE.md)
{settingSources: ['project']}

Beta Features

{
  model: 'claude-sonnet-4-5-20250929',
  betas: ['context-1m-2025-08-07'] // 1M token context
}

Debugging

{
  stderr: (data) => console.error('[STDERR]', data),
  includePartialMessages: true // Streaming updates
}

Types

type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk';
type SettingSource = 'user' | 'project' | 'local';
type SdkBeta = 'context-1m-2025-08-07';

interface OutputFormat {
  type: 'json_schema';
  schema: Record<string, unknown>;
}

interface SdkPluginConfig {
  type: 'local';
  path: string;
}

Install with Tessl CLI

npx tessl i tessl/npm-anthropic-ai--claude-agent-sdk

docs

apis