Skip to main content
Thinkwell provides a TypeScript API for integrating AI agents into your applications. The library connects to AI coding agents via the Agent Client Protocol (ACP) and provides a fluent interface for building prompts, managing sessions, and handling typed responses.

​
Module Structure

Thinkwell exports everything from a single package: 
import { open } from "thinkwell";
import type { Agent, Session } from "thinkwell";
ExportDescription
open()Main entry point — opens a connection to a named agent
AgentThe agent interface returned by open()
SessionManages multi-turn conversations with persistent context
PlanFluent API for building prompts with tools
See Agent for the list of supported agent names.

​
Architecture

Thinkwell follows a layered architecture:
  1. Agent - Establishes a connection to an AI agent via ACP. Create one with open().
  2. Sessions - Agents support two interaction modes:
    • Ephemeral: Use agent.think() for single-turn interactions
    • Persistent: Use agent.createSession() for multi-turn conversations
  3. Plan - A fluent API for constructing prompts. Chain methods to build content, then call .run() to execute.

​
Structured Output with @JSONSchema

Thinkwell uses the @JSONSchema JSDoc tag to define expected AI output structures. The CLI generates JSON Schemas from your TypeScript interfaces at build time: 
/**
 * Analysis result from code review.
 * @JSONSchema
 */
export interface AnalysisResult {
  /** List of issues found */
  issues: Array<{
    severity: "low" | "medium" | "high";
    description: string;
  }>;
  /** Overall summary */
  summary: string;
}

// The schema is available as a static property
const result = await agent.think(AnalysisResult.Schema).text("...").run();
JSDoc comments become description fields in the generated schema, helping the AI understand what each field should contain.

​
Next Steps

  • Agent - Opening agents, named agents, and managing sessions
  • Plan - Building prompts with the fluent API
  • Sessions - Multi-turn conversations