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:
Supported agent names:

Custom Commands

You can also connect using any custom command that implements the Agent Client Protocol:

Connection Options

The open() function accepts optional configuration:

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.
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.
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

Using Custom Tools

Multi-Turn Session with Working Directory

API Reference

open(name, options?)

Opens a connection to a named agent. Parameters: Returns: Promise<Agent>

open(options)

Opens a connection using a custom command. Parameters: Returns: Promise<Agent> AgentOptions: CustomAgentOptions (extends AgentOptions):

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: Returns: Plan<Output>

agent.createSession(options?)

Creates a persistent session for multi-turn conversations. Parameters: Returns: Promise<Session> SessionOptions:

agent.close()

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

See Also