CLI Reference - Thinkwell

The thinkwell CLI is the primary way to run and build Thinkwell agent scripts.

Usage

thinkwell <script.ts> [args...]     # Run a TypeScript script
thinkwell run <script.ts> [args...] # Explicit run command
thinkwell init                      # Initialize thinkwell in current directory
thinkwell new <project-name>        # Create a new project in a new directory
thinkwell check                     # Type-check project (no output files)
thinkwell build                     # Compile project with @JSONSchema support
thinkwell bundle <script.ts>        # Compile to standalone executable
thinkwell --help                    # Show help message
thinkwell --version                 # Show version

Running Scripts (Zero-Config)

The simplest way to run a Thinkwell script is to pass it directly to the CLI:

thinkwell my-agent.ts

This runs your TypeScript file with native TypeScript support—no compilation step required. The CLI automatically processes @JSONSchema annotations. You can pass arguments to your script after the filename:

thinkwell my-agent.ts --input data.json --verbose

The `run` Subcommand

The explicit run subcommand is equivalent to passing a script directly:

thinkwell run my-agent.ts --input data.json

Project Setup

`thinkwell init`

Initialize thinkwell in an existing directory:

thinkwell init

This command:

Creates package.json if none exists
Adds thinkwell and typescript dependencies using the detected package manager (pnpm, yarn, or npm)

Options:

--yes, -y - Proceed without prompting for confirmation (CI-friendly)

`thinkwell new`

Create a new project in a new directory:

thinkwell new my-agent

This creates a new directory with:

package.json with thinkwell dependency
tsconfig.json for TypeScript
src/main.ts with example agent code
.gitignore
.env.example

Type Checking

`thinkwell check`

Check a project for type errors:

thinkwell check

This will essentially perform the same type checking as thinkwell build without writing any output files, which is faster for catching errors during development. In a workspace (pnpm or npm), all TypeScript packages are checked by default.

Option	Description
`-p, --package <name>`	Check a specific workspace package (can be repeated)
`--pretty`	Enable colorized output (default: true if TTY)
`--no-pretty`	Disable colorized output

Exit codes:

0 - No type errors
1 - Type errors found
2 - Configuration error

Examples

# Check the current project
thinkwell check

# Check a specific workspace package
thinkwell check -p acp

# Check multiple packages
thinkwell check -p acp -p protocol

# Disable colorized output (for CI)
thinkwell check --no-pretty

Building Projects

`thinkwell build`

Compile your TypeScript project using the standard TypeScript compiler with @JSONSchema namespace injection:

thinkwell build

This command compiles your project according to your tsconfig.json, applying @JSONSchema transformations first. Output (.js, .d.ts, source maps) is written to your configured outDir.

Option	Description
`-w, --watch`	Watch for file changes and recompile
`-p, --project <path>`	Path to tsconfig.json (default: `./tsconfig.json`)
`-q, --quiet`	Suppress all output except errors
`--verbose`	Show detailed build output

Examples

# Build the project
thinkwell build

# Watch and rebuild on changes
thinkwell build --watch

# Use a specific tsconfig
thinkwell build -p tsconfig.app.json

# Suppress success output (for CI)
thinkwell build --quiet

Configuration via package.json

Control which files receive @JSONSchema transformation:

{
  "thinkwell": {
    "build": {
      "include": ["src/**/*.ts"],
      "exclude": ["**/*.test.ts", "**/__fixtures__/**"]
    }
  }
}

Files not matched by include (or matched by exclude) are still compiled by TypeScript—they just skip @JSONSchema transformation.

Bundling Executables

`thinkwell bundle`

Compile your script into a standalone executable that can run without Node.js or Thinkwell installed:

thinkwell bundle src/agent.ts

The resulting binary includes:

Node.js 24 runtime with native TypeScript support
All thinkwell packages
Your bundled application code

Bundle Options

Option	Description
`-o, --output <path>`	Output file path (default: `./<name>-<target>`)
`-t, --target <target>`	Target platform (can be specified multiple times)
`--include <glob>`	Additional files to embed as assets
`-e, --external <pkg>`	Exclude package from bundling (can be repeated)
`-m, --minify`	Minify the bundled code for smaller output
`-w, --watch`	Watch for changes and rebuild automatically
`-n, --dry-run`	Show what would be built without building
`-q, --quiet`	Suppress all output except errors (for CI)
`-v, --verbose`	Show detailed build output

Target Platforms

Target	Description
`host`	Current platform (default)
`darwin-arm64`	macOS on Apple Silicon
`darwin-x64`	macOS on Intel
`linux-x64`	Linux on x64
`linux-arm64`	Linux on ARM64

Examples

# Bundle for current platform
thinkwell bundle src/agent.ts

# Specify output path
thinkwell bundle src/agent.ts -o dist/my-agent

# Bundle for Linux
thinkwell bundle src/agent.ts --target linux-x64

# Multi-platform build
thinkwell bundle src/agent.ts -t darwin-arm64 -t linux-x64

# Preview build without executing
thinkwell bundle src/agent.ts --dry-run

# Keep sqlite3 as external dependency
thinkwell bundle src/agent.ts -e sqlite3

# Minify for smaller binary
thinkwell bundle src/agent.ts --minify

# Watch mode for development
thinkwell bundle src/agent.ts --watch

Configuration via package.json

Set bundle defaults in your package.json:

{
  "thinkwell": {
    "bundle": {
      "output": "dist/my-agent",
      "targets": ["darwin-arm64", "linux-x64"],
      "external": ["sqlite3"],
      "minify": true
    }
  }
}

CLI options override package.json settings.

Binaries are approximately 70-90 MB due to the embedded Node.js runtime. The --minify flag reduces bundle size, though the Node.js runtime dominates the total size.

Environment Variables

Variable	Description
`THINKWELL_AGENT`	Override the agent name (see supported names)
`THINKWELL_AGENT_CMD`	Override the agent command (e.g., `myagent --acp`)
`THINKWELL_CACHE_DIR`	Override the cache directory (default: `~/.cache/thinkwell`)
`DEBUG`	Enable debug output for troubleshooting

The agent environment variables let you swap agents at runtime without modifying code. For example, a script that calls open('claude') can be run with a different agent:

# Run with OpenCode instead of Claude
THINKWELL_AGENT=opencode thinkwell my-script.ts

# Run with a custom agent command
THINKWELL_AGENT_CMD="myagent --acp" thinkwell my-script.ts

If both are set, THINKWELL_AGENT_CMD takes precedence.

Supported Agent Names

Name	Command
`claude`	`npx -y @agentclientprotocol/claude-agent-acp`
`codex`	`npx -y @zed-industries/codex-acp`
`gemini`	`npx -y @google/gemini-cli --experimental-acp`
`kiro`	`kiro-cli acp`
`opencode`	`opencode acp`
`auggie`	`auggie --acp`

​Usage

​Running Scripts (Zero-Config)

​The run Subcommand

​Project Setup

​thinkwell init

​thinkwell new

​Type Checking

​thinkwell check

​Examples

​Building Projects

​thinkwell build

​Examples

​Configuration via package.json

​Bundling Executables

​thinkwell bundle

​Bundle Options

​Target Platforms

​Examples

​Configuration via package.json

​Environment Variables

​Supported Agent Names

Usage

Running Scripts (Zero-Config)

The `run` Subcommand

Project Setup

`thinkwell init`

`thinkwell new`

Type Checking

`thinkwell check`

Examples

Building Projects

`thinkwell build`

Examples

Configuration via package.json

Bundling Executables

`thinkwell bundle`

Bundle Options

Target Platforms

Examples

Configuration via package.json

Environment Variables

Supported Agent Names