Skip to main content
Complete reference for all options available when creating sessions with the Chucky SDK.

​
Quick Reference

const session = client.createSession({
  // Model
  model: 'claude-sonnet-4-5-20250929',
  fallbackModel: 'claude-3-5-haiku-20241022',

  // Limits
  maxTurns: 10,
  maxBudgetUsd: 1.00,
  maxThinkingTokens: 10000,

  // Prompts
  systemPrompt: 'You are a helpful assistant.',

  // Tools
  tools: [myTool],
  mcpServers: [myServer],
  allowedTools: ['tool1', 'tool2'],
  disallowedTools: ['dangerous_tool'],

  // Session management
  sessionId: 'existing-session-id',
  forkSession: false,
  continue: true,

  // Output
  outputFormat: { type: 'json_schema', schema: mySchema },

  // Environment
  env: { API_KEY: 'value' },
  permissionMode: 'default',
});

​
Model Options

​
model

The Claude model to use. 
model: 'claude-sonnet-4-5-20250929'
Available models:
ModelDescription
claude-sonnet-4-5-20250929Fast, capable (recommended)
claude-opus-4-5-20251101Most powerful
claude-3-5-sonnet-20241022Previous Sonnet version
claude-3-5-haiku-20241022Fastest, cheapest
claude-3-opus-20240229Previous Opus version
Shortcuts: 
model: 'sonnet'  // claude-sonnet-4-5-20250929
model: 'opus'    // claude-opus-4-5-20251101
model: 'haiku'   // claude-3-5-haiku-20241022

​
fallbackModel

Model to use if primary model is unavailable or rate-limited. 
fallbackModel: 'claude-3-5-haiku-20241022'

​
Limit Options

​
maxTurns

Maximum number of conversation turns (user message + assistant response = 1 turn). 
maxTurns: 10
When reached, session ends with a result indicating the limit was hit.

​
maxBudgetUsd

Maximum spend for this session in USD. 
maxBudgetUsd: 1.00  // $1.00 limit
Throws BudgetExceededError when exceeded.

​
maxThinkingTokens

Maximum tokens for Claude’s extended thinking (if enabled). 
maxThinkingTokens: 10000

​
Prompt Options

​
systemPrompt

Instructions that guide Claude’s behavior. Can be a string or object. String format: 
systemPrompt: 'You are a helpful coding assistant.'
Object format with preset: 
systemPrompt: {
  type: 'preset',
  preset: 'claude_code',
}
Preset with custom append: 
systemPrompt: {
  type: 'preset',
  preset: 'claude_code',
  append: `
## Additional Context
Working directory: ${process.cwd()}
User preferences: ${userPrefs}
`,
}
Available presets:
PresetDescription
claude_codeFull Claude Code capabilities
assistantGeneral assistant
coderCode-focused assistant

​
Tool Options

​
tools

Array of tool definitions to make available to Claude. 
import { tool, textResult } from '@chucky.cloud/sdk';

const myTool = tool(
  'get_weather',
  'Get weather for a city',
  { type: 'object', properties: { city: { type: 'string' } } },
  async ({ city }) => textResult(`Sunny in ${city}`)
);

const session = client.createSession({
  tools: [myTool],
});

​
mcpServers

Array of MCP server definitions containing multiple tools. 
import { McpServerBuilder, textResult } from '@chucky.cloud/sdk';

const server = new McpServerBuilder('my-tools', '1.0.0')
  .addTool({
    name: 'tool1',
    description: 'First tool',
    inputSchema: { type: 'object', properties: {} },
    handler: async () => textResult('Done'),
  })
  .addTool({
    name: 'tool2',
    description: 'Second tool',
    inputSchema: { type: 'object', properties: {} },
    handler: async () => textResult('Done'),
  })
  .build();

const session = client.createSession({
  mcpServers: [server],
});

​
allowedTools

Whitelist of tool names Claude can use. If specified, only these tools are available. 
allowedTools: ['Read', 'Write', 'Bash']

​
disallowedTools

Blacklist of tool names Claude cannot use. 
disallowedTools: ['Bash', 'Write']  // Read-only mode

​
Session Management

​
sessionId

Resume an existing session by ID. 
const session = client.createSession({
  sessionId: 'sess_abc123...',
});

​
forkSession

Create a copy of an existing session instead of resuming it. 
const session = client.createSession({
  sessionId: 'sess_abc123...',
  forkSession: true,  // Creates a new branch
});

​
continue

Continue from where the previous session left off. 
const session = client.createSession({
  sessionId: 'sess_abc123...',
  continue: true,
});

​
resumeSessionAt

Resume at a specific point in the conversation history. 
const session = client.createSession({
  sessionId: 'sess_abc123...',
  resumeSessionAt: 'conv_xyz789...',  // Conversation ID
});

​
Output Options

​
outputFormat

Force structured output using JSON Schema. 
const session = client.createSession({
  outputFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        summary: { type: 'string' },
        items: {
          type: 'array',
          items: { type: 'string' },
        },
      },
      required: ['summary', 'items'],
    },
  },
});
The final result will be valid JSON matching the schema.

​
includePartialMessages

Include partial (streaming) messages in the message history. 
includePartialMessages: true

​
Environment Options

​
env

Environment variables available to tools in the sandbox. 
env: {
  API_KEY: 'sk-...',
  DATABASE_URL: 'postgres://...',
  DEBUG: 'true',
}

​
permissionMode

How Claude handles permission requests for tools. 
permissionMode: 'default'
Available modes:
ModeDescription
defaultNormal permission checking
planPlan-based restrictions
bypassPermissionsSkip all permission checks

​
allowDangerouslySkipPermissions

Enable bypass of all permission checks. Use with caution. 
allowDangerouslySkipPermissions: true
Only use in trusted environments. This allows Claude to execute any tool without confirmation.

​
Agent Options

​
agents

Define sub-agents that Claude can delegate to. 
agents: {
  researcher: {
    name: 'Researcher',
    description: 'Searches and summarizes information',
    tools: ['WebSearch', 'Read'],
    model: 'claude-3-5-haiku-20241022',
  },
  coder: {
    name: 'Coder',
    description: 'Writes and edits code',
    tools: ['Read', 'Write', 'Bash'],
    model: 'claude-sonnet-4-5-20250929',
  },
}

​
Client Options

Options passed when creating the ChuckyClient: 
const client = new ChuckyClient({
  // Required
  token: 'your-jwt-token',

  // Optional
  baseUrl: 'wss://conjure.chucky.cloud/ws',
  debug: false,
  timeout: 60000,
  keepAliveInterval: 300000,
  autoReconnect: false,
  maxReconnectAttempts: 5,
});

​
token

JWT token for authentication. Required.

​
baseUrl

WebSocket endpoint URL. Override for staging/development. 
baseUrl: 'wss://staging.chucky.cloud/ws'

​
debug

Enable debug logging. 
debug: true

​
timeout

Connection timeout in milliseconds. 
timeout: 60000  // 60 seconds

​
keepAliveInterval

Interval for keep-alive pings in milliseconds. 
keepAliveInterval: 300000  // 5 minutes

​
autoReconnect

Automatically reconnect on connection loss. 
autoReconnect: true

​
maxReconnectAttempts

Maximum reconnection attempts before giving up. 
maxReconnectAttempts: 5

​
Type Definitions

interface SessionOptions {
  // Model
  model?: Model;
  fallbackModel?: Model;

  // Limits
  maxTurns?: number;
  maxBudgetUsd?: number;
  maxThinkingTokens?: number;

  // Prompts
  systemPrompt?: string | SystemPromptConfig;

  // Tools
  tools?: ToolDefinition[];
  mcpServers?: McpServerDefinition[];
  allowedTools?: string[];
  disallowedTools?: string[];

  // Session
  sessionId?: string;
  forkSession?: boolean;
  continue?: boolean;
  resumeSessionAt?: string;

  // Output
  outputFormat?: OutputFormat;
  includePartialMessages?: boolean;

  // Environment
  env?: Record<string, string>;
  permissionMode?: PermissionMode;
  allowDangerouslySkipPermissions?: boolean;

  // Agents
  agents?: Record<string, AgentConfig>;
}

type Model =
  | 'claude-sonnet-4-5-20250929'
  | 'claude-opus-4-5-20251101'
  | 'claude-3-5-sonnet-20241022'
  | 'claude-3-5-haiku-20241022'
  | 'claude-3-opus-20240229'
  | 'sonnet'
  | 'opus'
  | 'haiku'
  | string;

type PermissionMode = 'default' | 'plan' | 'bypassPermissions';

interface OutputFormat {
  type: 'json_schema';
  schema: object;
}

interface SystemPromptConfig {
  type: 'preset';
  preset: 'claude_code' | 'assistant' | 'coder';
  append?: string;
}

​
Examples

​
Minimal Session

const session = client.createSession();
await session.send('Hello');

​
With Tools

const session = client.createSession({
  model: 'claude-sonnet-4-5-20250929',
  mcpServers: [myToolServer],
  maxTurns: 10,
});

​
Structured Output

const session = client.createSession({
  outputFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        answer: { type: 'string' },
        confidence: { type: 'number' },
      },
    },
  },
});

​
Resume Existing

const session = client.createSession({
  sessionId: previousSessionId,
  continue: true,
});

​
Development Mode

const session = client.createSession({
  model: 'haiku',  // Faster, cheaper
  debug: true,
  maxBudgetUsd: 0.10,
});