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

# Quick Start

> Quick instructions to get started with Thinkwell.

This guide will walk you through creating your first Thinkwell agent in just a few minutes.

## Installation with Homebrew (Recommended)

Homebrew is the simplest way to install Thinkwell system-wide:

```bash theme={null}
brew install dherman/thinkwell/thinkwell
```

## Manual Installation

<Tabs>
  <Tab title="macOS (Apple Silicon)">
    ```bash theme={null}
    mkdir -p ~/.local/bin
    curl -L https://github.com/dherman/thinkwell/releases/latest/download/thinkwell-darwin-arm64.tar.gz | tar -xz -C ~/.local/bin
    mv ~/.local/bin/thinkwell-darwin-arm64 ~/.local/bin/thinkwell
    ```
  </Tab>

  <Tab title="macOS (Intel)">
    ```bash theme={null}
    mkdir -p ~/.local/bin
    curl -L https://github.com/dherman/thinkwell/releases/latest/download/thinkwell-darwin-x64.tar.gz | tar -xz -C ~/.local/bin
    mv ~/.local/bin/thinkwell-darwin-x64 ~/.local/bin/thinkwell
    ```
  </Tab>

  <Tab title="Linux (ARM64)">
    ```bash theme={null}
    mkdir -p ~/.local/bin
    curl -L https://github.com/dherman/thinkwell/releases/latest/download/thinkwell-linux-arm64.tar.gz | tar -xz -C ~/.local/bin
    mv ~/.local/bin/thinkwell-linux-arm64 ~/.local/bin/thinkwell
    ```
  </Tab>

  <Tab title="Linux (x64)">
    ```bash theme={null}
    mkdir -p ~/.local/bin
    curl -L https://github.com/dherman/thinkwell/releases/latest/download/thinkwell-linux-x64.tar.gz | tar -xz -C ~/.local/bin
    mv ~/.local/bin/thinkwell-linux-x64 ~/.local/bin/thinkwell
    ```
  </Tab>
</Tabs>

## Zero-Install (Node.js)

If you don't want to install anything, you can use Thinkwell via `npx`:

```bash theme={null}
npx -y thinkwell --help
```

## Create Your First Agent

Create a new TypeScript file called `greeting.ts`:

```typescript theme={null}
import { open } from "thinkwell";

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

async function main() {
  const agent = await open('claude');
  try {
    const greeting = await agent
      .think(Greeting.Schema)
      .text("Create a friendly greeting message.")
      .run();
    console.log(greeting.message);
  } finally {
    agent.close();
  }
}
main();
```

## Run Your Script

The Thinkwell CLI can run TypeScript files directly without any compilation step:

```bash theme={null}
thinkwell greeting.ts
```

You should see a friendly greeting message printed to your console.

## Understanding the Code

Let's break down the key concepts:

### Imports

Thinkwell provides a standard npm package import:

* `thinkwell` - The main package, providing `open()`, `Agent`, and other APIs

### The @JSONSchema Pattern

The `@JSONSchema` JSDoc tag is central to how Thinkwell works. When you annotate an interface with `@JSONSchema`, Thinkwell automatically generates a JSON Schema and attaches it as a static `Schema` property:

```typescript theme={null}
/**
 * A friendly greeting.
 * @JSONSchema
 */
export interface Greeting {
  /** The greeting message */
  message: string;
}
```

This allows you to use `Greeting.Schema` when calling `agent.think()`, which tells the agent what structured output to produce. The JSDoc comments on properties become descriptions in the generated schema, helping the AI understand what each field should contain.

### Agent Lifecycle

1. **Open** - `open('claude')` connects to the AI backend by name
2. **Think** - `agent.think(Schema).text(prompt).run()` sends your prompt and returns structured output matching your schema
3. **Close** - Always close the agent when done to clean up resources

## Next Steps

Now that you have a basic agent working, explore:

* [API Overview](/api/overview) - Learn about schemas, tools, and the Plan API
* [Sessions](/api/sessions) - Create multi-turn conversations with persistent context