Overview - Thinkwell

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";

Export	Description
`open()`	Main entry point — opens a connection to a named agent
`Agent`	The agent interface returned by `open()`
`Session`	Manages multi-turn conversations with persistent context
`Plan`	Fluent API for building prompts with tools

See Agent for the list of supported agent names.

Architecture

Thinkwell follows a layered architecture:

Agent - Establishes a connection to an AI agent via ACP. Create one with open().
Sessions - Agents support two interaction modes:
- Ephemeral: Use agent.think() for single-turn interactions
- Persistent: Use agent.createSession() for multi-turn conversations
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

​Module Structure

​Architecture

​Structured Output with @JSONSchema

​Next Steps

Module Structure

Architecture

Structured Output with @JSONSchema

Next Steps