> ## Documentation Index
> Fetch the complete documentation index at: https://thinkwell.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Overview of the Thinkwell API.

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:

```typescript theme={null}
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](/api/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:

```typescript theme={null}
/**
 * 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](/api/agent) - Opening agents, named agents, and managing sessions
* [Plan](/api/plan) - Building prompts with the fluent API
* [Sessions](/api/sessions) - Multi-turn conversations