Skip to main content

​
Run your first agent

Sessions enable multi-turn conversations where Claude remembers previous messages. Use sessions for chat interfaces, complex tasks requiring multiple steps, or any scenario where context matters.

​
Creating a Session

import { ChuckyClient } from '@chucky.cloud/sdk';

const client = new ChuckyClient({ token });

const session = await client.createSession({
  model: 'claude-sonnet-4-5-20250929',
  systemPrompt: 'You are a helpful coding assistant.',
});

​
Session Options

OptionTypeDescription
modelstringClaude model to use
systemPromptstringSystem prompt for the session
toolsTool[]Tools available to Claude
mcpServersMcpServer[]MCP servers to connect
maxTurnsnumberMaximum conversation turns
maxBudgetUsdnumberBudget limit for this session
sessionIdstringResume an existing session
For the complete API, see the Session SDK Reference.

​
Sending Messages

​
Basic Send

const result = await session.send('What is TypeScript?');
console.log(result.text);

​
Streaming

for await (const event of session.sendStream('Explain async/await')) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.text);
      break;
    case 'tool_use':
      console.log(`Calling tool: ${event.name}`);
      break;
    case 'thinking':
      console.log(`[Thinking: ${event.thinking}]`);
      break;
  }
}

​
Session States

Sessions progress through these states: 
idle → initializing → ready ⇄ processing → completed
                        ↓
                     error
StateDescription
idleCreated, not connected
initializingConnecting to server
readyReady to send messages
processingWaiting for response
waiting_toolWaiting for tool result
completedSession finished
errorError occurred
Check the current state: 
console.log(session.state); // 'ready'

​
Event Handlers

Listen to session events: 
session.on({
  onSessionInfo: (info) => {
    console.log('Session started:', info.sessionId);
  },
  onText: (text) => {
    process.stdout.write(text);
  },
  onToolUse: (tool) => {
    console.log(`Tool called: ${tool.name}`, tool.input);
  },
  onToolResult: (callId, result) => {
    console.log(`Tool result for ${callId}:`, result);
  },
  onThinking: (thinking) => {
    console.log('[Thinking]', thinking);
  },
  onComplete: (result) => {
    console.log('Session complete:', result);
  },
  onError: (error) => {
    console.error('Session error:', error);
  },
});

​
Session Persistence

Sessions are automatically persisted. You can resume them later:

​
Get Session ID

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

// Save the session ID
const sessionId = session.sessionId;
console.log('Session ID:', sessionId);

​
Resume Session

// Later, resume the session
const resumedSession = await client.resumeSession(sessionId, {
  model: 'claude-sonnet-4-5-20250929',
});

// Continue the conversation
const result = await resumedSession.send('What did I say before?');

​
Closing Sessions

Always close sessions when done to free resources: 
await session.close();
Or use try/finally: 
const session = await client.createSession({ ... });
try {
  await session.send('Hello!');
  await session.send('How are you?');
} finally {
  await session.close();
}

​
Session Results

After each message, you get a SessionResult: 
interface SessionResult {
  type: 'result';
  subtype: 'success' | 'error' | 'interrupted';
  text?: string;              // Final text response
  messages?: Message[];       // Full conversation history
  total_cost_usd?: number;    // Total cost so far
  duration_secs?: number;     // Response time
  turn_count?: number;        // Number of turns
  session_id?: string;        // For resuming
}

​
Prompt Mode vs Session Mode

Featureclient.prompt()session.send()
StatelessYesNo
Multi-turnNoYes
ResumableNoYes
ContextSingle messageFull conversation
Use caseOne-off questionsChat, complex tasks

​
Example: Chat Interface

import { ChuckyClient } from '@chucky.cloud/sdk';
import * as readline from 'readline';

const client = new ChuckyClient({ token });
const session = await client.createSession({
  model: 'claude-sonnet-4-5-20250929',
  systemPrompt: 'You are a helpful assistant.',
});

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

async function chat() {
  rl.question('You: ', async (input) => {
    if (input.toLowerCase() === 'quit') {
      await session.close();
      rl.close();
      return;
    }

    process.stdout.write('Claude: ');
    for await (const event of session.sendStream(input)) {
      if (event.type === 'text') {
        process.stdout.write(event.text);
      }
    }
    console.log('\n');

    chat();
  });
}

chat();