Skip to main content
The open() function is the main entry point for Thinkwell. It connects to an AI agent (like Claude Code) and returns an Agent instance with a fluent API for blending deterministic code with LLM-powered reasoning.

​
Opening an Agent

Use open() to establish a connection to an AI agent by name.

​
Named Agents

Thinkwell provides built-in support for popular AI agents: 
import { open } from "thinkwell";

// Connect to Claude Code
const agent = await open('claude');

// Or connect to other supported agents
const codexAgent = await open('codex');
const geminiAgent = await open('gemini');
Supported agent names:
NameCommand
'claude'npx -y @zed-industries/claude-agent-acp
'codex'npx -y @zed-industries/codex-acp
'gemini'npx -y @google/gemini-cli --experimental-acp
'kiro'kiro-cli acp
'opencode'opencode acp
'auggie'auggie --acp

​
Custom Commands

You can also connect using any custom command that implements the Agent Client Protocol: 
const agent = await open({ cmd: 'my-custom-agent --acp' });

​
Connection Options

The open() function accepts optional configuration: 
const agent = await open('claude', {
  // Environment variables for the agent process
  env: {
    ANTHROPIC_API_KEY: process.env.MY_API_KEY,
  },
  // Connection timeout in milliseconds
  timeout: 30000,
});

​
Environment Variable Overrides

open() checks two environment variables before resolving the agent:
  • $THINKWELL_AGENT — an agent name: THINKWELL_AGENT=opencode thinkwell script.ts
  • $THINKWELL_AGENT_CMD — a command string: THINKWELL_AGENT_CMD="myagent --acp" thinkwell script.ts
If both are set, $THINKWELL_AGENT_CMD takes precedence. Either way, the env override applies regardless of what the script passes to open(). This lets you swap agents at runtime without changing code.

​
Ephemeral vs Persistent Sessions

Thinkwell supports two patterns for interacting with agents:

​
Ephemeral Sessions (Single-Turn)

Use agent.think() for one-off prompts that don’t need conversation history. Each call creates an ephemeral session that is automatically closed when the prompt completes. 
import { open } from "thinkwell";

/**
 * A summary of content.
 * @JSONSchema
 */
interface Summary {
  title: string;
  points: string[];
}

const agent = await open('claude');

const summary = await agent
  .think(Summary.Schema)
  .text("Summarize this document:")
  .quote(documentContent)
  .run();

console.log(summary.title);
console.log(summary.points);

agent.close();
Ephemeral sessions are ideal for:
  • Independent, self-contained tasks
  • Stateless operations that don’t need context
  • Parallel processing of multiple prompts

​
Persistent Sessions (Multi-Turn)

Use agent.createSession() for multi-turn conversations where the agent needs to remember previous interactions. 
import { open } from "thinkwell";

const agent = await open('claude');
const session = await agent.createSession({ cwd: "/my/project" });

// First turn: analyze the codebase
const analysis = await session
  .think(AnalysisSchema)
  .text("Analyze this codebase for potential issues")
  .run();

// Second turn: the agent remembers the analysis
const fixes = await session
  .think(FixesSchema)
  .text("Suggest fixes for the top 3 issues you found")
  .run();

session.close();
agent.close();
Persistent sessions are ideal for:
  • Multi-step workflows where context matters
  • Iterative refinement of results
  • Conversations that build on previous responses

​
Code Examples

​
Basic Prompt with Structured Output

import { open } from "thinkwell";

/**
 * Sentiment analysis result.
 * @JSONSchema
 */
interface Sentiment {
  /** Overall sentiment: positive, negative, or neutral */
  sentiment: "positive" | "negative" | "neutral";
  /** Confidence score from 0 to 1 */
  confidence: number;
  /** Brief explanation */
  explanation: string;
}

async function analyzeSentiment(text: string) {
  const agent = await open('claude');

  try {
    return await agent
      .think(Sentiment.Schema)
      .text("Analyze the sentiment of this text:")
      .quote(text)
      .run();
  } finally {
    agent.close();
  }
}

​
Using Custom Tools

import { open } from "thinkwell";

/**
 * A greeting message.
 * @JSONSchema
 */
interface Greeting {
  message: string;
}

const agent = await open('claude');

const greeting = await agent
  .think(Greeting.Schema)
  .text("Create a greeting appropriate for the current time of day.")
  .tool(
    "current_time",
    "Returns the current date and time.",
    async () => ({
      time: new Date().toLocaleTimeString(),
      date: new Date().toLocaleDateString(),
    })
  )
  .run();

agent.close();

​
Multi-Turn Session with Working Directory

import { open } from "thinkwell";

const agent = await open('claude');

// Create a session scoped to a specific project directory
const session = await agent.createSession({
  cwd: "/path/to/project",
  systemPrompt: "You are a helpful code review assistant.",
});

// The agent can access files relative to the working directory
const review = await session
  .think(CodeReviewSchema)
  .text("Review the main entry point of this project")
  .run();

// Follow-up questions maintain context
const details = await session
  .think(DetailSchema)
  .text("Explain more about the third issue you mentioned")
  .run();

session.close();
agent.close();

​
API Reference

​
open(name, options?)

Opens a connection to a named agent. Parameters:
ParameterTypeDescription
nameAgentNameAgent name: 'claude', 'codex', 'gemini', 'kiro', 'opencode', 'auggie'
optionsAgentOptionsOptional connection configuration
Returns: Promise<Agent>

​
open(options)

Opens a connection using a custom command. Parameters:
ParameterTypeDescription
optionsCustomAgentOptionsOptions with required cmd field
Returns: Promise<Agent> AgentOptions:
PropertyTypeDescription
envRecord<string, string>Environment variables for the agent process
timeoutnumberConnection timeout in milliseconds
CustomAgentOptions (extends AgentOptions):
PropertyTypeDescription
cmdstringThe shell command to spawn the agent process

​
agent.think(schema)

Creates a Plan for constructing a single-turn prompt. Each call creates an ephemeral session that is automatically closed when the prompt completes. Parameters:
ParameterTypeDescription
schemaSchemaProvider<Output>Defines the expected output structure
Returns: Plan<Output>

​
agent.createSession(options?)

Creates a persistent session for multi-turn conversations. Parameters:
ParameterTypeDescription
optionsSessionOptionsOptional session configuration
Returns: Promise<Session> SessionOptions:
PropertyTypeDescription
cwdstringWorking directory for the session (defaults to process.cwd())
systemPromptstringSystem prompt for the session

​
agent.close()

Closes the connection to the agent. This shuts down the conductor and invalidates any active sessions. Returns: void

​
See Also